Skip to content

Latest commit

 

History

History
150 lines (96 loc) · 6.07 KB

cmm-interface.md

File metadata and controls

150 lines (96 loc) · 6.07 KB

Cryptographic Materials Manager Interface

Version

0.1.0-preview

Implementations

Overview

The Cryptographic Materials Manager (CMM) assembles the cryptographic materials used to encrypt the message and decrypt the encrypted messages. 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:

Decrypt Materials Request

This is the input to the decrypt materials behavior.

The decrypt materials request MUST 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:

  • Algorithm Suite
    • If the encryption materials request contains an algorithm suite, the encryption materials returned SHOULD contain the same algorithm suite.
  • Plaintext Data Key
  • Encrypted Data Keys
    • Every encrypted data key in this list MUST correspond to the above plaintext data key.
  • Encryption Context
    • The CMM MAY modify the encryption context.

The encryption materials returned MAY include the following:

If the algorithm suite contains a signing algorithm:

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

  • The encryption materials returned MUST follow the specification for encryption-materials.
  • The value of the plaintext data key MUST be non-NULL.
  • The plaintext data key length MUST be equal to the key derivation input length.
  • The encrypted data keys list MUST contain at least one encrypted data key.
  • If the algorithm suite contains a signing algorithm, the encryption materials returned MUST include the generated signing key.

Decrypt Materials

When the CMM gets a decrypt materials request, it MUST return decryption materials appropriate for the 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.
  • Algorithm Suite
    • If the decrypt materials request contains an algorithm suite, the decryption materials returned SHOULD contain the same algorithm suite.

The decryption materials returned MAY include the following:

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