CDNI Protected Secrets Metadata

Introduction Certain objects in both the FCI and MI interfaces encapsulate sensitive values, such as credentials and access keys, which should not necessarily be accessible to all parties that can view the advertisement and configuration payloads. This document defines two mechanisms to enclose secret values in the context of other FCI and MI objects that may only be viewed by the intended recipients, including embedded secrets encrypted using a certificate supplied by a counterparty and secrets stored in an external service (support defined in this draft is specifically for HashiCorp Vault), which are accessed via a specified path and a key ID. Refer to documentation for details. Either side can share secrets, and the functionality is the same for both sides, so the FCI capabilities are wrappers around the MI objects, similar to how FCI footprints (used in ) reutilize the MI.Footprint and registry defined in The public certificate for the downstream content delivery network (dCDN) is shared via FCI.SecretCertificate and the certificate for the upstream content delivery network (uCDN) is shared via MI.SecretCertificate. Overview of the workflow for embedded secrets:

uCDN retrieves an advertisement with FCI.SecretStore and FCI.SecretCertificate. As the uCDN has not yet provided a certificate, any embedded secret values in the advertisement are omitted; the dCDN is not yet able to encrypt the secrets, so no secrets are present.
uCDN provides configuration including MI.SecretStore and MI.SecretValue with values encrypted using the dCDN certificate.
uCDN receives an updated capabilities advertisement; having provided an MI.SecretCertificate, the advertisement SHOULD now contain populated MI.SecretValue objects if secret values are utilized, encrypted with the provided certificate.

| | | |---- | | | Encrypt secrets using provided FCI.SecretCertificate | |<--- | | | | Provide encrypted secrets via MI.SecretValue | |--------------------------------------------------------------->| | | | Provide MI.SecretStore and MI.SecretCertificate | |--------------------------------------------------------------->| | | | ----| | Encrypt secrets using provided MI.SecretCertificate | | | --->| | | | Retrieve FCI.SecretValue with encrypted secrets | |--------------------------------------------------------------->| | | ┌────┐ ┌────┐ │uCDN│ │dCDN│ └────┘ └────┘ ]]> Detailed workflow examples, including modes that reference external services or contain secret values in plaintext, are available in the Workflow Examples section. The MI.SecretValue objects are utilized in the FCI and MI interfaces, where secrets must be referenced. Certificates can be validated based on signatures in production environments, and self-signed certificates can be accepted in testing/lab environments. With this model, no out-of-band communication is required to share secrets.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Metadata Objects

MI.SecretStore MI.SecretStore instructs the counterparty how to dereference the value of any MI.SecretValue objects linked to the store. For embedded stores, MI.SecretStore identifies the certificate used for encrypting the values. For external stores (e.g., HashiCorp Vault), MI.SecretStore specifies the service endpoint that SHOULD be used in conjunction with the MI.SecretValue key path to obtain the secure data. Property: secret-store-id

Description: An identifier for this store configuration that is referenced from linked MI.SecretValue objects. This value MUST be unique within the context of the metadata objects and the FCI advertisement.
Type: String
Mandatory-to-Specify: Yes

Property: secret-store-type

Description: A type discriminator for the configuration object, this property specifies whether the linked MI.SecretValue objects contain embedded secret objects or reference an external store.
Type: String. Either "MI.SecretStoreTypeEmbedded" or "MI.SecretStoreTypeHashiCorpVault".
Mandatory-to-Specify: Yes

Property: secret-store-config

Description: The appropriate configuration object for the specified store type.
Type: Object, with type specified by the secret-store-type property.
Mandatory-to-Specify: Yes

MI.SecretStoreTypeEmbedded MI.SecretStoreTypeEmbedded contains the configuration necessary to decrypt embedded secrets in MI.SecretValue. The only currently supported encrypted message format is Cryptographic Message Syntax (CMS) as defined in Messages MUST be CMS type "EnvelopedData". Messages MUST be encoded as Base64 per section 4 of Messages MAY also be optionally formatted with encapsulation boundaries as per It is strongly preferred to utilize the message formatting when capable. A cleartext format is also defined for testing purposes. In this case, the value of an MI.SecretValue object's secret-value property is the cleartext secret. It is NOT RECOMMENDED to use the cleartext format in production environments. Property: format

Description: The format of the embedded encrypted message.
Type: String. Either "cms" or "cleartext".
Mandatory-to-Specify: Yes

Property: secret-certificate-id

Description: The ID of the MI.SecretCertificate used to encrypt secret messages linked with this store configuration.
Type: String
Mandatory-to-Specify: Yes when format is "cms", otherwise No.

The following is an example of MI.SecretStoreTypeEmbedded specifying use of CMS:

