Managing secrets

Users might need to access secrets generated by the Coordinator or pass in secrets to MarbleRun themselves.

For example, an application might require an access token, to establish secure connections to an external service. While setting the token directly in the manifest is an option, this would mean exposing the confidential token to everyone with access to the manifest.

For such cases, MarbleRun allows predefined users to upload secrets that have been predefined in the manifest. Similarly, predefined users can retrieve particular secrets from the Coordinator via the /secrets endpoint.

Reading a secret

Authorized users can use the client API to read secrets in JSON format.

For example, the following command requests a secret named symmetricKeyShared:

marblerun secret get symmetricKeyShared $MARBLERUN --cert=admin-cert.pem --key=admin-key.pem --era-config=era.json

If the user has the required permissions, the secret is returned:

symmetricKeyShared:
	Type:          symmetric-key
	UserDefined:   false
	Size:          128
	Key:           uVGpoJZTRICLccJiVNt9jA==

Setting a secret

A user can upload secrets via the HTTP REST API in JSON format. The secrets need to be marked as UserDefined.

For secrets of the types cert-rsa, cert-ecdsa and cert-ed25519 the CLI supports directly uploading a PEM encoded certificate and key from a file. Take for example the secret_file.pem containing a certificate and corresponding private key:

-----BEGIN CERTIFICATE-----
MIICpjC ... zrNxzg==
-----END CERTIFICATE-----

-----BEGIN PRIVATE KEY-----
MIICeAI ... 8bu8Z+Fe
-----END PRIVATE KEY-----

The CLI will look for the first instance of an encoded certificate and/or key in the file, perform a conversion to JSON format, and upload them to the Coordinator. The name of the secret you are trying to set is specified using the --from-pem flag.

The following command uploads the key and certificate pair stored in the secret_file.pem as a secret named user-certificate:

marblerun secret set secret_file.pem $MARBLERUN --from-pem user-certificate --cert=admin-cert.pem --key=admin-key.pem --era-config=era.json

To upload different types, or a batch of secrets, a file with the secrets in JSON format is needed. Each entry in the file is a JSON object labeled by the name of the secret and contains values depending on its type:

• For the types cert-rsa, cert-ecdsa and cert-ed25519:
  • Cert: A PEM encoded certificate. To preserve newlines correctly set Cert to the output of the following command:

    echo -n $(cat <secret_certificate>.pem | sed '1,1d;$ d' | awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}')
  • Private: A PEM encoded private key. This may be omitted. To preserve newlines correctly set Private to the output of the following command:

    echo -n $(cat <secret_private_key>.pem | sed '1,1d;$ d' | awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}')
• For type symmetric-key:
  • Key: a base64 encoded key, with length matching the size defined in the original manifest
• For the type plain:
  • Key: arbitrary data in base64 encoding. This may be a key of unspecified length, a confidential config file, or any kind of data only some Marbles and/or users should have access to.

The following gives an example for a file to set the secrets userDefinedSymmetricKey, userDefinedCert, and genericSecret:

{
  "userDefinedSymmetricKey": {
    "Key": "AAECAwQFBgcICQoLDA0ODw=="
  },
  "userDefinedCert": {
    "Cert": "MIIBjDCCATOgAwIBAgICBTkwCgYIKoZIzj0EAwIwMjEwMC4GA1UEAxMnTWFyYmxlcnVuIENvb3JkaW5hdG9yIC0gSW50ZXJtZWRpYXRlIENBMB4XDTIxMDYxNTA4NTY0M1oXDTIxMDYyMjA4NTY0M1owLTEcMBoGA1UEAxMTTWFyYmxlcnVuIFVuaXQgVGVzdDENMAsGA1UEBRMEMTMzNzAqMAUGAytlcAMhAEPOc066G5XmvLizOKTENSR+U9lv3geZ0/a2+XkhJRvDo20wazAOBgNVHQ8BAf8EBAMCAoQwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwLAYDVR0RBCUwI4IJbG9jYWxob3N0hwR/AAABhxAAAAAAAAAAAAAAAAAAAAABMAoGCCqGSM49BAMCA0cAMEQCIGOlRcynaPaj/flSr2ZEvmTmhuvtmTb4QkwPFtxFz3EJAiB77ijxAcJNxPKcKmgMB+c8NORC+6N/St2iP/oX/vqQvg==",
    "Private": "MC4CAQAwBQYDK2VwBCIEIPlmAOOhAStk8ytxzvekPr8zLaQa9+lxnHK+CizDrMds"
  },
  "genericSecret": {
    "Key": "SGVsbG8gZnJvbSB0aGUgTWFyYmxlcnVuIERvY3MhCg=="
  }
}

This file can then be uploaded using the CLI and the users credentials:

marblerun secret set secret_file.json $MARBLERUN --cert=admin-cert.pem --key=admin-key.pem --era-config=era.json

Subsequently, the secrets can be accessed by marbles and authorized users. If the user lacks permission to set one of the secrets, or a secret the user tried to upload was malformed an error occurs instead.