Skip to content

Commit 95b70f3

Browse files
rishav-karanjitrishav-karanjit
committed
auto commit
1 parent 9f7b93e commit 95b70f3

File tree

2 files changed

+338
-6
lines changed

2 files changed

+338
-6
lines changed

‎changes/2025-06-30_branch_keys_version_2/DesignQuestion.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ to verify the MAC.
6262

6363
## 1.3 Binding the **Branch Key Context Digest** via KMS Encrypt
6464

65-
One option is to refactor Branch Key Creation to use `kms:GenerateDataKey`
65+
One option is to refactor Branch Key Creation to use `kms:GenerateDataKey`
6666
to get a plain text cryptographic materials.
6767

6868
This **Branch Key Context Digest** is then concatenated with
@@ -73,16 +73,15 @@ if this local entropy fails to be random then cryptographic integrity of the mes
7373

7474
## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt
7575

76-
KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key.
76+
KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key.
7777
This can be useful in situations where you need to generate random data, but don't require access controls provided by KMS keys with key policy.
78-
Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key.
79-
As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission.
78+
Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key.
79+
As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission.
8080

81-
Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation,
81+
Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation,
8282
as they can't use key policy for it. However, this approach could lead to a "clunkier" interface, as it would involve managing multiple KMS clients.
8383
So, option 1.4 was rejected.
8484

85-
8685
## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location
8786

8887
Rather than appending the **Branch Key Context Digest** to the plain-text AES-256,

