include/mbedtls/nist_kw.h

0001 /**
0002  * \file nist_kw.h
0003  *
0004  * \brief This file provides an API for key wrapping (KW) and key wrapping with
0005  *        padding (KWP) as defined in NIST SP 800-38F.
0006  *        https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
0007  *
0008  *        Key wrapping specifies a deterministic authenticated-encryption mode
0009  *        of operation, according to <em>NIST SP 800-38F: Recommendation for
0010  *        Block Cipher Modes of Operation: Methods for Key Wrapping</em>. Its
0011  *        purpose is to protect cryptographic keys.
0012  *
0013  *        Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP.
0014  *        https://tools.ietf.org/html/rfc3394
0015  *        https://tools.ietf.org/html/rfc5649
0016  *
0017  */
0018 /*
0019  *  Copyright The Mbed TLS Contributors
0020  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0021  */
0022
0023 #ifndef MBEDTLS_NIST_KW_H
0024 #define MBEDTLS_NIST_KW_H
0025 #include "mbedtls/private_access.h"
0026
0027 #include "mbedtls/build_info.h"
0028
0029 #include "mbedtls/cipher.h"
0030
0031 #ifdef __cplusplus
0032 extern "C" {
0033 #endif
0034
0035 typedef enum {
0036     MBEDTLS_KW_MODE_KW = 0,
0037     MBEDTLS_KW_MODE_KWP = 1
0038 } mbedtls_nist_kw_mode_t;
0039
0040 #if !defined(MBEDTLS_NIST_KW_ALT)
0041 // Regular implementation
0042 //
0043
0044 /**
0045  * \brief    The key wrapping context-type definition. The key wrapping context is passed
0046  *           to the APIs called.
0047  *
0048  * \note     The definition of this type may change in future library versions.
0049  *           Don't make any assumptions on this context!
0050  */
0051 typedef struct {
0052     mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx);    /*!< The cipher context used. */
0053 } mbedtls_nist_kw_context;
0054
0055 #else  /* MBEDTLS_NIST_key wrapping_ALT */
0056 #include "nist_kw_alt.h"
0057 #endif /* MBEDTLS_NIST_KW_ALT */
0058
0059 /**
0060  * \brief           This function initializes the specified key wrapping context
0061  *                  to make references valid and prepare the context
0062  *                  for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
0063  *
0064  * \param ctx       The key wrapping context to initialize.
0065  *
0066  */
0067 void mbedtls_nist_kw_init(mbedtls_nist_kw_context *ctx);
0068
0069 /**
0070  * \brief           This function initializes the key wrapping context set in the
0071  *                  \p ctx parameter and sets the encryption key.
0072  *
0073  * \param ctx       The key wrapping context.
0074  * \param cipher    The 128-bit block cipher to use. Only AES is supported.
0075  * \param key       The Key Encryption Key (KEK).
0076  * \param keybits   The KEK size in bits. This must be acceptable by the cipher.
0077  * \param is_wrap   Specify whether the operation within the context is wrapping or unwrapping
0078  *
0079  * \return          \c 0 on success.
0080  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
0081  * \return          \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
0082  *                  which are not supported.
0083  * \return          cipher-specific error code on failure of the underlying cipher.
0084  */
0085 int mbedtls_nist_kw_setkey(mbedtls_nist_kw_context *ctx,
0086                            mbedtls_cipher_id_t cipher,
0087                            const unsigned char *key,
0088                            unsigned int keybits,
0089                            const int is_wrap);
0090
0091 /**
0092  * \brief   This function releases and clears the specified key wrapping context
0093  *          and underlying cipher sub-context.
0094  *
0095  * \param ctx       The key wrapping context to clear.
0096  */
0097 void mbedtls_nist_kw_free(mbedtls_nist_kw_context *ctx);
0098
0099 /**
0100  * \brief           This function encrypts a buffer using key wrapping.
0101  *
0102  * \param ctx       The key wrapping context to use for encryption.
0103  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
0104  * \param input     The buffer holding the input data.
0105  * \param in_len    The length of the input data in Bytes.
0106  *                  The input uses units of 8 Bytes called semiblocks.
0107  *                  <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
0108  *                  <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
0109  * \param[out] output    The buffer holding the output data.
0110  *                  <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
0111  *                  <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
0112  *                  8 bytes for KWP (15 bytes at most).</li></ul>
0113  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
0114  * \param[in] out_size The capacity of the output buffer.
0115  *
0116  * \return          \c 0 on success.
0117  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
0118  * \return          cipher-specific error code on failure of the underlying cipher.
0119  */
0120 int mbedtls_nist_kw_wrap(mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
0121                          const unsigned char *input, size_t in_len,
0122                          unsigned char *output, size_t *out_len, size_t out_size);
0123
0124 /**
0125  * \brief           This function decrypts a buffer using key wrapping.
0126  *
0127  * \param ctx       The key wrapping context to use for decryption.
0128  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
0129  * \param input     The buffer holding the input data.
0130  * \param in_len    The length of the input data in Bytes.
0131  *                  The input uses units of 8 Bytes called semiblocks.
0132  *                  The input must be a multiple of semiblocks.
0133  *                  <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
0134  *                  <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
0135  * \param[out] output    The buffer holding the output data.
0136  *                  The output buffer's minimal length is 8 bytes shorter than \p in_len.
0137  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
0138  *                  For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
0139  *                  depending on how much padding was added to the data.
0140  * \param[in] out_size The capacity of the output buffer.
0141  *
0142  * \return          \c 0 on success.
0143  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
0144  * \return          \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
0145  * \return          cipher-specific error code on failure of the underlying cipher.
0146  */
0147 int mbedtls_nist_kw_unwrap(mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
0148                            const unsigned char *input, size_t in_len,
0149                            unsigned char *output, size_t *out_len, size_t out_size);
0150
0151
0152 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
0153 /**
0154  * \brief          The key wrapping checkup routine.
0155  *
0156  * \return         \c 0 on success.
0157  * \return         \c 1 on failure.
0158  */
0159 int mbedtls_nist_kw_self_test(int verbose);
0160 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
0161
0162 #ifdef __cplusplus
0163 }
0164 #endif
0165
0166 #endif /* MBEDTLS_NIST_KW_H */