Sealed Secret

A secret is data that should only be readable by the intended parties. When a secret is sealed to an ACL of one or more enclave identities, the encrypted secret is only decryptable by enclaves whose identities match that ACL expectation.

AeadScheme

Name Description
UNKNOWN_AEAD_SCHEME
AES128_GCM
AES256_GCM
AES128_GCM_SIV
AES256_GCM_SIV

SealedSecret

A self-contained payload containing an encrypted secret and metadata describing how to decrypt and use the secret.

Field Type Description Required
iv bytes

Initialization vector used by the AEAD scheme used for encrypting the secret. The size of the IV depends on the cipher suite used for the encryption (which may be included in the SealingRootInformation::additional_info field).

No
sealed_secret_header bytes

Serialized SealedSecretHeader. The header is included in its serialized form to enable deterministic MAC computation.

No
additional_authenticated_data bytes

Data whose integrity and authenticity are verifiable.

No
secret_ciphertext bytes

Ciphertext as computed by an appropriate AEAD scheme.

No
sealing_root_bookkeeping_info bytes

Bookkeeping information for the sealing root. This information is strictly optional, and has no meaning for the client.

No

SealedSecretHeader

Describes the purpose and intent of an already-sealed secret.

Field Type Description Required
secret_name string

Name of the secret. This is an arbitrary, user-defined string. The SecretSealer does not associate any meaning with this value.

Users of the SecretSealer interface are expected to populate this field.

No
secret_version string

Version of the secret. This is an arbitrary user-defined string. The SecretSealer does not associate any meaning with this value.

Users of the SecretSealer interface are expected to populate this field.

No
secret_purpose string

Purpose of the secret. This is an arbitrary, user-defined string. The SecretSealer does not associate any meaning with this value.

Users of the SecretSealer interface are expected to populate this field.

No
root_info SealingRootInformation

Information about the sealing root.

SecretSealer::SetDefaultHeader() must populate this field.

No
author EnclaveIdentity[]

An optional list of identities belonging to the author of the sealed secret.

The SecretSealer::Seal() and SecretSealer::Reseal() methods must populate this field.

No
client_acl IdentityAclPredicate

ACL consisting of the enclave-identity expectations that are allowed to access this secret.

SecretSealer::SetDefaultHeader() must populate this field.

No
secret_handling_policy bytes

Policy that the client is expected to enforce on the unwrapped secret. secret_handling_policy is an opaque field, and its interpretation is specific to the client and/or secret.

User of the SecretSealer interface is expected to populate this field.

No

SealingRootInformation

Represents information about a sealing root. This information is used by the program to instantiate the correct implementation of the SecretSealer interface.

Field Type Description Required
sealing_root_type SealingRootType

Type of the sealing root. When combined with sealing_root_name, it uniquely identifies the SecretSealer responsible for handling the associated secrets.

No
sealing_root_name string

Name of the sealing root. The sealing_root_name is an arbitrary, UTF-8 string, with the only restriction that it may not contain the character ‘#’.

No
sealing_root_acl IdentityAclPredicate

ACL consisting of enclave-identity expectations for a sealing root of type REMOTE. For such a root, the SecretSealer ensures that the remote root’s set of enclave identities set satisfies sealing_root_acl.

No
additional_info bytes

Additional information. The additional_info field is an opaque field that is used by the SecretSealer to wrap and unwrap the secrets correctly. Some example uses of this field include:

  • Keeping track of the SVN (Security Version Number) of the root.
No
aead_scheme AeadScheme

The AEAD scheme used for wrapping the secrets. Previously, the |additional_info| field was suggested as a place to store this value.

No

SealingRootType

A type of sealing root.

Name Description
LOCAL

Indicates that the secret is sealed to a machine-local (e.g., CPU-based) sealing root.

REMOTE

Indicates that the secret is sealed to a remote-service-based sealing root (e.g., a secret-escrow service).

UnsealedSecret

A disassembled SealedSecret. It contains all information necessary to reseal the data.

Field Type Description Required
secret_header SealedSecretHeader

The secret’s header. It encapsulates information about the secret and information about how to seal it.

No
additional_authenticated_data bytes

Data associated with the secret. When the secret is sealed using an AEAD scheme, this data should be provided as the associated data.

No
secret_plaintext bytes

A plaintext secret.

No