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 "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/cipher.h"
#include "nist_kw_alt.h"
Go to the source code of this file.
|
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...
|
|
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.
Enumerator |
---|
MBEDTLS_KW_MODE_KW |
|
MBEDTLS_KW_MODE_KWP |
|
Definition at line 47 of file nist_kw.h.
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. |
void mbedtls_nist_kw_init |
( |
mbedtls_nist_kw_context * |
ctx | ) |
|
int mbedtls_nist_kw_self_test |
( |
int |
verbose | ) |
|
The key wrapping checkup routine.
- Returns
0
on success.
-
1
on failure.
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.
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.
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.