Managing secrets

In some cases 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 potentially 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 symmetric_key_shared:

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

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

	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. Take for example this file containing a certificate and corresponding private key:

MIICpjC ... zrNxzg==

MIICeAI ... 8bu8Z+Fe

The following command sets this certificate as a secret named user-certificate:

marblerun secret set secret_file.pem $MARBLERUN --from-pem user-secret --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 user_defined_symmetric_key, user_defined_cert, and generic_secret:

  "user_defined_symmetric_key": {
    "Key": "AAECAwQFBgcICQoLDA0ODw=="
  "user_defined_cert": {
    "Private": "MC4CAQAwBQYDK2VwBCIEIPlmAOOhAStk8ytxzvekPr8zLaQa9+lxnHK+CizDrMds"
  "generic_secret": {
    "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.