Skip to content

Commit b0f55f8

Browse files
lavalerijosecorella
lavaleri
authored and
josecorella
committed
fix: Organize alg suites by format not library (#64)
1 parent 12aaafc commit b0f55f8

6 files changed

+96
-76
lines changed

‎framework/algorithm-suites.md

Lines changed: 58 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,15 @@
55

66
## Version
77

8-
0.3.0
8+
0.4.0
99

1010
### Changelog
1111

1212
- 0.4.0
1313

14+
- Reframe "supported libraries" as "supported formats"
1415
- Add suites with symmetric signing
16+
- Add DBE as supported format
1517

1618
- 0.3.0
1719
- [Material Providers Library (MPL)](../changes/2022-06-19_seperate_material_providers/change.md)
@@ -30,7 +32,7 @@
3032
## Overview
3133

3234
An algorithm suite is a collection of cryptographic algorithms and related values.
33-
The algorithm suite defines the behaviors [supported libraries](#supported-libraries) MUST follow for cryptographic operations.
35+
The algorithm suite defines the behaviors [supported formats](#supported-formats) MUST follow for cryptographic operations.
3436

3537
## Definitions
3638

@@ -93,25 +95,24 @@ Specification: [RFC 5869](https://tools.ietf.org/html/rfc5869)
9395

9496
The HMAC-based extract-and-expand key derivation function (HKDF) is a key derivation algorithm.
9597

96-
## Supported Libraries
98+
## Supported Formats
9799

98-
The following tables includes the dependant libraries
99-
supported by the Material Providers Library.
100+
The following table inclues the cryptographic formats supported by the Material Providers Library.
100101
Both short and long name MUST be unique.
101102

102-
| Library (long name) | Library (short name) |
103-
| -------------------------- | -------------------- |
104-
| AWS Encryption SDK | ESDK |
105-
| S3 Encryption Client | S3EC |
106-
| DynamoDb Encryption Client | DDBEC |
103+
| Cryptographic Format (long) | Cryptographic Format (short) |
104+
| -------------------------------------------- | ---------------------------- |
105+
| AWS Encryption SDK Message Format | ESDK |
106+
| S3 Encryption Client Cryptographic Format | S3EC |
107+
| AWS Database Encryption Cryptographic Format | DBE |
107108

108-
## Supported Library Algorithm Suites ENUM
109+
## Supported Format Algorithm Suites ENUM
109110

110111
The following tables includes the algorithm suites
111112
supported by the Material Providers Library
112-
for each [supported library](#supported-libraries).
113+
for each [supported format](#supported-formats).
113114
The Material Providers Library MUST provide
114-
a set of algorithm suite ENUM for each [supported library](#supported-libraries).
115+
a set of algorithm suite ENUM for each [supported format](#supported-format).
115116

116117
| ESDK Algorithm Suite ENUM |
117118
| ------------------------------------------------- |
@@ -133,41 +134,41 @@ a set of algorithm suite ENUM for each [supported library](#supported-libraries)
133134
| ALG_AES_256_CTR_IV16_TAG16_NO_KDF |
134135
| ALG_AES_256_GCM_IV12_TAG16_NO_KDF |
135136

136-
| DDBEC Algorithm Suite ENUM |
137+
| DBE Algorithm Suite ENUM |
137138
| -------------------------------------------------------------------- |
138139
| ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384 |
139140
| ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384 |
140141

141142
## Supported Algorithm Suites ENUM
142143

143144
The Material Providers Library MUST provide
144-
an ENUM that is the super set of all the [supported library algorithm suites enum](#supported-library-algorithm-suites-enum)
145+
an ENUM that is the super set of all the [supported format algorithm suites enum](#supported-format-algorithm-suites-enum)
145146
called the Algorithm Suite ENUM.
146147
In this specification this Algorithm Suite ENUM
147-
will be denoted as `Library.LibraryENUM`
148-
to uniquely identify an Algorithm Suite ENUM across all supported libraries.
148+
will be denoted as `Format.FormatENUM`
149+
to uniquely identify an Algorithm Suite ENUM across all supported formats.
149150
For example `ESDK.ALG_AES_128_GCM_IV12_TAG16_NO_KDF`
150151
is the Algorithm Suite ENUM for the ESDK Algorithm Suite ENUM `ALG_AES_128_GCM_IV12_TAG16_NO_KDF`.
151-
This means that different libraries MAY have duplicate Library Algorithm Suite ENUM.
152-
153-
| Algorithm Suite ENUM |
154-
| -------------------------------------------------------------------------- |
155-
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 |
156-
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY |
157-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 |
158-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 |
159-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 |
160-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256 |
161-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256 |
162-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256 |
163-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_NO_KDF |
164-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_NO_KDF |
165-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_NO_KDF |
166-
| S3EC.ALG_AES_256_CBC_IV16_NO_KDF |
167-
| S3EC.ALG_AES_256_CTR_IV16_TAG16_NO_KDF |
168-
| S3EC.ALG_AES_256_GCM_IV12_TAG16_NO_KDF |
169-
| DDBEC.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384 |
170-
| DDBEC.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384 |
152+
This means that different formats MAY have duplicate Format Algorithm Suite ENUM.
153+
154+
| Algorithm Suite ENUM |
155+
| ------------------------------------------------------------------------ |
156+
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 |
157+
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY |
158+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 |
159+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 |
160+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 |
161+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256 |
162+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256 |
163+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256 |
164+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_NO_KDF |
165+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_NO_KDF |
166+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_NO_KDF |
167+
| S3EC.ALG_AES_256_CBC_IV16_NO_KDF |
168+
| S3EC.ALG_AES_256_CTR_IV16_TAG16_NO_KDF |
169+
| S3EC.ALG_AES_256_GCM_IV12_TAG16_NO_KDF |
170+
| DBE.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384 |
171+
| DBE.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384 |
171172

172173
## Supported Algorithm Suites
173174

@@ -177,24 +178,24 @@ and MUST NOT be used
177178
as an Algorithm Suite ID in the future.
178179
Algorithm Suite ID MUST be a unique hex value across all supported algorithm suites.
179180

180-
| Algorithm Suite ENUM | Algorithm Suite ID (hex) | Message Format Version | Algorithm Suite Data Length (bytes) |
181-
| -------------------------------------------------------------------------- | ------------------------ | ---------------------- | ----------------------------------- |
182-
| DDBEC.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384 | 67 00 | 1.0 | N/A |
183-
| DDBEC.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384 | 67 01 | 1.0 | N/A |
184-
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 | 05 78 | 2.0 | 32 |
185-
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY | 04 78 | 2.0 | 32 |
186-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 | 03 78 | 1.0 | N/A |
187-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 | 03 46 | 1.0 | N/A |
188-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 | 02 14 | 1.0 | N/A |
189-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256 | 01 78 | 1.0 | N/A |
190-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256 | 01 46 | 1.0 | N/A |
191-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256 | 01 14 | 1.0 | N/A |
192-
| ESDK.ALG_AES_256_GCM_IV12_TAG16_NO_KDF | 00 78 | 1.0 | N/A |
193-
| ESDK.ALG_AES_192_GCM_IV12_TAG16_NO_KDF | 00 46 | 1.0 | N/A |
194-
| ESDK.ALG_AES_128_GCM_IV12_TAG16_NO_KDF | 00 14 | 1.0 | N/A |
195-
| S3EC.ALG_AES_256_CBC_IV16_NO_KDF | 00 70 | 1.0 | N/A |
196-
| S3EC.ALG_AES_256_CTR_IV16_TAG16_NO_KDF | 00 71 | 1.0 | N/A |
197-
| S3EC.ALG_AES_256_GCM_IV12_TAG16_NO_KDF | 00 72 | 1.0 | N/A |
181+
| Algorithm Suite ENUM | Algorithm Suite ID (hex) | Message Format Version | Algorithm Suite Data Length (bytes) |
182+
| ------------------------------------------------------------------------ | ------------------------ | ---------------------- | ----------------------------------- |
183+
| DBE.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384 | 67 00 | 1.0 | N/A |
184+
| DBE.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384 | 67 01 | 1.0 | N/A |
185+
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 | 05 78 | 2.0 | 32 |
186+
| ESDK.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY | 04 78 | 2.0 | 32 |
187+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 | 03 78 | 1.0 | N/A |
188+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 | 03 46 | 1.0 | N/A |
189+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 | 02 14 | 1.0 | N/A |
190+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256 | 01 78 | 1.0 | N/A |
191+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256 | 01 46 | 1.0 | N/A |
192+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256 | 01 14 | 1.0 | N/A |
193+
| ESDK.ALG_AES_256_GCM_IV12_TAG16_NO_KDF | 00 78 | 1.0 | N/A |
194+
| ESDK.ALG_AES_192_GCM_IV12_TAG16_NO_KDF | 00 46 | 1.0 | N/A |
195+
| ESDK.ALG_AES_128_GCM_IV12_TAG16_NO_KDF | 00 14 | 1.0 | N/A |
196+
| S3EC.ALG_AES_256_CBC_IV16_NO_KDF | 00 70 | 1.0 | N/A |
197+
| S3EC.ALG_AES_256_CTR_IV16_TAG16_NO_KDF | 00 71 | 1.0 | N/A |
198+
| S3EC.ALG_AES_256_GCM_IV12_TAG16_NO_KDF | 00 72 | 1.0 | N/A |
198199

199200
## Algorithm Suites Encryption Key Derivation Settings
200201

@@ -514,8 +515,8 @@ If the algorithm suite does not include a symmetric signature algorithm:
514515
### Message Format Version
515516

516517
Indicates the serialization or message format version for the supported algorithm suite.
517-
This value can be duplicated across [supported libraries](#supported-libraries).
518-
This MUST be used to branch any serialization/deserialization logic in [supported libraries](#supported-libraries).
518+
This value can be duplicated across [supported formats](#supported-formats).
519+
This MUST be used to branch any serialization/deserialization logic in [supported formats](#supported-formats).
519520

520521
#### Supported Message Format Version
521522

‎framework/cmm-interface.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434

3535
The Cryptographic Materials Manager (CMM) assembles the cryptographic materials
3636
used to encrypt and decrypt the encrypted messages
37-
for each [supported library](./algorithm-suites.md#supported-libraries).
37+
for each [supported format](./algorithm-suites.md#supported-formats).
3838
The CMM interface describes the interface that all CMMs MUST implement.
3939

4040
## Definitions

‎framework/commitment-policy.md

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,13 @@
55

66
## Version
77

8-
0.2.0
8+
0.3.0
9+
10+
### Changelog
11+
12+
- 0.3.0
13+
14+
- Add commitment policy for DBE.
915

1016
## Implementations
1117

@@ -28,17 +34,17 @@ It is important that all messages that could be sent to a host can be decrypted
2834
A top level client makes such settings [hard to misuse](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/tenets.md#hard-to-misuse)
2935
because anything a client encrypts can be decrypted by the same client.
3036

31-
## Supported Library Commitment Policy ENUM
37+
## Supported Format Commitment Policy ENUM
3238

3339
The following tables include the commitment policies
3440
supported by the Material Providers Library
35-
for each [supported library](./algorithm-suites.md#supported-libraries).
41+
for each [supported format](./algorithm-suites.md#supported-formats).
3642

3743
The Material Providers Library MUST provide
38-
a distinct commitment policy ENUM for each library.
39-
The `Library` Commitment Policy ENUM, where `Library`
40-
is a value from [supported library short name](./algorithm-suites.md#supported-libraries).
41-
This ENUM can be used by each library to configured
44+
a distinct commitment policy ENUM for each format.
45+
The `Format` Commitment Policy ENUM, where `Format`
46+
is a value from [supported format short name](./algorithm-suites.md#supported-formats).
47+
This ENUM can be used to configure
4248
which Commitment Policies it supports.
4349

4450
| ESDK Commitment Policy ENUM |
@@ -47,23 +53,28 @@ which Commitment Policies it supports.
4753
| REQUIRE_ENCRYPT_ALLOW_DECRYPT |
4854
| REQUIRE_ENCRYPT_REQUIRE_DECRYPT |
4955

56+
| DBE Commitment Policy ENUM |
57+
| ------------------------------- |
58+
| REQUIRE_ENCRYPT_REQUIRE_DECRYPT |
59+
5060
## Supported Commitment Policy ENUM
5161

5262
The Material Providers Library also MUST provide
5363
a union ENUM for all distinct commitment policy ENUMs
5464
called the Commitment Policy ENUM.
5565
In this specification this union Commitment Policy ENUM
56-
will be denoted as `Library.LibraryENUM`
57-
to uniquely identify an Commitment Policy ENUM across all supported libraries.
66+
will be denoted as `Format.FormatENUM`
67+
to uniquely identify an Commitment Policy ENUM across all supported formats.
5868
For example `ESDK.FORBID_ENCRYPT_ALLOW_DECRYPT`
59-
is the Commitment Policy ENUM for the ESDK Commitment Policy ENU `FORBID_ENCRYPT_ALLOW_DECRYPT`.
60-
This means that different libraries MAY have duplicate Library Commitment Policy ENUM.
69+
is the Commitment Policy ENUM for the ESDK Commitment Policy ENUM `FORBID_ENCRYPT_ALLOW_DECRYPT`.
70+
This means that different formats MAY have duplicate Format Commitment Policy ENUM.
6171

6272
| Algorithm Suite ENUM |
6373
| ------------------------------------ |
6474
| ESDK.FORBID_ENCRYPT_ALLOW_DECRYPT |
6575
| ESDK.REQUIRE_ENCRYPT_ALLOW_DECRYPT |
6676
| ESDK.REQUIRE_ENCRYPT_REQUIRE_DECRYPT |
77+
| DBE.REQUIRE_ENCRYPT_REQUIRE_DECRYPT |
6778

6879
#### ESDK.FORBID_ENCRYPT_ALLOW_DECRYPT
6980

@@ -88,3 +99,11 @@ When the commitment policy `ESDK.REQUIRE_ENCRYPT_REQUIRE_DECRYPT` is configured:
8899
- `05 78` MUST be the default algorithm suite
89100
- [Get Encryption Materials](./cmm-interface.md#get-encryption-materials) MUST only support algorithm suites that have a [Key Commitment](./algorithm-suites.md#algorithm-suites-encryption-key-derivation-settings) value of True
90101
- [Decrypt Materials](./cmm-interface.md#decrypt-materials) MUST only support algorithm suites that have a [Key Commitment](./algorithm-suites.md#algorithm-suites-encryption-key-derivation-settings) value of True
102+
103+
#### DBE.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
104+
105+
The commitment policy `ESDK.REQUIRE_ENCRYPT_REQUIRE_DECRYPT` is always configured for DBE,
106+
and results in the following requirements:
107+
108+
- [Get Encryption Materials](./cmm-interface.md#get-encryption-materials) MUST only support algorithm suites that have a [Key Commitment](./algorithm-suites.md#algorithm-suites-encryption-key-derivation-settings) value of True
109+
- [Decrypt Materials](./cmm-interface.md#decrypt-materials) MUST only support algorithm suites that have a [Key Commitment](./algorithm-suites.md#algorithm-suites-encryption-key-derivation-settings) value of True

‎framework/required-encryption-context-cmm.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ This set of keys MUST
2222

2323
- Exist in the encryption context of all [Encryption Materials Requests](./cmm-interface.md#encryption-materials-request).
2424
- Exist in the [required encryption context keys](./structures.md#required-encryption-context-keys) for returned [encryption materials](./structures.md#encryption-materials)
25-
so that [supported libraries](./algorithm-suites.md#supported-libraries) will not serialize these values.
25+
so that these values will not be serialized into the [supported formats](./algorithm-suites.md#supported-formats).
2626
- Exist the reproduced encryption context of all [Decrypt Materials Requests](#decrypt-materials-request).
2727

2828
## Definitions

‎framework/structures.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ The value of this key MUST be kept secret.
201201
##### Required Encryption Context Keys
202202

203203
Communicates to higher level `encrypt` APIs
204-
in [supported libraries](algorithm-suites.md#supp#supported-libraries)
204+
of [supported formats](algorithm-suites.md#supp#supported-formats)
205205
how to split the encryption context
206206
into elements that are authenticated and stored
207207
from elements that are only authenticated and not stored.
@@ -291,7 +291,7 @@ included in this decryption material's [algorithm suite](#algorithm-suite-1).
291291
##### Required Encryption Context Keys
292292

293293
A set of strings to communicate to higher level `decrypt` APIs
294-
in [supported libraries](algorithm-suites.md#supp#supported-libraries)
294+
of [supported formats](algorithm-suites.md#supp#supported-formats)
295295
how to split the [encryption context](#encryption-context-2)
296296
into elements that are authenticated and stored
297297
from elements that are only authenticated

0 commit comments

Comments
 (0)