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 our setting a manifest hands-on. Specifically, the Coordinator provides the following to Marbles.

Virtual sealing keys

A key feature of Intel SGX is that it allows enclave software to derive so-called “sealing keys”. Generally, sealing keys are unique for a given enclave software/processor combination. Upon request from an enclave, the processor will deterministically derive the enclave’s sealing key using a recipe somewhat reminiscent of the following: hash(cpu_secret, hash(enclave_software), hash(enclave_parameters), ...). Enclave software uses sealing keys to encrypt data and persist it to the local disk. This process is also referred to as “sealing”. Sealing enables enclave software to persist sensitive data locally between restarts, e.g., after crashes or system reboots.

Crucially, in SGX, the aforementioned cpu_secret is hard-wired in silicon and is unique per physical processor. Thus, sealing keys do no commute between processors. Particularly in cloud settings, this becomes a problem: if a VM is scheduled on a different host, enclaves running within that VM cannot unseal their local data anymore, because the host’s cpu_secret has changed.

To solve this problem, the Coordinator generates “virtual sealing keys” for Marbles. After successful validation of a Marble, the Coordinator injects a Marble’s virtual sealing key through the {{ hex .Marblerun.SealKey }} placeholder in the Parameters section of the Manifest.

The Coordinator derives virtual sealing keys from respective Marble’s ID and a master secret only known to the Coordinator using the HKDF scheme. The ID is a public 128-bit value randomly generated by each Marble for itself upon startup and persisted in plaintext on local storage. Consequently, two Marbles could end up with the same ID and virtual sealing key under certain circumstances. The security implications of this need to be taken into account when using virtual sealing keys. For example, when using virtual sealing keys with AES-GCM, one must only use cryptographically random nonces.

Shared symmetric keys

While virtual sealing keys are used by individual Marbles, Marblerun also allows for the sharing of symmetric encryption keys between Marbles via placeholders in the Manifest. The Coordinator creates these keys once and provides them as parameters to corresponding Marbles. Marbles can use shared keys for a variety of tasks, including the bulk encryption of shared data.

As with virtual sealing keys, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.

TLS credentials

The Coordinator will generate a private TLS key for each new Marble and issue a corresponding X.509 certificate. Both are injected through placeholders in the Manifest. The certificate is signed by the Coordinator’s root CA. Marbles use their TLS credentials 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.


A Marble always receives fresh TLS credentials after a restart.