Skip to content

Commit 43c69f3

Browse files
alex-chewalex-chew
committed
doc: specify how caching CMM should handle max plaintext length in Get Encryption Materials
1 parent 31b0534 commit 43c69f3

File tree

2 files changed

+175
-6
lines changed

2 files changed

+175
-6
lines changed

‎changes/2020-07-13_caching-cmm-max-plaintext-length/change.md

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Enforce Safe Handling of Max Plaintext Length in Caching Cryptographic Materials Manager
5+
6+
## Affected Features
7+
8+
| Feature |
9+
| ------------------------------------------------------------------------- |
10+
| [Caching Cryptographic Materials Manager](../../framework/caching-cmm.md) |
11+
12+
## Affected Specifications
13+
14+
| Specification |
15+
| ------------------------------------------------------------------------- |
16+
| [Caching Cryptographic Materials Manager](../../framework/caching-cmm.md) |
17+
18+
## Affected Implementations
19+
20+
| Language | Repository |
21+
| ---------- | ------------------------------------------------------------------------------------- |
22+
| C | [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c) |
23+
| Java | [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java) |
24+
| JavaScript | [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript) |
25+
| Python | [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python) |
26+
27+
## Definitions
28+
29+
### Conventions used in this document
30+
31+
The key words
32+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
33+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
34+
in this document are to be interpreted as described in
35+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
36+
37+
## Summary
38+
39+
The Get Encryption Materials operation accepts an optional `max plaintext length` parameter,
40+
but the specification does not state how the caching CMM should behave
41+
when the caller does not provide the parameter value.
42+
This change specifies that the caching CMM should bypass the cache in this case.
43+
44+
Also, when the caching CMM is performing a Get Encryption Materials operation
45+
for which no materials are cached,
46+
it MUST call its underlying CMM's Get Encryption Materials operation.
47+
The specification does not state what value of `max plaintext length` (if any)
48+
the caching CMM should pass to its underlying CMM.
49+
This change specifies that the caching CMM should pass its `byte limit` value
50+
as the `max plaintext length` parameter of the call to the underlying CMM.
51+
52+
## Out of Scope
53+
54+
- Changing the shape of any CMM APIs is out of scope.
55+
56+
## Motivation
57+
58+
### Fulfulling Encryption Materials Requests Without `max plaintext length`
59+
60+
The Get Encryption Materials operation of the Cryptographic Materials Manager (CMM)
61+
accepts an Encryption Materials Request that MAY specify a `max plaintext length` field,
62+
indicating the maximum length of plaintext
63+
that the caller intends to encrypt using the returned materials.
64+
The caching Cryptographic Materials Manager (caching CMM)
65+
aims to prevent its users from using encryption materials
66+
to encrypt more bytes than its configured `byte limit`,
67+
and existing implementations do so by bypassing the cache
68+
whenever it does not know their users' `max plaintext length`.
69+
This behavior is safe but previously unspecified,
70+
and this change mandates that implementations implement it.
71+
72+
### Setting `max plaintext length` for Underlying CMM's Get Encryption Materials
73+
74+
The CMM interface specification implicitly allows an underlying CMM
75+
to produce encryption materials using logic
76+
that depends on the `max plaintext length` of its Encryption Materials Request.
77+
Suppose the caching CMM passes a `max plaintext length` value of `N`
78+
to its underlying CMM's Get Encryption Materials operation,
79+
and caches the materials that it receives.
80+
If a later Get Encryption Materials operation fetches those materials from the cache,
81+
but has a `max plaintext length` value that exceeds `N`,
82+
then the caching CMM returns those materials unsafely.
83+
84+
It is therefore important that the caching CMM
85+
carefully selects the `max plaintext length` parameter to pass to its underlying CMM.
86+
This change mandates that the caching CMM passes its configured `byte limit` value
87+
as the `max plaintext length` parameter to the underlying CMM,
88+
whereas previously, the caching CMM could choose any value.
89+
With this change in place,
90+
even if the underlying CMM produces materials using plaintext-length-dependent logic,
91+
the caching CMM receives and caches materials
92+
that are safe to use for up to `byte limit` bytes of plaintext.
93+
It follows that if a later Get Encryption Materials operation's `max plaintext length`
94+
does not exceed the caching CMM's `byte limit`,
95+
then it is also safe for the caching CMM to return corresponding cached materials.
96+
97+
## Drawbacks
98+
99+
Bypassing the cache in the caching CMM on Get Encryption Materials operations
100+
that do not specify `max plaintext length`
101+
could be confusing to the user.
102+
Warning the user when this happens could help prevent users from running into
103+
unexpected (and potentially expensive) calls to the underlying CMM,
104+
but we leave this as an implementation choice.
105+
106+
## Security Implications
107+
108+
This change SHOULD NOT have any security implications.
109+
110+
## Operational Implications
111+
112+
This change will break any customer use case
113+
that depends on the Caching CMM passing no `max plaintext length` parameter
114+
to the underlying CMM on Get Encryption Materials calls.
115+
116+
## Guide-level Explanation
117+
118+
When you make a Get Encryption Materials call to the caching CMM,
119+
you may optionally specify a value for the `max plaintext length` parameter,
120+
which indicates the maximum number of bytes you will encrypt
121+
with the materials you receive from the call.
122+
If you do not specify a `max plaintext length` value,
123+
then the caching CMM will neither use cached materials
124+
nor cache materials from its underlying CMM.
125+
This helps to ensure that you do not exceed the `byte limit`
126+
that you configure on the caching CMM.
127+
So in order to maximize the benefits of caching,
128+
you should specify the `max plaintext length` value
129+
whenever you know an appropriate upper bound for bytes you will encrypt.
130+
131+
If you customize the underlying CMM of a caching CMM,
132+
then whenever the caching CMM makes a Get Encryption Materials call
133+
to your customized underlying CMM,
134+
the Encryption Materials Request will have a `max plaintext length` value
135+
equal to the `byte limit` value configured on the caching CMM.
136+
This helps to ensure that the caching CMM can safely cache materials
137+
that it receives from the customized underlying CMM.
138+
139+
## Reference-level Explanation
140+
141+
When the caching CMM is performing the Get Encryption Materials operation
142+
for an Encryption Materials Request that does not specify a `max plaintext length`,
143+
144+
- The caching CMM MUST NOT return materials from its CMC.
145+
- If the caching CMM calls its underlying CMM's Get Encryption Materials operation
146+
in order to obtain encryption materials,
147+
it MUST NOT cache the encryption materials in its CMC.
148+
149+
When the caching CMM calls its underlying CMM's Get Encryption Materials operation
150+
in order to obtain encryption materials,
151+
it MUST use its configured `byte limit` value
152+
as the `max plaintext length` field of the Encryption Materials Request
153+
that it sends to the underlying CMM.