MI.SecretStoreTypeHashiCorpVault MI.SecretStoreTypeHashiCorpVault contains the configuration necessary to reference secrets stored in an external instance of a HashiCorp Vault KV store . MI.SecretValue objects reference secrets stored in the Vault using the secret-path property to identify the path and property key. See the MI.SecretValue section for details. Property: endpoint

Description: The base URL of the Vault instance.
Type: String
Mandatory-to-Specify: Yes

Property: namespace

Description: The Vault namespace in which secret lookups should be performed.
Type: String
Mandatory-to-Specify: Yes

Property: version

Description: The Vault KV version.
Type: Integer. Valid values: 1 or 2.
Mandatory-to-Specify: Yes

The following is an example of MI.SecretStoreTypeHashiCorpVault specifying a version KV-V1 Vault:

The following is an example of MI.SecretStoreTypeHashiCorpVault specifying a version KV-V2 Vault:

MI.SecretValue MI.SecretValue may be used in any FCI or MI object where sensitive data must be transmitted only to intended recipients. Only one of secret-value or secret-path MUST be specified, depending on the store type. Property: secret-store-id

Description: The ID of MI.SecretStore that contains the configuration defining how to decrypt or access the referenced secret.
Type: String
Mandatory-to-Specify: Yes

Property: secret-value

Description: Used only for embedded secrets. Format is one of the following:
- The cleartext string
- The PEM encoded or Base64 encoded value of a CMS message. If the message begins with an pre-encapsulation boundary of "---BEGIN CMS---", the message MUST be decoded according to If no pre-encapsulation boundary is present, the message MUST be decoded as per section 4 of Future versions of this specification will deprecate support for plain encoding.
Type: String
Mandatory-to-Specify: Yes, if secret-path is not specified.

Property: secret-path

Description: Used only for HashiCorp Vault secrets, the path, not including namespace, to the secret, including the key of the particular property to access as the last path parameter.
Type: String
Mandatory-to-Specify: Yes, if secret-value is not specified.

Property: timeout

Description: If this property is present and the elapsed time since last retrieving the secret value has exceeded this timeout, any cached instance of this secret value MUST be discarded and fetched again from the associated secret store. This value has no effect when using an embedded store.
Type: Integer duration in seconds.
Mandatory-to-Specify: No

The following is an example of MI.SecretValue specifying an embedded value:

The following is an example of MI.SecretValue for a Vault:

MI.SecretCertificate MI.SecretCertificate is used to share an certificate to be utilized for encrypting embedded secret messages. In lab and testing environments, this certificate MAY be self-signed, depending on participant agreement. In production environments, this SHOULD be a certificate signed by an appropriate certificate authority (CA) and validated by the counterparty. Property: certificate-id

Description: A unique ID for this certificate that can be referenced from a corresponding MI.SecretStore configuration defined by a counterparty.
Type: String
Mandatory-to-Specify: Yes

Property: certificate-value

Description: The PEM encoded OR Base64 encoded certificate.If the value begins with an pre-encapsulation boundary of "---BEGIN CERTIFICATE---", the message MUST be decoded according to If no pre-encapsulation boundary is present, the message MUST be decoded as per section 4 of Future versions of this specification will deprecate support for plain encoding.
Type: String
Mandatory-to-Specify: Yes

The following is an example of MI.SecretCertificate:

Capabilities Objects These objects are simple capability wrappers around the MI objects defined in this specification.

FCI.SecretStore FCI.SecretStore instructs the uCDN how to dereference the value of any MI.SecretValue objects linked to the store from other FCI objects via an embedded MI.SecretValue object. For further details, see the MI.SecretStore section. The following is an example of FCI.SecretStore:

FCI.SecretCertificate FCI.SecretCertificate is used to share an certificate to be utilized for encrypting embedded secret messages via an embedded MI.SecretCertificate object. For further details, see the MI.SecretCertificate section. The following is an example of FCI.SecretCertificate:

Workflow Examples The facilities in this document can be used for simple and bidirectional exchange of secret values between uCDN and dCDN participants in an Open Caching system. The embedded model provides for a secret exchange without reference to out-of-band services, while the Vault support allows for external reference to secrets stored in a HashiCorp Vault. Participants utilizing a secret distribution method or service not supported here MAY define a Private Feature MI object with the necessary configuration for that method or service and then utilize that MI object within MI.SecretStore and FCI.SecretStore Provided below are workflow examples for uCDN -> dCDN and dCDN -> uCDN exchanges of secret values. Consideration is needed when addressing key rollover, expiration, and revocation in the embedded model. The RECOMMENDED workflow for key rollover is as follows:

