Secrets management
The generation and the management of cryptographic keys and certificates for Marbles (i.e., containers running enclaves) are central duties of the Coordinator. Keys and certificates are passed to Marbles on startup via placeholders defined in the manifest. You can learn more about this mechanism in the Secrets section from our manifest definition hands-on. Specifically, the Coordinator provides the following to Marbles.
Symmetric keys
MarbleRun allows you to define symmetric keys that are generated by the Coordinator and distributed to your Marbles. Such keys can either be shared among Marbles or individually generated for each instance. This is useful whenever data needs to leave the protected memory of your enclave, hence, needs to be encrypted. For example, when sharing data between multiple Marbles or storing data on the disk.
To pass the generated keys to your application, you can use a template placeholder definition like {{ raw .Secrets.MySecretKey }} in your manifest. Those templates can be utilized when specifying files and environment variables for your application. From these locations, your application can retrieve the generated secret keys at runtime and use them for cryptographic purposes.
If you use one key throughout multiple Marbles, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.
Certificates
Upon launch of a Marble, the Coordinator will generate TLS credentials for each new Marble in the form of a private key and a corresponding X.509 certificate. The certificate is signed with the Coordinator's intermediate CA. These TLS credentials represent the notion of identity used for authentication in MarbleRun. Marbles can use this certificate to establish secure communication channels with other Marbles and external clients (i.e., users of your app). Clients only need to verify the Coordinator's root CA once before they can securely communicate with any Marble, as is described in more detail in our verification hands-on. By default, they're available to your application via the environment variables MARBLE_PREDEFINED_MARBLE_CERTIFICATE_CHAIN and MARBLE_PREDEFINED_PRIVATE_KEY. In addition, you can expose them via custom environment variables or files by defining template placeholders such as {{ pem .MarbleRun.MarbleCert.Cert }} or {{ pem .MarbleRun.MarbleCert.Private }} in the manifest.
Next to the default credentials, you can use Secrets to define custom certificates in your manifest. These are also generated upon each launch of your Marble and signed by the Coordinator's intermediate CA. You can include them into environment variables or files via placeholders such as {{ pem .Secrets.MySecretCertificate }} in your manifest.
Certificate secrets are always regenerated upon launch of a Marble, making them not suitable for certificate pinning.
User-defined secrets
In addition to secrets generated by the Coordinator, MarbleRun also allows you to define secrets that can be uploaded and updated after the initial deployment of your manifest. This can be used to store sensitive data, such as passwords, tokens, certificates, or other types of credentials that shouldn't be stored in the manifest directly. They can be injected via the placeholders in the same way as other secret types. Changes to user-defined secrets are logged and can be audited over via the /update or /secrets HTTP REST API endpoint of the Coordinator. You can learn more about this in the section about Managing secrets.