File nist_kw.h

This file provides an API for key wrapping (KW) and key wrapping with padding (KWP) as defined in NIST SP 800-38F. https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf.

Key wrapping specifies a deterministic authenticated-encryption mode of operation, according to NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping. Its purpose is to protect cryptographic keys.

Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP. https://tools.ietf.org/html/rfc3394 https://tools.ietf.org/html/rfc5649

Enums

enum mbedtls_nist_kw_mode_t

Values:

enumerator MBEDTLS_KW_MODE_KW
enumerator MBEDTLS_KW_MODE_KWP

Functions

void mbedtls_nist_kw_init(mbedtls_nist_kw_context *ctx)

This function initializes the specified key wrapping context to make references valid and prepare the context for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().

Parameters

ctx – The key wrapping context to initialize.

int mbedtls_nist_kw_setkey(mbedtls_nist_kw_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits, const int is_wrap)

This function initializes the key wrapping context set in the ctx parameter and sets the encryption key.

Parameters

  • ctx – The key wrapping context.

  • cipher – The 128-bit block cipher to use. Only AES is supported.

  • key – The Key Encryption Key (KEK).

  • keybits – The KEK size in bits. This must be acceptable by the cipher.

  • is_wrap – Specify whether the operation within the context is wrapping or unwrapping

Returns

0 on success.

Returns

MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.

Returns

MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers which are not supported.

Returns

cipher-specific error code on failure of the underlying cipher.

void mbedtls_nist_kw_free(mbedtls_nist_kw_context *ctx)

This function releases and clears the specified key wrapping context and underlying cipher sub-context.

Parameters

ctx – The key wrapping context to clear.

int mbedtls_nist_kw_wrap(mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode, const unsigned char *input, size_t in_len, unsigned char *output, size_t *out_len, size_t out_size)

This function encrypts a buffer using key wrapping.

Parameters

  • ctx – The key wrapping context to use for encryption.

  • mode – The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)

  • input – The buffer holding the input data.

  • in_len – The length of the input data in Bytes. The input uses units of 8 Bytes called semiblocks.

    • For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive.

    • For KWP mode: any length between 1 and 2^32-1 inclusive.

  • output – [out] The buffer holding the output data.

    • For KW mode: Must be at least 8 bytes larger than in_len.

    • For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of 8 bytes for KWP (15 bytes at most).

  • out_len – [out] The number of bytes written to the output buffer. 0 on failure.

  • out_size – [in] The capacity of the output buffer.

Returns

0 on success.

Returns

MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.

Returns

cipher-specific error code on failure of the underlying cipher.

int mbedtls_nist_kw_unwrap(mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode, const unsigned char *input, size_t in_len, unsigned char *output, size_t *out_len, size_t out_size)

This function decrypts a buffer using key wrapping.

Parameters

  • ctx – The key wrapping context to use for decryption.

  • mode – The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)

  • input – The buffer holding the input data.

  • in_len – The length of the input data in Bytes. The input uses units of 8 Bytes called semiblocks. The input must be a multiple of semiblocks.

    • For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive.

    • For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.

  • output – [out] The buffer holding the output data. The output buffer’s minimal length is 8 bytes shorter than in_len.

  • out_len – [out] The number of bytes written to the output buffer. 0 on failure. For KWP mode, the length could be up to 15 bytes shorter than in_len, depending on how much padding was added to the data.

  • out_size – [in] The capacity of the output buffer.

Returns

0 on success.

Returns

MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.

Returns

MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.

Returns

cipher-specific error code on failure of the underlying cipher.

int mbedtls_nist_kw_self_test(int verbose)

The key wrapping checkup routine.

Returns

0 on success.

Returns

1 on failure.