OPTIGA Trust M  1.1.0
C++ library for Optiga Trust M Chip Security Controller
nist_kw.h File Reference

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. More...

#include "cipher.h"
Include dependency graph for nist_kw.h:

Go to the source code of this file.

Classes

struct  mbedtls_nist_kw_context
 The key wrapping context-type definition. The key wrapping context is passed to the APIs called. More...
 

Enumerations

enum  mbedtls_nist_kw_mode_t { MBEDTLS_KW_MODE_KW = 0, MBEDTLS_KW_MODE_KWP = 1 }
 

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(). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

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

Enumeration Type Documentation

◆ mbedtls_nist_kw_mode_t

Enumerator
MBEDTLS_KW_MODE_KW 
MBEDTLS_KW_MODE_KWP 

Function Documentation

◆ mbedtls_nist_kw_free()

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
ctxThe key wrapping context to clear.

◆ mbedtls_nist_kw_init()

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
ctxThe key wrapping context to initialize.

◆ mbedtls_nist_kw_setkey()

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
ctxThe key wrapping context.
cipherThe 128-bit block cipher to use. Only AES is supported.
keyThe Key Encryption Key (KEK).
keybitsThe KEK size in bits. This must be acceptable by the cipher.
is_wrapSpecify whether the operation within the context is wrapping or unwrapping
Returns
0 on success.
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers which are not supported.
cipher-specific error code on failure of the underlying cipher.

◆ mbedtls_nist_kw_unwrap()

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
ctxThe key wrapping context to use for decryption.
modeThe key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
inputThe buffer holding the input data.
in_lenThe 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.
[out]outputThe buffer holding the output data. The output buffer's minimal length is 8 bytes shorter than in_len.
[out]out_lenThe 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.
[in]out_sizeThe capacity of the output buffer.
Returns
0 on success.
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
cipher-specific error code on failure of the underlying cipher.

◆ mbedtls_nist_kw_wrap()

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
ctxThe key wrapping context to use for encryption.
modeThe key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
inputThe buffer holding the input data.
in_lenThe 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.
[out]outputThe 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]out_lenThe number of bytes written to the output buffer. 0 on failure.
[in]out_sizeThe capacity of the output buffer.
Returns
0 on success.
MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
cipher-specific error code on failure of the underlying cipher.