This serves as a reference of all features that this change affects.
| Feature |
|---|
| Encrypted Data Key |
| AWS KMS Keyring |
| Raw AES Keyring |
| Raw RSA Keyring |
| Keyring Decryption Contract |
This serves as a reference of all specification documents that this change affects.
| Specification |
|---|
| Structures |
| Keyring Interface |
| AWS KMS Keyring |
| Raw AES Keyring |
| Raw RSA Keyring |
The scope of this change only affects the specification. Follow-up changes that define whether implementations expose these concepts MAY affect implementations.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
We have referenced several terms throughout various specification documents that are never defined: "key namespace", "key name", "key provider ID", and "key provider info". This change defines each of these terms and describes their relationships to each other and the keyrings they represent.
-
Whether, or how, each keyring exposes any of these values at runtime is out of scope.
-
Specific values for these terms for any specific keyring is out of scope.
Various specification documents reference "key namespace", "key name", "key provider ID", and "key provider info", but we never define what these terms mean or how they relate to each other.
In order to ensure the specification documents accurately describe keyring behavior, we need to define all terms that they use.
This change SHOULD NOT introduce any drawbacks. It is identifying and describing terms that already exist and the existing relationship between them.
This change SHOULD NOT have any security implications.
This change SHOULD NOT have any operational implications.
Key namespace and key name are configuration values that determine the behavior of a keyring.
Key provider ID and key provider info are values that identify the keyring configuration that can fulfill the keyring's decryption contract. The keyring attaches these values to a data key ciphertext to form an encrypted data key.
"Key namespace", "key name", "key provider ID", and "key provider info" are all concepts that identify a wrapping key.
A configuration value for a keyring that identifies the grouping or categorization for the wrapping keys that keyring can access.
The key namespace MUST be a string value.
A configuration value for a keyring that identifies a single wrapping key within a key namespace.
The key name MUST be a string value.
An output value returned by a keyring on encrypt as part of an encrypted data key structure that identifies the grouping or categorization for a keyring that can fulfill this decryption contract.
The key provider ID MUST be a binary value and SHOULD be equal to a UTF-8 encoding of the key namespace.
An output value returned by a keyring on encrypt as part of an encrypted data key structure that provides necessary information for a keyring to fulfill this decryption contract.
The key provider info MUST be a binary value and SHOULD be equal to a UTF-8 encoding of the key name.
One example of a keyring where the key name and key provider info can differ is the AWS KMS keyring. This keyring uses its key name to identify the desired CMK in its call to AWS KMS. However, the key provider info that this keyring writes is the CMK identifier that AWS KMS includes in its response. If the key name is a CMK ARN, these two values are identical because this response value is always the CMK ARN of the CMK that AWS KMS used. However, if the key name is some other valid CMK identifier, such as an alias, then they are different.