Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

nist_kw.h File Reference
Data Structures | 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. More...

Go to the source code of this file.

Data Structures

struct  mbedtls_nist_kw_context
 The key wrapping context-type definition. More...

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

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.

Function Documentation

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.

Definition at line 162 of file nist_kw.c.

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.

Definition at line 108 of file nist_kw.c.

int mbedtls_nist_kw_self_test ( int  verbose )

The key wrapping checkup routine.

Returns:
0 on success.
1 on failure.

Definition at line 627 of file nist_kw.c.

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.

Definition at line 113 of file nist_kw.c.

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.

Definition at line 387 of file nist_kw.c.

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.

Definition at line 185 of file nist_kw.c.

Generated on Tue Jul 12 2022 13:55:17 by  doxygen 1.7.2