Skip to content

Commit 102a523

Browse files
texastonyjosecorella
texastony
authored and
josecorella
committed
feat(proposal): Raw RSA Keyring V2 (#56)
Adding AWS KMS RSA Asymmetric key support
1 parent 19a4555 commit 102a523

File tree

2 files changed

+277
-0
lines changed

2 files changed

+277
-0
lines changed

‎framework/aws-kms/aws-kms-rsa-keyring.md

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# AWS KMS RSA Keyring
5+
6+
## Version
7+
8+
0.1.0-preview
9+
10+
### Changelog
11+
12+
- 0.1.0-preview
13+
14+
- Initial record
15+
16+
## Implementations
17+
18+
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
19+
| ---------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
20+
21+
## Overview
22+
23+
A keyring which uses AWS KMS RSA asymmetric keys
24+
to protect messages with envelop encryption.
25+
A hash of the Encryption Context is stored
26+
in the encrypted data key
27+
to bind the encryption context to the data key.
28+
29+
For decryption of data keys the keyring always calls KMS
30+
and compares the encryption context
31+
to the hashed value stored in the encrypted data key.
32+
33+
## Definitions
34+
35+
### Conventions used in this document
36+
37+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
38+
in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
39+
40+
## Initialization
41+
42+
On initialized the caller can provide:
43+
44+
- MUST provide an AWS KMS key identifier
45+
- MUST provide an [AWS KMS Encryption Algorithm](#supported-padding-schemes)
46+
- MAY provide a PEM encoded Public Key
47+
- MAY provide an AWS KMS SDK client
48+
- MAY provide a list of Grant Tokens
49+
50+
The AWS KMS key identifier MUST NOT be null or empty.
51+
The AWS KMS key identifier MUST be [a valid identifier](../../framework/aws-kms/aws-kms-key-arn.md#a-valid-aws-kms-identifier).
52+
The AWS KMS key identifier MUST NOT be an AWS KMS alias.
53+
54+
If provided the Public Key
55+
MUST have an RSA modulus bit length greater than or equal to 2048.
56+
The configured AWS KMS key identifier
57+
must match the public key provided.
58+
There should not be a synchronous check to verify this.
59+
60+
### AWS KMS Encryption Algorithm
61+
62+
The RSA padding scheme to use with this keyring.
63+
64+
This value MUST correspond with one of the [supported padding schemes](#supported-padding-schemes).
65+
66+
#### Supported Padding Schemes
67+
68+
The following padding schemes are currently defined by AWS KMS:
69+
70+
- RSAES_OAEP_SHA_1
71+
- This is equivalent to [OAEP with SHA-1 and MGF1 with SHA-1 Padding](https://tools.ietf.org/html/rfc8017#section-7.1)
72+
- RSAES_OAEP_SHA_256
73+
- This is equivalent to [OAEP with SHA-256 and MGF1 with SHA-256 Padding](https://tools.ietf.org/html/rfc8017#section-7.1)
74+
75+
This keyring MUST NOT use a padding scheme outside those defined above.
76+
These values must match the supported values
77+
for [AWS KMS RSA key specs](https://docs.aws.amazon.com/kms/latest/developerguide/asymmetric-key-specs.html#key-spec-rsa).
78+
79+
## Operation
80+
81+
### OnEncrypt
82+
83+
OnEncrypt MUST fail if this keyring does not have a specified Public Key.
84+
85+
OnEncrypt MUST take [encryption materials](../structures.md#encryption-materials) as input.
86+
87+
If the [encryption materials](structures.md#encryption-materials) do not contain a plaintext data key,
88+
OnEncrypt MUST generate a random plaintext data key and set it on the [encryption materials](structures.md#encryption-materials).
89+
90+
OnEncrypt MUST calculate a Encryption Context Digest by:
91+
92+
1. Serializing The [encryption context](structures.md#encryption-context-1) from the input
93+
[encryption materials](../structures.md#encryption-materials) in the same format as the serialization of
94+
[message header AAD key value pairs](../../data-format/message-header.md#key-value-pairs).
95+
2. Taking the SHA-384 Digest of this concatenation.
96+
97+
The keyring MUST determine the [Padding Scheme](#padding-scheme)
98+
using the configured [AWS KMS Encryption Algorithm]((https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html#KMS-Decrypt-request-EncryptionAlgorithm).
99+
in the following manner:
100+
101+
If `RSAES_OAEP_SHA_256` the keyring
102+
MUST use [OAEP with SHA-256 and MGF1 with SHA-256 Padding](https://tools.ietf.org/html/rfc8017#section-7.1).
103+
104+
If `RSAES_OAEP_SHA_1` the keyring
105+
MUST use [OAEP with SHA-1 and MGF1 with SHA-1 Padding](https://tools.ietf.org/html/rfc8017#section-7.1)
106+
107+
The keyring MUST attempt to encrypt the plaintext data key in the
108+
[encryption materials](structures.md#encryption-materials) using RSA.
109+
110+
The keyring performs [RSA encryption](#rsa) with the following specifics:
111+
112+
- This keyring's [padding scheme](#supported-padding-schemes) calculated above.
113+
- The Encryption Context Digest concatenated with the plaintext data key is the plaintext input to RSA encryption.
114+
- This [public key](kms-rsa-public-key-provider-interface.md##public-key)
115+
is the configured RSA public key.
116+
117+
If RSA encryption was successful, OnEncrypt MUST return the input
118+
[encryption materials](structures.md#encryption-materials), modified in the following ways:
119+
120+
- The encrypted data key list has a new encrypted data key added, constructed as follows:
121+
- The [ciphertext](../structures.md#ciphertext) MUST field is the ciphertext output by the RSA encryption.
122+
- The [key provider id](../structures.md#key-provider-id) MUST be "aws-kms-rsa".
123+
- The [key provider information](../structures.md#key-provider-information) MUST be
124+
the configured `AWS KMS key identifier`.
125+
126+
If RSA encryption was NOT successful, OnEncrypt MUST fail.
127+
128+
### OnDecrypt
129+
130+
OnDecrypt MUST fail if this keyring does not have a specified AWS KMS SDK client.
131+
132+
OnDecrypt MUST take [decryption materials](../structures.md#decryption-materials) and
133+
a list of [encrypted data keys](../structures.md#encrypted-data-key) as input.
134+
135+
If the [decryption materials](../structures.md#decryption-materials) already contained a valid plaintext data key
136+
OnDecrypt MUST return an error.
137+
138+
The set of encrypted data keys MUST first be filtered to match this keyring’s configuration. For the encrypted data key to match:
139+
140+
- Its provider ID MUST exactly match the value “aws-kms-rsa”.
141+
- The provider info MUST be a [valid AWS KMS ARN](aws-kms-key-arn.md#a-valid-aws-kms-arn)
142+
with a resource type of `key` or OnDecrypt MUST fail.
143+
- The function [AWS KMS MRK Match for Decrypt](aws-kms-mrk-match-for-decrypt.md#implementation)
144+
called with the configured AWS KMS key identifier and the provider info MUST return `true`.
145+
146+
OnDecrypt MUST calculate a Encryption Context Digest Prime by:
147+
148+
1. Serializing The [encryption context](structures.md#encryption-context-2) from the input
149+
[decryption materials](../structures.md#decryption-materials) in the same format as the serialization of
150+
[message header AAD key value pairs](../../data-format/message-header.md#key-value-pairs).
151+
2. Taking the SHA-384 Digest of this concatenation.
152+
153+
For each encrypted data key in the filtered set,
154+
one at a time,
155+
the OnDecrypt MUST attempt to decrypt the data key.
156+
If this attempt results in an error,
157+
then these errors MUST be collected.
158+
159+
To attempt to decrypt a particular [encrypted data key](../structures.md#encrypted-data-key),
160+
OnDecrypt MUST call [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
161+
with the configured AWS KMS client.
162+
163+
When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html),
164+
the keyring MUST call with a request constructed as follows:
165+
166+
- `KeyId` MUST be the configured AWS KMS key identifier.
167+
- `CiphertextBlob` MUST be the [encrypted data key ciphertext](../structures.md#ciphertext).
168+
- `GrantTokens` MUST be this keyring's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token).
169+
- `EncryptionAlgorithm` MUST be configured value.
170+
171+
If the call to [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) succeeds,
172+
OnDecrypt verifies:
173+
174+
- The `KeyId` field in the response MUST equal the configured AWS KMS key identifier.
175+
176+
If any decryption succeeds,
177+
the result of this decryption MUST be split into
178+
the encryption context digest and plaintext data key by:
179+
180+
- the first 48 bytes is the encryption context digest
181+
- all bytes after that are the plain text data key.
182+
183+
The keyring MUST compare the decrypted encryption context digest
184+
to the encryption context digest prime;
185+
if the two are not equal,
186+
the keyring MUST fail and
187+
MUST NOT modify the [decryption materials](structures.md#decryption-materials).
188+
189+
Otherwise, this keyring MUST immediately return the input
190+
[decryption materials](structures.md#decryption-materials), modified in the following ways:
191+
192+
- The plaintext data key is set as the decryption material's plaintext data key.
193+
194+
If no decryption and keyring digest check succeeds,
195+
the keyring MUST fail
196+
and MUST NOT modify the [decryption materials](structures.md#decryption-materials).
197+
198+
### Encryption Context Digest
199+
200+
The Encryption Context is the SHA-384 hash of
201+
the Encryption Materials' Encryption Context.
202+
The fact that this digest is not truncated
203+
means that this keyring MUST NOT
204+
support 1024 bit keys.
205+
206+
### Encryption Context Digest Prime
207+
208+
The Encryption Context Digest Prime is the SHA-384 hash of
209+
the Decryption Materials' Encryption Context.

‎proposals/2022-10-27_rsa-keyring-v2/proposal.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Raw RSA Keyring V2
5+
6+
## Affected Features
7+
8+
This serves as a reference of all features that this change affects.
9+
10+
| Feature |
11+
| ----------------------------------------------------- |
12+
| [Raw RSA Keyring](../../framework/raw-rsa-keyring.md) |
13+
14+
## Affected Specifications
15+
16+
This serves as a reference of all specification documents that this change affects.
17+
18+
| Specification |
19+
| -------------------------------------------------------------- |
20+
| [Raw RSA Keyring](../../framework/aws-kms/aws-kms-rsa-keyring) |
21+
22+
## Definitions
23+
24+
### Conventions used in this document
25+
26+
The key words
27+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
28+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
29+
in this document are to be interpreted as described in
30+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
31+
32+
## Summary
33+
34+
The ESDK message format includes a digital signature over all of body of the message.
35+
This signature is verified on decrypt with a verification key that is
36+
persisted in the Encryption Context.
37+
With an AWS KMS Keyring
38+
the Encryption Context is included in the
39+
Encrypt and Decrypt invocations as encryption context.
40+
This encryption context is immutable
41+
because it is enforce by AWS KMS
42+
and it is bound to the encrypted data key.
43+
44+
But RSA is not an Authenticated Encryption with Additional Data (AEAD) cipher;
45+
as such, it's invocation cannot include encryption context.
46+
This means that an by default an AWS KMS RSA keyring
47+
would not have these properties.
48+
49+
To solve this,
50+
we propose storing a representation of the Encryption Context in
51+
the Encrypted Data Key's ciphertext of AWS KMS RSA Keyrings.
52+
53+
On Decrypt,
54+
this representation would be compared to the given Encryption Context.
55+
If this comparison fails, the decrypt would fail.
56+
57+
## Out of Scope
58+
59+
This proposal does not address:
60+
61+
- Integrating the Raw RSA Keyring
62+
63+
## Motivation
64+
65+
Digital Signatures are a prominent feature of the ESDK's message format.
66+
It is a miss that Verification Key is not protected in the RSA Keyring.
67+
These changes make the Encryption Context bound to the encrypted data key
68+
and the message more tightly bound together.

0 commit comments

Comments
 (0)