When the recipient of a secret provides an updated configuration that no longer contains an MI.SecretCertificate with an ID referenced in an MI.SecretStore used by MI.SecretValue objects, those MI.SecretValue objects SHOULD be reduced to an object with no contained secret-value or secret-path property as they would be in the initial state before any certificate had been provided.
If the recipient of a secret then provides a new MI.SecretCertificate object, the sender of the secret SHOULD update its MI.SecretStore to reference the new certificate-id and then update any referencing MI.SecretValue objects to include an updated secret-value property that contains the newly encrypted values.

Workflow: dCDN -> uCDN Embedded

The dCDN advertises FCI.SecretStore with a store-type of MI.SecretStoreTypeEmbedded; other FCI objects may contain MI.SecretValue objects that reference the store-id. MI.SecretValue objects do not presently contain a secret-value property.
The uCDN pushes the MI configuration with an MI.SecretCertificate.
The dCDN updates the advertised FCI.SecretStore with a certificate-id property that references the dCDN MI.SecretCertificate; any MI.SecretValue objects in other FCI objects now contain a secret-value property with the CMS encrypted secret.

| | | | Provide MI.SecretCertificate | |--------------------------------------------------------------->| | | | ----| | Encrypt secrets using provided MI.SecretCertificate | | | --->| | | | Retrieve FCI.SecretValue with encrypted secrets | |--------------------------------------------------------------->| | | ┌────┐ ┌────┐ │uCDN│ │dCDN│ └────┘ └────┘ ]]>

Workflow: uCDN -> dCDN Embedded

The dCDN advertises an FCI.SecretCertificate.
The uCDN pushes the MI configuration containing MI.SecretStore with a store-type of MI.SecretStoreTypeEmbedded and a certificate-id referencing the FCI.SecretCertificate advertised by the uCDN. Other MI objects may contain MI.SecretValue objects with a secret-value property containing the CMS encrypted secret.

| | | |---- | | | Encrypt secrets using provided FCI.SecretCertificate | |<--- | | | | Provide MI.SecretStore and MI.SecretValue objects | |--------------------------------------------------------------->| | | ┌────┐ ┌────┐ │uCDN│ │dCDN│ └────┘ └────┘ ]]>

Workflow: Embedded Cleartext (uCDN and dCDN)

An MI.SecretStoreTypeEmbedded has a defined format of "cleartext".
Any MI.SecretValue objects that reference the cleartext store contain a secret-value property with the unencrypted secret.

| | | | Provide MI.SecretStore ("cleartext") and MI.SecretValue | |--------------------------------------------------------------->| | | ┌────┐ ┌────┐ │uCDN│ │dCDN│ └────┘ └────┘ ]]>

Workflow: dCDN -> uCDN Vault The dCDN advertises an FCI.SecretStore with an appropriate configuration for accessing an instance of a HashiCorp Vault accessible to the uCDN. Other FCI objects may contain MI.SecretValue objects that reference the FCI.SecretStore and a secret-path property specifying the secret to retrieve.

| | | | | | Retrieve secrets using path provided | | | in FCI.SecretValue objects | | |----------------------------------------------------|---------->| | | | ┌────┐ ┌─────┐ ┌────┐ │uCDN│ │Vault│ │dCDN│ └────┘ └─────┘ └────┘ ]]>

Workflow: uCDN -> dCDN Vault The uCDN provides the MI configuration, including an MI.SecretStore with appropriate configuration for accessing an instance of a HashiCorp Vault accessible to the dCDN. Other MI objects may contain MI.SecretValue objects that reference the MI.SecretStore and a secret-path property specifying the secret to retrieve.

The FCI and MI objects defined in this document are transferred via the interfaces defined in CDNI which describes how to secure these interfaces by protecting integrity and confidentiality while ensuring the authenticity of the dCDN and uCDN.

This document requests the registration of the following entries under the "CDNI Payload Types" registry hosted by IANA: CDNI Payload Types

Payload Type	Specification
MI.SecretStore	RFCthis
MI.SecretStoreTypeEmbedded	RFCthis
MI.SecretStoreTypeVault	RFCthis
MI.SecretValue	RFCthis
MI.SecretCertificate	RFCthis
FCI.SecretStore	RFCthis
FCI.SecretCertificate	RFCthis

The authors would like to express their gratitude to the members of the Streaming Video Technology Alliance Open Caching Working Group for their contributions and guidance. The following people contributed to the content of this draft:

Chris Lemmons (Comcast)
Rajeev RK (picoNETS)
Yoav Gressel (Qwilt)
Arnon Warshavsky (Qwilt)
Alfonso Siloniz (Telefonica)