transitive-requirements.md

Transitive requirements for supported formats

Version

0.1.0

Implementations

Overview

There are implementation specific details that are relevant to some algorithm suites. These requirements may not be enforced by the Material Providers Library. This is the place to track these requirements.

These requirements need to be ensured in the implementation of the encryption and decryption of each supported format. By placing them in a separate markdown the expectation is that this file can be parsed by duvet and the appropriate annotations can be added in each library implementing a supported format.

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.

HKDF Encryption Key

If an algorithm suite uses HKDF to derive the encryption key the AWS Encryption SDK MUST use HKDF with the following specifics:

• The hash function MUST be specified by the algorithm suite key derivation settings.
• For the extract step:
  • The input keying material MUST be the data key generated by the key provider.
  • The length of the input keying material MUST equal the key derivation input length specified by the algorithm suite encryption key derivation settings.
  • If there is no salt length defined for the algorithm suite encryption key derivation commitment setting, the the salt MUST be a byte sequence of 0 as long as the hash length in bytes.
  • If salt length is defined for the algorithm suite encryption key derivation commitment setting, the salt MUST be the message ID with a length equal to the salt length.
• For the expand step:
  • The input pseudorandom key MUST be the output from the extract step.
  • The length of the output keying material MUST equal the encryption key length specified by the algorithm suite encryption settings.
  • If key commitment for the algorithm suite encryption key derivation setting is True, then the input info MUST be a concatenation of the algorithm suite ID followed by the string DERIVEKEY as UTF8 encoded bytes.
  • If key commitment for the algorithm suite encryption key derivation setting is False, the the input info MUST be a concatenation of the algorithm suite ID followed by the message ID.

HKDF Commit Key

If an algorithm suite uses HKDF to derive the commitment key the AWS Encryption SDK MUST use HKDF with the following specifics:

• The hash function MUST be specified by the algorithm suite commitment settings.
• For the extract step:
  • The input keying material MUST be the data key generated by the key provider.
  • The length of the input keying material MUST equal the key derivation input length specified by the algorithm suite commit key derivation setting.
  • The salt MUST be the message ID with a length of 256 bits.
• For the expand step:
  • The input pseudorandom key MUST be the output from the extract step.
  • The length of the output keying material MUST equal the algorithm suite data length specified by the supported algorithm suites.
  • The input info MUST the string COMMITKEY as UTF8 encoded bytes by the algorithm suite commitment settings.

For algorithm suites that support commitment, the AWS Encryption SDK SHOULD only perform the extract step once and use the same output from the extract step for both the encryption key and the commitment key.

Verification of the commitment key MUST be a constant time comparison.

ECDSA

Specification: ANS X9.62-2005 (Not available publicly, but the specification for ECDSA is replicated in SEC 1 version 2.0. Information about obtaining copies of ANS X9.62 is available at http://www.x9.org.)

The Elliptic Curve Digital Signature Algorithm (ECDSA) is a signature algorithm.

If specified to use ECDSA, the AWS Encryption SDK MUST use ECDSA with the following specifics:

• The elliptic curve is specified by the algorithm suite. The specific curves are defined in Digital Signature Standard (DSS) (FIPS PUB 186-4).
• The hash function is specified by the algorithm suite.
• When included in the message, the output signature value is encoded using the ANS.1 structure ECDSA-Sig-Value defined in section C.5 of Sec 1 version 2.0:

ECDSA-Sig-Value ::= SEQUENCE {
    r INTEGER,
    s INTEGER
}

• If serialized, the binary form of the verification key is equal to the elliptic curve point Q compressed according to section 2.3.3 of SEC 1 version 2.0.