Skip to content

Commit 280a894

Browse files
kessplaskessplas
authored
chore: spec for S3EC Keyring/KmsKeyring (#306)
1 parent 85d4c17 commit 280a894

File tree

3 files changed

+189
-0
lines changed

3 files changed

+189
-0
lines changed

‎s3-encryption/materials/keyrings.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Keyrings
5+
6+
This specification refers to Keyrings used in S3EC v3 and is largely similar to the keyring interface present in the Material Providers Library (MPL), available [here](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md).
7+
8+
## Version
9+
10+
0.1.0
11+
12+
### Changelog
13+
14+
- 0.1.0
15+
- Initial
16+
17+
## Definitions
18+
19+
### Conventions used in this document
20+
21+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
22+
in this document are to be interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119).
23+
24+
## Interface
25+
26+
The Keyring interface and its operations SHOULD adhere to the naming conventions of the implementation language.
27+
28+
The Keyring interface MUST include the OnEncrypt operation.
29+
The OnEncrypt operation MUST accept an instance of EncryptionMaterials as input.
30+
The OnEncrypt operation MUST return an instance of EncryptionMaterials as output.
31+
32+
The Keyring interface MUST include the OnDecrypt operation.
33+
The OnDecrypt operation MUST accept an instance of DecryptionMaterials and a collection of EncryptedDataKey instances as input.
34+
The OnDecrypt operation MUST return an instance of DecryptionMaterials as output.
35+
36+
## Supported Keyrings
37+
38+
The Amazon S3 Encryption Client provides the following keyring implementations:
39+
40+
- [S3 Keyring](s3-keyring.md)
41+
- [S3 KMS Keyring](s3-kms-keyring.md)
42+
- [S3 AES Keyring](s3-aes-keyring.md)
43+
- [S3 RSA Keyring](s3-rsa-keyring.md)
44+
45+
Note: A user MAY create their own custom keyring(s).

‎s3-encryption/materials/s3-keyring.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# S3 Keyring
5+
6+
## Version
7+
8+
0.1.0
9+
10+
### Changelog
11+
12+
- 0.1.0
13+
- Initial
14+
15+
## Definitions
16+
17+
### Conventions used in this document
18+
19+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
20+
in this document are to be interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119).
21+
22+
## Overview
23+
24+
The S3EC SHOULD implement an S3 Keyring to consolidate validation and other functionality common to all S3 Keyrings.
25+
If implemented, the S3 Keyring MUST implement the Keyring interface.
26+
If implemented, the S3 Keyring MUST NOT be able to be instantiated as a Keyring instance.
27+
28+
### Abstract Methods
29+
30+
In addition to the methods defined in the Keyring interface, the S3 Keyring must define or support the following:
31+
32+
- The S3 Keyring MUST define an abstract method GenerateDataKey.
33+
- The S3 Keyring MUST define an abstract method EncryptDataKey.
34+
- The S3 Keyring MUST define an abstract method DecryptDataKey.
35+
36+
### Functionality
37+
38+
#### OnEncrypt
39+
40+
If the Plaintext Data Key in the input EncryptionMaterials is null, the S3 Keyring MUST call the GenerateDataKey method using the materials.
41+
If the materials returned from GenerateDataKey contain an EncryptedDataKey, the S3 Keyring MUST return the materials.
42+
If the materials returned from GenerateDataKey do not contain an EncryptedDataKey, the S3 Keyring MUST call the EncryptDataKey method using the materials.
43+
The OnEncrypt operation is responsible for ensuring that the EncryptionMaterials are valid and contain valid plaintext and encrypted data keys.
44+
45+
#### OnDecrypt
46+
47+
If the input DecryptionMaterials contains a Plaintext Data Key, the S3 Keyring MUST throw an exception.
48+
If the input collection of EncryptedDataKey instances contains any number of EDKs other than 1, the S3 Keyring MUST throw an exception.
49+
The S3 Keyring MAY validate that the Key Provider ID of the Encrypted Data Key matches the expected default Key Provider ID value.
50+
The S3 Keyring MUST call the DecryptDataKey method using the materials and add the resulting plaintext data key to the materials.
51+
The OnDecrypt operation is responsible for ensuring that the DecryptionMaterials contain valid plaintext and encrypted data keys.
52+
The OnDecrypt operation is also responsible for ensuring that the DecryptionMaterials are valid and contain valid plaintext and encrypted data keys.

