Skip to content

Latest commit

 

History

History
205 lines (141 loc) · 10.2 KB

cmm-interface.md

File metadata and controls

205 lines (141 loc) · 10.2 KB

Cryptographic Materials Manager Interface

Version

0.3.0

Changelog

  • 0.3.0

    • Clarify handling of the aws-crypto-public-key encryption context key.

  • 0.2.0

  • 0.1.0-preview

    • Initial record

Implementations

Language Confirmed Compatible with Spec Version Minimum Version Confirmed Implementation
C 0.1.0-preview 0.1.0 materials.h
Javascript 0.1.0-preview 0.1.0 materials_manager.ts
Python 0.1.0-preview 1.3.0 materials_managers
Java 0.1.0-preview 1.3.0 CryptoMaterialsManager.java

Overview

The Cryptographic Materials Manager (CMM) assembles the cryptographic materials used to encrypt and decrypt the encrypted messages for each supported format. The CMM interface describes the interface that all CMMs MUST implement.

Definitions

Conventions used in this document

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.

Supported CMMs

The AWS Encryption SDK provides the following built-in CMM types:

Note: A user MAY create their own custom CMM.

Interface

Inputs

The inputs to the CMM are groups of related fields, referred to as:

Encryption Materials Request

This is the input to the get encryption materials behavior.

The encryption materials request MUST include the following:

The encryption request MAY include the following:

  • Algorithm Suite Id
  • Required Encryption Context Keys - a set of strings.
  • Max Plaintext Length
    • This value represents the maximum length of the plaintext to be encrypted using the returned materials. The length of the plaintext to be encrypted MUST not be larger than this value.

Decrypt Materials Request

This is the input to the decrypt materials behavior.

The decrypt materials request MUST include the following:

The decrypt materials request MAY include the following:

Behaviors

The CMM Interface MUST support the following behaviors:

Get Encryption Materials

When the CMM gets an encryption materials request, it MUST return encryption materials appropriate for the request.

The encryption materials returned MUST include the following:

If the algorithm suite contains a signing algorithm:

  • The CMM MUST include a signing key.
  • The CMM SHOULD also add a key-value pair using the reserved key aws-crypto-public-key to the encryption context. If it does, the mapped value SHOULD be the signature verification key corresponding to the signing key.

If the algorithm suite does not contain a signing algorithm:

  • The CMM SHOULD NOT add a key-value pair using the reserved key aws-crypto-public-key to the encryption context.

The CMM MUST ensure that the encryption materials returned are valid.

Decrypt Materials

When the CMM gets a decrypt materials request, it MUST return decryption materials appropriate for the request.

If the requested algorithm suite does not include a signing algorithm but the encryption context includes the reserved aws-crypto-public-key key, the operation SHOULD fail. Likewise, if the requested algorithm suite includes a signing algorithm but the encryption context does not include the reserved aws-crypto-public-key key, the operation SHOULD fail.

The CMM MUST validate the Encryption Context by comparing it to the customer supplied Reproduced Encryption Context in decrypt materials request. For every key that exists in both Reproduced Encryption Context and Encryption Context, the values MUST be equal or the operation MUST fail.

The CMM MAY fail if it expects key-value pairs that do not exist in Reproduced Encryption Context on the decrypt materials request.

The decryption materials returned MUST include the following:

  • Plaintext Data Key
  • Encryption Context
    • The CMM MAY modify the encryption context.
    • The operations made on the encryption context on the Get Encryption Materials call SHOULD be inverted on the Decrypt Materials call.
    • All key-value pairs that exist in Reproduced Encryption Context but do not exist in encryption context on the decrypt materials request SHOULD be appended to the decryption materials.
  • Algorithm Suite
    • If the decrypt materials request contains an algorithm suite, the decryption materials returned SHOULD contain the same algorithm suite.
  • Required Encryption Context Keys
    • This set MUST include all keys added to the decryption materials encryption context that existed in the decrypt materials request's reproduced encryption context but did not exist in the decrypt materials request's encryption context.
    • All keys in this set MUST exist in the decryption materials encryption context.

If the algorithm suite obtained from the decryption request contains a signing algorithm, the decryption materials MUST include the signature verification key.

The CMM MUST ensure that the decryption materials returned are valid.

  • The decryption materials returned MUST follow the specification for decryption-materials.
  • The value of the plaintext data key MUST be non-NULL.
  • The plaintext data key returned MUST correspond with at least one of the encrypted data keys.
    • The is typically done by constructing a CMM that uses keyrings/master keys.

Customization

The CMM is an ideal point for customization and extension.

Example scenarios include:

  • Interacting with other CMMs
  • Using Keyring(s)
  • Modifying the encryption context
  • Managing the signing/verification keys
  • Data key Caching
  • Providing support for policy enforcement