‎changes/2025-06-30_branch_keys_version_2/background.md‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Customers should control encryption context
5+
6+
# Definitions
7+
8+
## Conventions used in this document
9+
10+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
11+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
12+
interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
13+
14+
## HV-1
15+
16+
The Branch Key Store's Branch Keys are designated as `"hierarchy-version" : "1"`.
17+
18+
This document proposes changes to theses Branch Keys;
19+
when HV-1 is written,
20+
we mean a Branch Key Item written by the Branch Key Store v0.2.0 to v0.7.0.
21+
22+
## Branch Key's Cryptographic Material
23+
24+
Cryptographic material (AES-256 bit key) generated and protected by KMS.
25+
26+
## Branch Key's Properities
27+
28+
These three values are stored on every
29+
Active,
30+
Version,
31+
and Beacon Key Item in the Branch Key Store's Storage.
32+
33+
They are also present in the KMS Encryption Context.
34+
35+
```json
36+
"kms-arn" : "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
37+
"create-time" : "2023-06-03T19:03:29.358Z",
38+
"hierarchy-version" : "1",
39+
```
40+
41+
The Active has an additional field:
42+
43+
```json
44+
"version": "branch:version:83eec007-5659-4554-bf11-699b90f41ac6"
45+
```
46+
47+
## Branch Key's Location
48+
49+
These two values are stored on every
50+
Active,
51+
Version,
52+
and Beacon Key Item in the Branch Key Store's Storage.
53+
54+
For Active:
55+
56+
```json
57+
"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b",
58+
"type" : "branch:ACTIVE"
59+
```
60+
61+
For Version:
62+
63+
```json
64+
"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b",
65+
"type": "branch:version:83eec007-5659-4554-bf11-699b90f41ac6"
66+
```
67+
68+
For Beacon:
69+
70+
```json
71+
"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b",
72+
"type": "beacon:ACTIVE"
73+
```
74+
75+
However,
76+
the Logical Key Store Name is also included in the KMS Encryption Context.
77+
78+
```json
79+
"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b",
80+
"type" : "branch:ACTIVE",
81+
"tablename": "KeyStore"
82+
```
83+
84+
These three values describe where the Branch Key is stored; however, the tablename is a logical description, not a physical description.
85+
At this time, no cryptography binds the Branch Key to the physical table.
86+
87+
```json
88+
"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b",
89+
"tablename": "KeyStore"
90+
```
91+
92+
These two values label the Branch Key, seperating it from all other Branch Keys.
93+
94+
## Branch Key's Encryption Context
95+
96+
These values are determined by the Branch Key Creator
97+
or last Branch Key Mutator.
98+
99+
In DynamoDB and in KMS Encryption Requests,
100+
their keys are prefixed with `aws-crypto-ec:`.
101+
102+
```json
103+
"aws-crypto-ec:department" : "admin"
104+
```
105+
106+
However,
107+
when returned to the requesters of the Branch Key Store's
108+
`Get*Key*` operations,
109+
the prefix is removed.
110+
111+
## Branch Key's Context
112+
113+
The union of the Branch Key's:
114+
115+
- Properities
116+
- Location (including logical key store name)
117+
- Encryption Context
118+
119+
# Background
120+
121+
The current Branch Key Store's Branch Key's use KMS Encryption Context
122+
to cryptographically bind the Branch Key's cryptographic material to
123+
the Branch Key's Context.
124+
125+
This cryptographic binding mitigates a number of threats around
126+
storing the Branch Keys
127+
and is vital to the safe usage of the Hierarchal Keyring.
128+
129+
However,
130+
it is not clear that this is the best use of KMS Encryption Context,
131+
as it interferes with customers ability to use KMS Key Policies to
132+
constrain Key Usage.
133+
134+
Further more,
135+
Encryption Context evaluation can be customized by the calling principles authorization;
136+
KMS Key Grants can have restricted but unique conditions.
137+
138+
Many potential Branch Key Customers are prevented from using
139+
the Hierarchy Keyring,
140+
as they have pre-existing Key Policies with their tenants
141+
that cannot be met if the KMS Encryption Context is populated
142+
by the Branch Key's Context.
143+
144+
Finally,
145+
some of the users have insisted that
146+
Crypto Tools refactor the KMS Encryption Context
147+
to only be the Branch Key's Encryption Context.
148+
149+
# Requirements
150+
151+
1. Branch Key's Context be cryptographically bound to the Branch Key's Cryptographic Material
152+
153+
2. Branch Key's Encryption Context, untransformed in any way, is the KMS Encryption Context
154+
155+
3. Support for all of Behaviors of the current Branch Key Store (Create, Version, Get\*)
156+
157+
# Out of Scope
158+
159+
- Abstracting away from KMS
160+
- Supporting any Branch Key protection Scheme via the DB-ESDK, much like the DDBEC's MetaStore.
161+
162+
## Why not Abstract away from KMS
163+
164+
Over the past year,
165+
Crypto Tools has spent a significant amount of our time
166+
supporting services integrating with KMS for multi-tenant applications.
167+
168+
While we MAY eventually want to support GCP or Azure,
169+
we MUST focus on the fasting growing customer base we have;
170+
AWS Services and Software-as-a-service providers integrating with KMS.
171+
172+
## Why not the MetaStore approach?
173+
174+
The MetaStore was the predecessor to the Branch Key Store; it is the "caching" solution for the legacy DynamoDB Encryption Client (DDBEC). The MetaStore used the DDBEC itself to protect the hierarchical material with KMS.
175+
176+
Which affords for some flexibility, as the MetaStore was an interface.
177+
178+
However, our customers have complained that the DB-ESDK is complicated;
179+
using the DB-ESDK to protect the materials used by the DB-ESDK is NOT
180+
a step towards simplification.
181+
182+
While such a feature MAY provide the greatest flexibility to
183+
our customers,
184+
it is not a simplification of the Hierarchy Keyring,
185+
but a complication to it.
186+
187+
# Design Questions
188+
189+
## 1 How can the Branch Key's Context be protected without using KMS EC?
190+
191+
See [DesignQuestion.md](./DesignQuestion.md).
192+
193+
## 2 How are we going to offer operation in a mixed mode?
194+
195+
UPDATE: 2.1 was rejected.
196+
There will be no Policy (2.2).
197+
198+
### 2.1 `hierarchy-version-policy`
199+
200+
Much like [Key Commitment](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#key-commitment),
201+
I suggest we introduce a policy that
202+
would allow for mixed usage or restricting to one or the other.
203+
204+
Something like `hierarchy-version-policy`:
205+
206+
- ALLOW_V1
207+
- ALLOW_V2
208+
- ALLOW_V1_OR_V2
209+
- ANY
210+
211+
This policy would be part of (all) Branch Key Store configuration.
212+
213+
(all: Branch Key Store, any future Branch Key Store Usage client.)
214+
215+
This allows our customers to
216+
restrict to one KMS Encryption Context
217+
experience or another.
218+
219+
The effort to implement and test this is very low,
220+
relative to other code paths in this effort.
221+
222+
### 2.2 Do Nothing
223+
224+
UPDATE: We are going with Do Nothing
225+
226+
There is no immediate customer demand for a policy like this.
227+
In general,
228+
the Branch Key in the table,
229+
in combination with KMS,
230+
the authority of it's treatment.
231+
232+
However,
233+
given the low effort required to implement/support this,
234+
and the aid it gives our customers in having
235+
a consistent KMS Encryption Context experience,
236+
I suggest we implement the policy.
237+
238+
### 2.3 Pros of 2.1
239+
240+
**Update Readers, than Writers**:
241+
To use HV-2,
242+
customers already using the H-Keyring will need
243+
to update their readers before they start creating
244+
or mutating Branch Keys to HV-2.
245+
246+
i.e: They need to update their readers before they update their writers.
247+
248+
This alone is justification for the policy.
249+
250+
**Consistent KMS Encryption Context**:
251+
[Much has been said for](https://quip-amazon.com/rc9CARWxsCTT#LHG9AA64tJh) and [against the Encryption Context](https://quip-amazon.com/l5d8AHH0hgZs/Encryption-Context-Exposure-by-Dynamo-ESDK)
252+
witnessed by KMS in HV-1.
253+
254+
The arguments for the HV-1 Encryption Context suggest
255+
users SHOULD be able to restrict their Branch Key Store clients
256+
to a HV-1 such that they know any IAM or KMS Key Policies
257+
they created that depend on HV-1's Encryption Context
258+
are still valid.
259+
260+
### 2.4 Cons
261+
262+
**Additional Development work and documentation**:
263+
Nothing is free;
264+
we would need to implement, document, test, and maintain this policy.
265+
266+
Still,
267+
the migration benefit justifies this cost.
268+
269+
## 3 Branch Key Creation
270+
271+
UPDATE: The team decided that the Branch Key Store would create and version both HV-1 and HV-2 BKs.
272+
UPDATE: The team changed their mind; the Branch Key Store WILL support HV-2 Branch Key Creation, via a flag.
273+
274+
Customers MUST be able to chose which `hierarchy-version`
275+
new Branch Keys are created with.
276+
277+
The question is what should the UX be.
278+
279+
### 3.1 Specify the `hierarchy-version` at Creation
280+
281+
Currently, our library has one Branch Key Creation operations:
282+
283+
- `BranchKeyStore#CreateKey`
284+
285+
To this operation,
286+
we could add a flag that dictates the `hierarchy-version` to be created with.
287+
288+
If that flag conflicts with `hierarchy-version-policy`,
289+
then FAIL.
290+
291+
Otherwise, respect the flag.
292+
293+
**Plumbing through `GenerateRandom`**:
294+
UPDATE: `kms:GenerateDataKey` closed this negative consequence.
295+
We will had to add an optional `AwsKms` input
296+
to supply the plain-text data key.
297+
298+
### 3.2 Follow the Configuration
299+
300+
This does not work if the configuration is `ALLOW\_V1\_OR_V2`;
301+
this is not recommended.
302+
303+
### 3.3 New Operation or Client
304+
305+
We could leave the old Branch Key Store alone,
306+
and introduce a new Branch Key Store V2.
307+
308+
The UX advantage here is that we can introduce new error types
309+
without breaking customers.
310+
311+
For example,
312+
the creation of the `hierarchy-version-policy` implies
313+
that we will need an error type for rejecting a Branch Key
314+
that does not match.
315+
316+
Particularly if we went down the additional KMS approaches (1.2, 1.3),
317+
new error types will need to be created to represent
318+
failures from the additional KMS key.
319+
320+
But we have committed to 1.4;
321+
this limits the failure modes/additional errors
322+
to the point that I do not think new client
323+
or operation is needed.
324+
325+
### 3.4 Author's conclusion
326+
327+
Unless someone can think of something else,
328+
3.1.
329+
330+
## 4 Branch Key Versioning (Rotation)
331+
332+
UPDATE: The team elected for 3.5; we will Mirror 3.5.
333+
(BKS can VersionKey HV-1 or HV-2).

0 commit comments

Comments
 (0)