1.0.0
-
1.0.0
- Initial record
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.
This document describes the behavior by which a Structured Data is encrypted. We define encryption over this Structured Data to mean that authenticity is ensured over a non-empty set of Terminal Data, and confidentiality is ensured over a (possibly empty) subset of that Terminal Data.
The following inputs to this behavior are REQUIRED:
The following inputs to this behavior MUST be OPTIONAL:
The logical name for the structure. This can be the same as the physical name. For example the name of the table to hold the encrypted record.
The Crypto List to be encrypted.
The paths in the input Crypto List MUST be unique.
This Crypto List MUST NOT already contain data located at the header index or the footer index.
The Crypto List describes how each Terminal Data should be treated during encryption.
The Crypto List MUST include at least one Crypto Action that is not DO_NOTHING.
A CMM that implements the CMM interface.
The algorithm suite that SHOULD be used for encryption.
This algorithm suite MUST be a supported suite for Database Encryption (DBE); otherwise, this operation MUST yield an error.
See encryption context.
The prefix aws-crypto- is reserved for internal use by the AWS Encryption SDK; see the
the Default CMM spec
for one such use.
The operation MUST fail if an encryption context is provided which contains a key with the prefix aws-crypto-.
This operation MUST output the following:
An encrypted form of the input Crypto List, encrypted according to the behavior specified below.
All inputs MUST adhere to their requirements; otherwise this operation MUST immediately yield an error.
Given valid inputs, the Encrypt Structure operation is divided into several distinct steps:
- Retrieve Encryption Materials
- Calculate Intermediate Encrypted Structured Data
- Construct Encrypted Structured Data
This operation MUST perform all the above steps, and it MUST perform them in the above order.
If any of these steps fails, this operation MUST halt and indicate a failure to the caller.
This operation MUST calculate the appropriate CMM and encryption context.
This operation MUST obtain a set of encryption materials by calling Get Encryption Materials on the CMM calculated above.
This operation MUST call Get Encryption Materials on the CMM as follows.
- Encryption Context: This MUST be the encryption context calculated above.
- Commitment Policy: This MUST be REQUIRE_ENCRYPT_REQUIRE_DECRYPT.
- Algorithm Suite: If provided, this is the input algorithm suite; otherwise, this field MUST be the algorithm suite corresponding to the enum DBE.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384.
- Max Plaintext Length: This field MUST be the result of the calculation
encryptedTerminalDataNum * 2 + totalEncryptedTerminalValuesSizeencryptedTerminalDataNumis the number of Terminal Data in the input data being encrypted, as defined by the input Crypto Schema.totalEncryptedTerminalValuesSizeis the sum of the length of all Terminal Values in the input data being encrypted, as defined by the input Crypto Schema.
The algorithm suite used in all aspects of this operation MUST be the algorithm suite in the encryption materials returned from the Get Encryption Materials call.
Note that the algorithm suite in the retrieved encryption materials MAY be different from the input algorithm suite. If this algorithm suite is not a supported suite for Database Encryption (DBE), this operation MUST yield an error.
If no Crypto Action is configured to be SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT Crypto Action then the input cmm and encryption context MUST be used unchanged.
Otherwise, this operation MUST add an entry to the encryption context for every SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT Crypto Action Terminal Data in the input record, plus the Legend.
An error MUST be returned if any of the entries added to the encryption context in this step have the same key as any entry already in the encryption context.
The Legend MUST be named "aws-crypto-legend" and be a string with one character per attribute added above, with a one-to-one correspondence with the attributes sorted by their UTF8 encoding, each character designating the original type of the attribute, to allow reversing of the encoding.
- 'S' if the attribute was of type String
- 'N' if the attribute was of type Number
- 'L' if the attribute was of type Null or Boolean
- 'B' otherwise
Then, this operation MUST create a Required Encryption Context CMM with the following inputs:
- This input CMM as the underlying CMM.
- The name of every entry added above.
When a key-value pair is added to the encryption context, the key MUST be the concatenation of the literal "aws-crypto-attr." and the member strings of the path joined by the '.' character.
This mapping does not produce a unique output for every unique input. For example ['a.b'] and ['a', 'b'] both produce "a.b".
An error MUST be returned if an attempt is made to add two different attributes that produce the same encryption context key.
To construct the final Encrypted Structured Data, a pre-signature version of this Encrypted Structured Data must first be calculated. This will be referred to as the Intermediate Encryption Structured Data.
The calculations below REQUIRE generating a unique Message ID for this Encrypted Structured Data. The process used to generate this identifier MUST use a good source of randomness to make the chance of duplicate identifiers negligible.
The Intermediate Encryption Structured Data has the following specifics:
For every entry in the input Crypto List there MUST be an entry with the same canonical path in Intermediate Encrypted Structured Data.
There MUST be no other entries in the Intermediate Encrypted Structured Data.
The info used for the HKDF function MUST be
| Field | Length |
|---|---|
| "AWS_DBE_DERIVE_KEY" | 18 |
| Message ID | 32 |
The HKDF algorithm used to calculate the Field Root Key MUST be the Encryption Key KDF indicated by the algorithm suite, using a provided plaintext data key, no salt, and an info as calculated above
The FieldRootKey MUST be generated with the plaintext data key in the encryption materials
and the Message ID generated for this Encrypted Structured Data.
The FieldRootKey is combined with the ordinal position of a field within a record
to generate a unique FieldKey for encrypting that field.
The ordinal position is calculated by sorting the canonical path of all of the ENCRYPT_AND_SIGN fields, sorting those paths in ascending order, and taking the zero-based position of the field in that sorted list.
The calculated Field Root MUST have length equal to the algorithm suite's encryption key length.
The FieldKeyNonce for a given offset MUST be 16 bytes comprised of
| Field | Length | Interpretation |
|---|---|---|
| "AwsDbeField" | 11 | Literal Ascii String |
| 0x2c | 1 | 44, the length of the eventual FieldKey |
| offset | 4 | 32 bit integer representation of offset |
The FieldKey for a given key and offset MUST be the first 44 bytes
of the aes256ctr_stream
of the FieldRootKey and the FieldKeyNonce of three times the given offset.
The FieldKey is used to derive a specific Cipherkey for each specific TerminalData to be encrypted, and the nonces that are used for that encryption"
The Cipherkey MUST be the first 32 bytes of the FieldKey
The Nonce MUST be the remaining 12 bytes of the FieldKey
Encryption of Terminal Data takes a Terminal Data as input, and returns an encrypted Terminal Data.
The output encrypted Terminal Data MUST have a Terminal Type Id
equal 0xFFFF.
The output encrypted Terminal Data MUST have a Terminal Value with the following serialization:
| Field | Length |
|---|---|
| Terminal Type Id | 2 |
| Encrypted Terminal Value | Variable |
Terminal Type Id MUST equal the input Terminal Data's Terminal Type Id.
The Encrypted Terminal Value MUST be derived according to the following encryption:
- The encryption algorithm used is the encryption algorithm indicated in the algorithm suite.
- The AAD is the canonical path for this Terminal Data.
- The Cipherkey and Nonce are as calculated above.
- The plaintext is the Terminal Value for this Terminal Data.
Given an Intermediate Encrypted Structured Data, the signatures over this Structured Data may be calculated, and the final Encrypted Structured Data outputted.
The Header Field name MUST be aws_dbe_head
The Header Field TypeID MUST be 0xFFFF
The Header Field Value MUST be the full serialized header with commitment.
The encryption context field serialized in the header MUST contain all key-value pairs of the encryption context in the encryption materials that are not included in the required encryption context keys list.
The Footer Field name MUST be aws_dbe_foot
The Footer Field TypeID MUST be 0xFFFF
The Footer Field Value MUST be the serialized footer.
- For every entry in the input Crypto List an entry MUST exist with the same path in the final Encrypted Structured Data.
- The Header Field MUST exist in the final Encrypted Structured Data
- The Footer Field MUST exist in the final Encrypted Structured Data
- For every entry in the final Encrypted Structured Data, other than the header and footer, an entry MUST exist with the same path in the input Crypto List.
For each entry in the final Encrypted Structured Data:
If the Crypto Schema indicates a Crypto Action of ENCRYPT_AND_SIGN, the Terminal Data MUST have Terminal Type ID equal to 0xffff and the value MUST be the encryption of the input's Terminal Data.
Otherwise, this Terminal Data MUST have Terminal Type ID and Terminal Value equal to the input Terminal Data's.