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 the DynamoDB Item Encryptor decrypts a DynamoDB Item originally encrypted via the Encrypt Item operation.
The following inputs to this behavior are REQUIRED:
The DynamoDB Item is the item to be decrypted by this behavior.
This item MUST include an Attribute with a name that matches the DynamoDB Partition Key Name configured on the DynamoDB Item Encryptor. Otherwise this operation MUST yield an error.
If the DynamoDB Item Encryptor has a DynamoDB Sort Key Name configured, this item MUST include an Attribute with that name. Otherwise this operation MUST yield an error.
This operation MUST output the following:
This operation MUST also output a Parsed Header if the following is true:
- The operation is not using a Legacy Policy that allows legacy decrypts, and the input item is a legacy item.
- The operation is not using a Plaintext Policy that allows plaintext reads, and the input item is a plaintext item.
The DynamoDB Item is the decryption of the [input DynamoBD Item](#input dynamodb-item).
This structure MUST contain the following values, representing the deserialized form of the header of the input encrypted structure:
- Algorithm Suite ID: The Algorithm Suite ID associated with the Format Flavor on the header.
- Attribute Actions: The Crypto Schema for each signed attribute, calculated using the Crypto Legend in the header, the signature scope used for decryption, and the data in the structure, converted into Attribute Actions.
- Encrypted Data Keys: The Encrypted Data Keys stored in the header.
- Stored Encryption Context: The Encryption Context stored in the header.
- Encryption Context: The full Encryption Context used.
- Selector Context : the AttributeMap as passed to the Branch Key Supplier
If a Legacy Policy of
FORBID_LEGACY_ENCRYPT_FORBID_LEGACY_DECRYPT is configured,
and the input item is an item written in the legacy format,
this operation MUST fail.
If a Legacy Policy of
FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT or FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT is configured,
and the input item is an item written in the legacy format,
this operation MUST delegate decryption of this item to the
Legacy Encryptor,
using the configured Attribute Flags as input.
The item returned by this operation MUST be the item outputted by the
Legacy Encryptor.
Otherwise, this operations continues as follows.
If a Plaintext Policy of
FORCE_PLAINTEXT_WRITE_ALLOW_PLAINTEXT_READ or FORBID_PLAINTEXT_WRITE_ALLOW_PLAINTEXT_READ is specified,
and the input item is a plaintext item
this operation MUST NOT decrypt the input item,
and MUST passthrough that item as the output.
This behavior REQUIRES a Structured Data which is converted from the input DynamoDB Item.
This operation MUST create a Required Encryption Context CMM with the following inputs:
- This item encryptor's CMM as the underlying CMM.
- The keys from the DynamoDB Item Base Context.
Given the converted Structured Data, this operation MUST delegate decryption of this data to Structured Encryption Client's Decrypt Structure, with the following inputs:
- Encrypted Structured Data MUST be the Structured Data converted above.
- Authenticate Schema MUST be a Authenticate Schema
built with the following requirements:
- For every Attribute in the input DynamoDB Item that is in the signature scope, there MUST exist a SIGN Authenticate Action in the Authenticate Schema, string indexed at the top level by that attribute name.
- For every Attribute in the input DynamoDB Item that is not in the signature scope, there MUST exist a DO_NOT_SIGN Authenticate Action in the Authenticate Schema, string indexed at the top level by that attribute name.
- The number of Authenticate Actions in the Authenticate Schema MUST EQUAL the number of Attributes on the input DynamoDB Item.
- Encryption Context MUST be the input Item's DynamoDB Item Base Context.
- CMM MUST be the CMM constructed above.
The output to this behavior is the conversion of the decrypted Structured Data determined above into the output DynamoDB Item.
The output MUST also include a Parsed Header that contains data that was serialized into the header included in the output DynamoDb Item.
The item to be encrypted MUST have an attribute named aws_dbe_head.
The attribute named aws_dbe_head MUST be of type B Binary.
The first byte of that value is the Version Number.
If the Version Number is 2, then the base context MUST be the version 2 context.
If the Version Number is 1, the base context MUST be the version 1 context.
If the Version Number is not 1 or 2, the operation MUST return an error.
The Signature Scope is a client-side configuration of what attributes should be included within signature calculations whenever encrypting or decrypting items.
An Attribute on a DynamoDB Item MUST NOT be considered as within the signature scope if it's Attribute Name is included in Unauthenticated Attributes or if it's Attribute Name begins with the prefix specified in Unauthenticated Attribute Prefix. Otherwise, Attributes MUST be considered as within the signature scope.
If an Authenticate Action other than DO_NOTHING is configured for an attribute name included in Unauthenticated Attributes or beginning with the prefix specified in Unauthenticated Attribute Prefix, this operation MUST yield an error.
An item MUST be determined to be encrypted under the legacy format if it contains attributes for the material description and the signature. These are usually "amzn-ddb-map-desc" and "amzn-ddb-map-sig" respectively, although the DynamoDbEncryptor allows callers to configure custom names for these attributes.
An item MUST be determined to be plaintext if it does not contain attributes with the names "aws_dbe_head" and "aws_dbe_foot".
Note that this does not conflict with the legacy item definition, as there is no configuration state which needs to be able to distinguish between legacy items and plaintext items.