mbed TLS v2.16.0: nist_kw.h File Reference

mbed TLS v2.16.0

Data Structures | Enumerations | Functions
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.

## Data Structures
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...
int | mbedtls_nist_kw_self_test (int verbose)
| The key wrapping checkup routine. 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

Definition in file nist_kw.h.

## Enumeration Type Documentation

## ◆ mbedtls_nist_kw_mode_t

enum mbedtls_nist_kw_mode_t

Enumerator
MBEDTLS_KW_MODE_KW |
MBEDTLS_KW_MODE_KWP |

Definition at line 46 of file nist_kw.h.

## 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

  ctx | The 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

  ctx | The key wrapping context to initialize.

## ◆ mbedtls_nist_kw_self_test()

int mbedtls_nist_kw_self_test | ( | int | verbose | ) |

The key wrapping checkup routine.

Returns
  `0` on success.
  `1` on failure.

## ◆ 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

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

  | 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.
  [out] | output | The buffer holding the output data. The output buffer's minimal length is 8 bytes shorter than `in_len`.
  [out] | out_len | 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.
  [in] | out_size | The 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

  | 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.
  [out] | output | 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] | out_len | The number of bytes written to the output buffer. `0` on failure.
  [in] | out_size | The 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.