Skip to content

Latest commit

 

History

History
225 lines (141 loc) · 10.7 KB

algorithm-suites.md

File metadata and controls

225 lines (141 loc) · 10.7 KB

Algorithm Suites

Version

0.1.0-preview

Implementations

Overview

An algorithm suite is a collection of cryptographic algorithms and related values. The algorithm suite defines the behaviors the AWS Encryption SDK MUST follow for cryptographic operations.

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.

AES

Specification: NIST FIPS 297

The Advanced Encryption Standard (AES) is a symmetric block cipher encryption algorithm.

GCM

Specification: NIST Special Publication 800-38D

Galois/Counter Mode is a mode of operation for block ciphers that provides authenticated encryption with additional data (AEAD).

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

  • The internal block cipher is the encryption algorithm specified by the algorithm suite.

Identity KDF

The identity key derivation function (Identity KDF) is a key derivation algorithm.

The Identity KDF MUST take a byte sequence as input, and MUST return the input, unchanged, as output.

If included in the algorithm suite, the algorithm suite's encryption key length MUST equal the algorithm suite's key derivation input length.

HKDF

Specification: RFC 5869

The HMAC-based extract-and-expand key derivation function (HKDF) is a key derivation algorithm.

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

  • The hash function is specified by the algorithm suite.
  • For the extract step:
    • No salt is used.
    • The input keying material is the data key generated by the key provider.
  • For the expand step:
    • The input pseudorandom key is the output from the extract step.
    • The input info is a concatenation of the algorithm suite ID followed by the message ID.
    • The length of the output keying material is the encryption key length specified by the algorithm suite.

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:

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.

Supported Algorithm Suites

The following table includes the algorithm suites supported by the AWS Encryption SDK. The values for each field of each algorithm suite is specified below.

Algorithm Suite ID (hex) Encryption Algorithm Encryption Algorithm Mode Encryption Key Length (bits) IV Length (bytes) Authentication Tag Length (bytes) Key Derivation Algorithm Key Derivation Input Length (bits) Signature Algorithm Is Default
03 78 AES GCM 256 12 16 HKDF with SHA-384 256 ECDSA with P-384 and SHA-384 True
03 46 AES GCM 192 12 16 HKDF with SHA-384 192 ECDSA with P-384 and SHA-384 False
02 14 AES GCM 128 12 16 HKDF with SHA-256 128 ECDSA with P-256 and SHA-256 False
01 78 AES GCM 256 12 16 HKDF with SHA-256 256 Not applicable False
01 46 AES GCM 192 12 16 HKDF with SHA-256 192 Not applicable False
01 14 AES GCM 128 12 16 HKDF with SHA-256 128 Not applicable False
00 78 AES GCM 256 12 16 Identity KDF 256 Not applicable False
00 46 AES GCM 192 12 16 Identity KDF 192 Not applicable False
00 14 AES GCM 128 12 16 Identity KDF 128 Not applicable False

Structure

The fields described below are REQUIRED to be specified by algorithm suites, unless otherwise specified.

Algorithm Suite ID

A 2-byte hex value that uniquely identifies an algorithm suite.

Encryption Algorithm

The block cipher encryption algorithm.

The length of the input encryption key MUST equal the encryption key length specified by the algorithm suite.

Supported Encryption Algorithms

Encryption Algorithm Mode

The AEAD operation mode used with the encryption algorithm.

The length of the input IV MUST equal the IV length specified by the algorithm suite. The length of the authentication tag MUST equal the authentication tag length specified by the algorithm suite.

Supported Encryption Algorithm Modes

Encryption Key Length

The length of the encryption key used as input to the encryption algorithm.

IV Length

The length of the initialization vector (IV) used with the encryption algorithm.

Authentication Tag Length

The length of the authentication tag used with AEAD.

Key Derivation Algorithm

The key derivation algorithm defines what key derivation function (KDF) to use for encryption key generation.

The specified KDF algorithm MUST be used to generate the encryption algorithm encryption key input. The length of the key derivation algorithm input MUST equal the key derivation input length specified by the algorithm suite. The length of the output encryption key MUST be equal to the encryption key length specified by the algorithm suite.

Supported Key Derivation Algorithms

Key Derivation Input Length

The length of the input to the Key Derivation Algorithm.

Signature Algorithm

This field is OPTIONAL.

The signature algorithm defines what algorithm to use for signature generation and verification.

If the algorithm suite includes a signature algorithm:

  • Signatures MUST be generated using the specified signature algorithm.
  • Signatures MUST be verified using the specified signature algorithm.

If the algorithm suite does not include a signature algorithm:

  • Signatures MUST NOT be generated.
  • Signatures MUST NOT be verified.

Supported Signature Algorithms

Is Default

Indicates which algorithm suite is the default algorithm suite for the AWS Encryption SDK.

Test Vectors

TODO

Security Considerations

Why is no salt used for HKDF?

[TODO]

Which algorithm suite should I use?

You SHOULD use the default algorithm suite (0x0378).

You MAY use the non-default AES-GCM with key derivation and signing key algorithm suites (0x0346, 0x0214) if key derivation input lengths of other sizes are required.

If the users who encrypt and the users who decrypt are equally trusted, you MAY use AES-GCM with only key derivation algorithm suites (0x0178, 0x0146, 0x0114).

You SHOULD NOT use AES-GCM with only key derivation algorithm suites (0x0178, 0x0146, 0x0114) if the users who encrypt and the users who decrypt are not equally trusted.

You SHOULD NOT use AES-GCM without key Derivation or signing (0x0078, 0x0046, 0x0014), except for backwards compatability.