‎s3-encryption/materials/s3-kms-keyring.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# KMS Keyring
5+
6+
## Overview
7+
8+
A keyring which interacts with AWS Key Management Service (AWS KMS) to create, encrypt, and decrypt data keys using AWS KMS keys.
9+
10+
## Definitions
11+
12+
### Conventions used in this document
13+
14+
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](https://tools.ietf.org/html/rfc2119).
15+
16+
## Interface
17+
18+
The KmsKeyring MUST implement the [Keyring interface](keyrings.md#interface) and include the behavior described in the [S3 Keyring](s3-keyring.md).
19+
20+
## Initialization
21+
22+
On initialization, the caller MAY provide an AWS KMS SDK client instance.
23+
If the caller does not provide an AWS KMS SDK client instance or provides a null value, the KmsKeyring MUST create a default KMS client instance.
24+
On initialization, the caller MUST provide an AWS KMS key identifier.
25+
26+
The KmsKeyring MAY validate that the AWS KMS key identifier is not null or empty.
27+
If the KmsKeyring validates that the AWS KMS key identifier is not null or empty, then it MUST throw an exception.
28+
The KmsKeyring MAY validate that the AWS KMS key identifier is [a valid AWS KMS Key identifier](../../framework/aws-kms/aws-kms-key-arn.md#a-valid-aws-kms-identifier).
29+
If the KmsKeyring validates that the AWS KMS key identifier is not a valid AWS KMS Key identifier, then it MUST throw an exception.
30+
31+
## Supported Wrapping Algorithm Modes
32+
33+
The KmsKeyring has two supported algorithm modes: KmsV1 and Kms+Context (V2).
34+
The KmsKeyring MUST NOT support encryption using KmsV1 mode.
35+
The KmsKeyring MUST support decryption using KmsV1 mode.
36+
The KmsV1 mode MUST be only enabled when legacy wrapping algorithms are enabled.
37+
The KmsKeyring MUST support encryption using Kms+Context mode.
38+
The KmsKeyring MUST support decryption using Kms+Context mode.
39+
The Kms+Context mode MUST be enabled as a fully-supported (non-legacy) wrapping algorithm.
40+
41+
### EncryptDataKey
42+
43+
The KmsKeyring MUST implement the EncryptDataKey method.
44+
The keyring MUST call [AWS KMS Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) using the configured AWS KMS client.
45+
The keyring must AWS KMS Encrypt call with a request constructed as follows:
46+
47+
- `KeyId` MUST be the configured AWS KMS key identifier.
48+
- `PlaintextDataKey` MUST be the plaintext data key in the [encryption materials](../structures.md#encryption-materials).
49+
- `EncryptionContext` MUST be the [encryption context](../structures.md#encryption-context) included in the input [encryption materials](../structures.md#encryption-materials).
50+
- A custom API Name or User Agent string SHOULD be provided in order to provide metrics on KMS calls associated with the S3 Encryption Client.
51+
52+
If the call to [AWS KMS Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) does not succeed, OnEncrypt MUST fail.
53+
54+
If the call to AWS KMS Encrypt is successful, OnEncrypt MUST return the `CiphertextBlob` as a collection of bytes.
55+
56+
### DecryptDataKey
57+
58+
The KmsKeyring MUST determine whether to decrypt using KmsV1 mode or Kms+Context mode.
59+
If the Key Provider Info of the Encrypted Data Key is "kms", the KmsKeyring MUST attempt to decrypt using KmsV1 mode.
60+
If the Key Provider Info of the Encrypted Data Key is "kms+context", the KmsKeyring MUST attempt to decrypt using Kms+Context mode.
61+
62+
#### KmsV1
63+
64+
To attempt to decrypt a particular [encrypted data key](../structures.md#encrypted-data-key), the KmsKeyring MUST call [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) with the configured AWS KMS client.
65+
66+
When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), the keyring must call with a request constructed as follows:
67+
68+
- `KeyId` MUST be the configured AWS KMS key identifier.
69+
- `CiphertextBlob` MUST be the [encrypted data key ciphertext](../structures.md#ciphertext).
70+
- `EncryptionContext` MUST be the [encryption context](../structures.md#encryption-context) included in the input [decryption materials](../structures.md#decryption-materials).
71+
- A custom API Name or User Agent string SHOULD be provided in order to provide metrics on KMS calls associated with the S3 Encryption Client.
72+
73+
The KmsKeyring MUST immediately return the plaintext as a collection of bytes.
74+
If the KmsKeyring fails to successfully decrypt the [encrypted data key](../structures.md#encrypted-data-key), then it MUST throw an exception.
75+
76+
#### Kms+Context
77+
78+
To attempt to decrypt a particular [encrypted data key](../structures.md#encrypted-data-key), the KmsKeyring MUST call [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) with the configured AWS KMS client.
79+
80+
When decrypting using Kms+Context mode, the KmsKeyring MUST validate the provided (request) encryption context with the stored (materials) encryption context.
81+
The stored encryption context with the two reserved keys removed MUST match the provided encryption context.
82+
If the stored encryption context with the two reserved keys removed does not match the provided encryption context, the KmsKeyring MUST throw an exception.
83+
84+
When calling [AWS KMS Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), the keyring must call with a request constructed as follows:
85+
86+
- `KeyId` MUST be the configured AWS KMS key identifier.
87+
- `CiphertextBlob` MUST be the [encrypted data key ciphertext](../structures.md#ciphertext).
88+
- `EncryptionContext` MUST be the [encryption context](../structures.md#encryption-context) included in the input [decryption materials](../structures.md#decryption-materials).
89+
- A custom API Name or User Agent string SHOULD be provided in order to provide metrics on KMS calls associated with the S3 Encryption Client.
90+
91+
The KmsKeyring MUST immediately return the plaintext as a collection of bytes.
92+
If the KmsKeyring fails to successfully decrypt the [encrypted data key](../structures.md#encrypted-data-key), then it MUST throw an exception.

0 commit comments

Comments
 (0)