‎framework/caching-cmm.md

+22-6
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,24 @@
55

66
## Version
77

8-
0.1.0-preview
8+
0.2.0
9+
10+
### Changelog
11+
12+
- 0.2.0
13+
- [Enforce Safe Handling of Max Plaintext Length in Caching Cryptographic Materials Manager](../changes/2020-07-13_caching-cmm-max-plaintext-length/change.md)
14+
- 0.1.0-preview
15+
- Initial record
916

1017
## Implementations
1118

12-
- [C](https://github.com/aws/aws-encryption-sdk-c/blob/master/include/aws/cryptosdk/cache.h)
13-
- [Python](https://github.com/aws/aws-encryption-sdk-python/blob/master/src/aws_encryption_sdk/materials_managers/caching.py)
14-
- [Java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/main/java/com/amazonaws/encryptionsdk/caching/CachingCryptoMaterialsManager.java)
15-
- [NodeJS](https://github.com/awslabs/aws-encryption-sdk-javascript/blob/master/modules/caching-materials-manager-node/src/caching_materials_manager_node.ts)
16-
- [Browser JS](https://github.com/awslabs/aws-encryption-sdk-javascript/blob/master/modules/caching-materials-manager-browser/src/caching_materials_manager_browser.ts)
19+
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
20+
| ---------- | -------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21+
| C | 0.1.0-preview | 0.1.0 | [cache.h](https://github.com/aws/aws-encryption-sdk-c/blob/master/include/aws/cryptosdk/cache.h) |
22+
| NodeJS | 0.1.0-preview | 0.1.0 | [caching_materials_manager_node.ts](https://github.com/awslabs/aws-encryption-sdk-javascript/blob/master/modules/caching-materials-manager-node/src/caching_materials_manager_node.ts) |
23+
| Browser JS | 0.1.0-preview | 0.1.0 | [caching_materials_manager_browser.ts](https://github.com/awslabs/aws-encryption-sdk-javascript/blob/master/modules/caching-materials-manager-browser/src/caching_materials_manager_browser.ts) |
24+
| Python | 0.1.0-preview | n/a | [materials_managers/caching.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/src/aws_encryption_sdk/materials_managers/caching.py) |
25+
| Java | 0.1.0-preview | n/a | [CachingCryptoMaterialsManager.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/main/java/com/amazonaws/encryptionsdk/caching/CachingCryptoMaterialsManager.java) |
1726

1827
## Overview
1928

@@ -113,6 +122,7 @@ The number of bytes encrypted by the [encryption](structures.md#encryption-mater
113122
### Get Encryption Materials
114123

115124
If the [algorithm suite](algorithm-suites.md) requested contains a [Identity KDF](algorithm-suites.md#identity-kdf),
125+
or if the request does not include a [Max Plaintext Length](cmm-interface.md#encryption-materials-request) value,
116126
the caching CMM MUST obtain the encryption materials by making a call to the underlying CMM's [Get Encryption Materials](cmm-interface.md#get-encryption-materials) function.
117127

118128
Otherwise, the caching CMM MUST attempt to find the [encryption materials](structures.md#encryption-materials)
@@ -122,10 +132,16 @@ If a cache entry is found, the caching CMM MUST return the encryption materials
122132
If a cache entry is not found, the caching CMM MUST then attempt to obtain the encryption materials
123133
by making a call to the underlying CMM's [Get Encryption Materials](cmm-interface.md#get-encryption-materials).
124134

135+
If the caching CMM makes a call to the underlying CMM's [Get Encryption Materials](cmm-interface.md#get-encryption-materials) operation,
136+
then it MUST include a [Max Plaintext Length](cmm-interface.md#encryption-materials-request) value,
137+
which MUST be equal to its [Limit Bytes](#limit-bytes) value.
138+
125139
If the [algorithm suite](algorithm-suites.md) requested does not contain an [Identity KDF](algorithm-suites.md#identity-kdf),
140+
and if the request includes a [Max Plaintext Length](cmm-interface.md#encryption-materials-request) value,
126141
the caching CMM MUST add the encryption materials obtained from the underlying CMM into the underlying CMC.
127142

128143
If the [algorithm suite](algorithm-suites.md) requested contains an Identity KDF,
144+
or if the request does not include a [Max Plaintext Length](cmm-interface.md#encryption-materials-request) value,
129145
the caching CMM MUST NOT store the encryption materials in the underlying CMC.
130146

131147
### Decrypt Materials

0 commit comments

Comments
 (0)