Skip to content

Commit 4cdeaa6

Browse files
mattsb42-awsaciocMatthewBennington
authored
docs: add change doc to describe key namespaces, names, provider IDs, and provider info (#135)
* docs: add change doc to describe key namespaces, names, provider IDs, and provider info * docs: clarify operational implications of change * docs: define types for wrapping key identifiers and tighten relationships * docs: define wrapping key identifiers - add wrapping key identifier definitions to keyring interface - remove key name and key namespace definitions from raw keyring documents and link to definitions in interface * docs: reword provider ID/info definitions to refer to ESDK as decryption contract * docs: clarify "key" provider id/info * docs: consolidate key provider id/info definitions * docs: apply suggestions from code review Co-authored-by: Alex Cioc <[email protected]> Co-authored-by: MatthewBennington <[email protected]> Co-authored-by: Alex Cioc <[email protected]> Co-authored-by: MatthewBennington <[email protected]>
1 parent b2c9944 commit 4cdeaa6

File tree

5 files changed

+214
-60
lines changed

5 files changed

+214
-60
lines changed

‎changes/2020-06-09_wrapping-key-identifiers/change.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Clarify Wrapping Key Identifiers
5+
6+
## Affected Features
7+
8+
This serves as a reference of all features that this change affects.
9+
10+
| Feature |
11+
| --------------------------------------------------------------------------------------------------- |
12+
| [Encrypted Data Key](../../framework/structures.md#encrypted-data-key) |
13+
| [AWS KMS Keyring](../../framework/kms-keyring.md) |
14+
| [Raw AES Keyring](../../framework/raw-aes-keyring.md) |
15+
| [Raw RSA Keyring](../../framework/raw-rsa-keyring.md) |
16+
| [Keyring Decryption Contract](https://github.com/awslabs/aws-encryption-sdk-specification/pull/131) |
17+
18+
## Affected Specifications
19+
20+
This serves as a reference of all specification documents that this change affects.
21+
22+
| Specification |
23+
| --------------------------------------------------------- |
24+
| [Structures](../../framework/structures.md) |
25+
| [Keyring Interface](../../framework/keyring-interface.md) |
26+
| [AWS KMS Keyring](../../framework/kms-keyring.md) |
27+
| [Raw AES Keyring](../../framework/raw-aes-keyring.md) |
28+
| [Raw RSA Keyring](../../framework/raw-rsa-keyring.md) |
29+
30+
## Affected Implementations
31+
32+
The scope of this change only affects the specification.
33+
Follow-up changes that define
34+
whether implementations expose these concepts
35+
MAY affect implementations.
36+
37+
## Definitions
38+
39+
### Conventions used in this document
40+
41+
The key words
42+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
43+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
44+
in this document are to be interpreted as described in
45+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
46+
47+
## Summary
48+
49+
We have referenced several terms throughout various specification documents
50+
that are never defined:
51+
"key namespace",
52+
"key name",
53+
"key provider ID",
54+
and "key provider info".
55+
This change defines each of these terms
56+
and describes their relationships to each other
57+
and the keyrings they represent.
58+
59+
## Out of Scope
60+
61+
- Whether, or how, each keyring exposes any of these values at runtime is out of scope.
62+
63+
- Specific values for these terms for any specific keyring is out of scope.
64+
65+
## Motivation
66+
67+
Various specification documents reference
68+
"key namespace",
69+
"key name",
70+
"key provider ID",
71+
and "key provider info",
72+
but we never define what these terms mean
73+
or how they relate to each other.
74+
75+
In order to ensure the specification documents accurately describe keyring behavior,
76+
we need to define all terms that they use.
77+
78+
## Drawbacks
79+
80+
This change SHOULD NOT introduce any drawbacks.
81+
It is identifying and describing
82+
terms that already exist
83+
and the existing relationship between them.
84+
85+
## Security Implications
86+
87+
This change SHOULD NOT have any security implications.
88+
89+
## Operational Implications
90+
91+
This change SHOULD NOT have any operational implications.
92+
93+
## Guide-level Explanation
94+
95+
Key namespace and key name are configuration values that determine the behavior of a keyring.
96+
97+
Key provider ID and key provider info are values that identify the keyring configuration
98+
that can fulfill the keyring's decryption contract.
99+
The keyring attaches these values to a data key ciphertext to form an encrypted data key.
100+
101+
## Reference-level Explanation
102+
103+
"Key namespace", "key name", "key provider ID", and "key provider info"
104+
are all concepts that identify a wrapping key.
105+
106+
### key namespace
107+
108+
A configuration value for a keyring
109+
that identifies the grouping or categorization
110+
for the wrapping keys that keyring can access.
111+
112+
The key namespace MUST be a string value.
113+
114+
### key name
115+
116+
A configuration value for a keyring
117+
that identifies a single wrapping key
118+
within a key namespace.
119+
120+
The key name MUST be a string value.
121+
122+
### key provider ID
123+
124+
An output value returned by a keyring on encrypt
125+
as part of an encrypted data key structure
126+
that identifies the grouping or categorization
127+
for a keyring that can fulfill this decryption contract.
128+
129+
The key provider ID MUST be a binary value
130+
and SHOULD be equal to a UTF-8 encoding of the key namespace.
131+
132+
### key provider info
133+
134+
An output value returned by a keyring on encrypt
135+
as part of an encrypted data key structure
136+
that provides necessary information for a keyring
137+
to fulfill this decryption contract.
138+
139+
The key provider info MUST be a binary value
140+
and SHOULD be equal to a UTF-8 encoding of the key name.
141+
142+
One example of a keyring where the key name and key provider info can differ
143+
is the AWS KMS keyring.
144+
This keyring uses its key name to identify the desired CMK in its call to AWS KMS.
145+
However, the key provider info that this keyring writes is
146+
the CMK identifier that AWS KMS includes in its response.
147+
If the key name is a CMK ARN, these two values are identical
148+
because this response value is always the CMK ARN of the CMK that AWS KMS used.
149+
However, if the key name is some other valid CMK identifier,
150+
such as an alias,
151+
then they are different.

‎framework/keyring-interface.md

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,14 @@
55

66
## Version
77

8-
0.2.1
8+
0.2.2
99

1010
### Changelog
1111

12+
- 0.2.2
13+
14+
- [Define wrapping key identifier terms](../changes/2020-06-09_wrapping-key-identifiers/change.md)
15+
1216
- 0.2.1
1317

1418
- [Clarify naming of KMS to AWS KMS](https://github.com/awslabs/aws-encryption-sdk-specification/issues/67)
@@ -43,6 +47,45 @@ The keyring interface specified in this document describes the interface all key
4347
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
4448
in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
4549

50+
### key namespace
51+
52+
A configuration value for a keyring
53+
that identifies the grouping or categorization
54+
for the wrapping keys that keyring can access.
55+
56+
The key namespace MUST be a string value.
57+
58+
### key name
59+
60+
A configuration value for a keyring
61+
that identifies a single wrapping key
62+
within a key namespace.
63+
64+
The key name MUST be a string value.
65+
66+
### key provider ID
67+
68+
An output value returned by a keyring on encrypt
69+
as part of an encrypted data key structure
70+
that identifies the grouping or categorization
71+
for a keyring that can fulfill this decryption contract.
72+
73+
The key provider ID MUST be a binary value
74+
and SHOULD be equal to a UTF-8 encoding of the key namespace.
75+
76+
This value MUST NOT be "aws-kms"
77+
unless this encrypted data key was produced by the [AWS KMS Keyring](kms-keyring.md).
78+
79+
### key provider info
80+
81+
An output value returned by a keyring on encrypt
82+
as part of an encrypted data key structure
83+
that provides necessary information for a keyring
84+
to fulfill this decryption contract.
85+
86+
The key provider info MUST be a binary value
87+
and SHOULD be equal to a UTF-8 encoding of the key name.
88+
4689
## Supported Keyrings
4790

4891
- [AWS KMS Keyring](kms-keyring.md)

‎framework/raw-aes-keyring.md

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -54,24 +54,10 @@ Galois/Counter Mode (GCM) Specification: [NIST Special Publication 800-38D](http
5454

5555
On keyring initialization, the following inputs are REQUIRED:
5656

57-
- [Key Namespace](#key-namespace)
58-
- [Key Name](#key-name)
57+
- [Key Namespace](./keyring-interface.md#key-namespace)
58+
- [Key Name](./keyring-interface.md#key-name)
5959
- [Wrapping Key](#wrapping-key)
6060

61-
### Key Namespace
62-
63-
A UTF-8 encoded value that, together with the [key name](#key-name), identifies a particular [wrapping key](#wrapping-key).
64-
65-
The raw AES keyring MUST NOT accept a key namespace of "aws-kms".
66-
67-
This value is also used for bookkeeping purposes.
68-
69-
### Key Name
70-
71-
A UTF-8 encoded value that, together with the [key namespace](#key-namespace), identifies a particular [wrapping key](#wrapping-key).
72-
73-
This value is also used for bookkeeping purposes.
74-
7561
### Wrapping Key
7662

7763
The AES key input to AES-GCM to encrypt plaintext data keys
@@ -91,16 +77,16 @@ This structure is a sequence of bytes in big-endian format to be used as the
9177
The following table describes the fields that form the raw AES keyring key provider information.
9278
The bytes are appended in the order shown.
9379

94-
| Field | Length (bytes) | Interpreted as |
95-
| ------------------------- | ------------------------------- | ------------------- |
96-
| Key Name | length of [Key Name](#key-name) | UTF-8 encoded bytes |
97-
| Authentication Tag Length | 4 | UInt32 |
98-
| IV Length | 4 | UInt32 |
99-
| IV | [IV Length](#iv-length) | Bytes |
80+
| Field | Length (bytes) | Interpreted as |
81+
| ------------------------- | ----------------------------------------------------- | ------------------- |
82+
| Key Name | length of [Key Name](./keyring-interface.md#key-name) | UTF-8 encoded bytes |
83+
| Authentication Tag Length | 4 | UInt32 |
84+
| IV Length | 4 | UInt32 |
85+
| IV | [IV Length](#iv-length) | Bytes |
10086

10187
#### Key Name
10288

103-
The [Key Name](#key-name) of this keyring.
89+
The [Key Name](./keyring-interface.md#key-name) of this keyring.
10490

10591
#### Authentication Tag Length
10692

@@ -164,7 +150,7 @@ The keyring must use AES-GCM with the following specifics:
164150
Based on the ciphertext output of the AES-GCM decryption,
165151
the keyring MUST construct an [encrypted data key](structures.md#encrypted-data-key) with the following specifics:
166152

167-
- the [key provider ID](structures.md#key-provider-id) is this keyring's [key namespace](#key-namespace)
153+
- the [key provider ID](structures.md#key-provider-id) is this keyring's [key namespace](./keyring-interface.md#key-namespace)
168154
- the [key provider information](structures.md#key-provider-information) is serialized as the
169155
[raw AES keyring key provider information](#key-provider-information)
170156
- the [ciphertext](structures.md#ciphertext) is serialized as the
@@ -186,14 +172,14 @@ in the input encrypted data key list, serially, until it successfully decrypts o
186172
For each [encrypted data key](structures.md#encrypted-data-key),
187173
the keyring MUST first attempt to deserialize the [serialized ciphertext](#ciphertext)
188174
to obtain the [encrypted key](#encrypted-key) and [authentication tag](#authentication-tag), and
189-
deserialize the [serialized key provider info](#key-provider-information) to obtain the [key name](#key-name),
175+
deserialize the [serialized key provider info](#key-provider-information) to obtain the [key name](./keyring-interface.md#key-name),
190176
[IV](#iv), [IV length](#iv-length), and [authentication tag length](#authentication-tag-length).
191177

192178
The keyring MUST attempt to decrypt the encrypted data key if and only if the following is true:
193179

194180
- the [ciphertext](#ciphertext) and [key provider information](#key-provider-information) are successfully deserialized.
195-
- the key name obtained from the encrypted data key's key provider information has a value equal to this keyring's [key name](#key-name).
196-
- the key provider ID of the encrypted data key has a value equal to this keyring's [key namespace](#key-namespace).
181+
- the key name obtained from the encrypted data key's key provider information has a value equal to this keyring's [key name](./keyring-interface.md#key-name).
182+
- the key provider ID of the encrypted data key has a value equal to this keyring's [key namespace](./keyring-interface.md#key-namespace).
197183
- the [IV length](#iv-length) obtained from the encrypted data key's key provider information has a value equal to 12.
198184
- the [authentication tag length](#authentication-tag-length) obtained from the key provider information has a value equal to 128.
199185

‎framework/raw-rsa-keyring.md

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -52,25 +52,11 @@ RSA Implementation Specification: [RFC 3447](https://tools.ietf.org/html/rfc8017
5252

5353
On keyring initialization, the following inputs are REQUIRED:
5454

55-
- [Key Namespace](#key-namespace)
56-
- [Key Name](#key-name)
55+
- [Key Namespace](./keyring-interface.md#key-namespace)
56+
- [Key Name](./keyring-interface.md#key-name)
5757
- [Padding Scheme](#padding-scheme)
5858
- [Public Key](#public-key) and/or [Private Key](#private-key)
5959

60-
### Key Namespace
61-
62-
A UTF-8 encoded value that namespaces this keyring.
63-
64-
The raw RSA keyring MUST NOT accept a key namespace of "aws-kms".
65-
66-
This value is also used for bookkeeping purposes.
67-
68-
### Key Name
69-
70-
A UTF-8 encoded value that names this keyring.
71-
72-
This value is also used for bookkeeping purposes.
73-
7460
### Padding Scheme
7561

7662
The RSA padding scheme to use with this keyring.

‎framework/structures.md

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -73,25 +73,13 @@ and vice versa MAY be any reversible operation, though we expect that most will
7373

7474
##### Key Provider ID
7575

76-
A UTF-8 encoded value related to the key provider that encrypted this data key.
77-
78-
This value usually represents the namespace of the key provider defined wrapping key
79-
used to encrypt the plaintext data key.
80-
81-
For example, [encrypted data keys](#encrypted-data-key) encrypted by the [AWS KMS Keyring](kms-keyring.md)
82-
have the value of "aws-kms" in this field.
83-
84-
This value MUST NOT be "aws-kms" unless this encrypted data key was produced by the [AWS KMS Keyring](kms-keyring.md).
76+
The [key provider ID](keyring-interface.md#key-provider-id) value
77+
for the keyring that wrote this encrypted data key.
8578

8679
##### Key Provider Information
8780

88-
Information related to the key provider.
89-
Its structure and meaning is specified by the key provider that encrypted this data key.
90-
91-
This is usually a UTF-8 encoded value.
92-
This value is usually the name of a key provider defined wrapping key that is used to encrypt the plaintext data key.
93-
However, the [raw AES keyring](raw-aes-keyring.md) defines a specific structure for the key provider information
94-
that includes more information.
81+
The [key provider info](keyring-interface.md#key-provider-info) value
82+
for the keyring that wrote this encrypted data key.
9583

9684
##### Ciphertext
9785

0 commit comments

Comments
 (0)