third_party/mbedtls/repo/include/mbedtls/nist_kw.h

   1 /**
   2  * \file nist_kw.h
   3  *
   4  * \brief This file provides an API for key wrapping (KW) and key wrapping with
   5  *        padding (KWP) as defined in NIST SP 800-38F.
   6  *        https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
   7  *
   8  *        Key wrapping specifies a deterministic authenticated-encryption mode
   9  *        of operation, according to <em>NIST SP 800-38F: Recommendation for
  10  *        Block Cipher Modes of Operation: Methods for Key Wrapping</em>. Its
  11  *        purpose is to protect cryptographic keys.
  12  *
  13  *        Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP.
  14  *        https://tools.ietf.org/html/rfc3394
  15  *        https://tools.ietf.org/html/rfc5649
  16  *
  17  */
  18 /*
  19  *  Copyright (C) 2018, Arm Limited (or its affiliates), All Rights Reserved
  20  *  SPDX-License-Identifier: Apache-2.0
  21  *
  22  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  23  *  not use this file except in compliance with the License.
  24  *  You may obtain a copy of the License at
  25  *
  26  *  http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *  Unless required by applicable law or agreed to in writing, software
  29  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  30  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *  See the License for the specific language governing permissions and
  32  *  limitations under the License.
  33  *
  34  *  This file is part of Mbed TLS (https://tls.mbed.org)
  35  */
  36
  37 #ifndef MBEDTLS_NIST_KW_H
  38 #define MBEDTLS_NIST_KW_H
  39
  40 #if !defined(MBEDTLS_CONFIG_FILE)
  41 #include "config.h"
  42 #else
  43 #include MBEDTLS_CONFIG_FILE
  44 #endif
  45
  46 #include "cipher.h"
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 typedef enum
  53 {
  54     MBEDTLS_KW_MODE_KW = 0,
  55     MBEDTLS_KW_MODE_KWP = 1
  56 } mbedtls_nist_kw_mode_t;
  57
  58 #if !defined(MBEDTLS_NIST_KW_ALT)
  59 // Regular implementation
  60 //
  61
  62 /**
  63  * \brief    The key wrapping context-type definition. The key wrapping context is passed
  64  *           to the APIs called.
  65  *
  66  * \note     The definition of this type may change in future library versions.
  67  *           Don't make any assumptions on this context!
  68  */
  69 typedef struct {
  70     mbedtls_cipher_context_t cipher_ctx;    /*!< The cipher context used. */
  71 } mbedtls_nist_kw_context;
  72
  73 #else  /* MBEDTLS_NIST_key wrapping_ALT */
  74 #include "nist_kw_alt.h"
  75 #endif /* MBEDTLS_NIST_KW_ALT */
  76
  77 /**
  78  * \brief           This function initializes the specified key wrapping context
  79  *                  to make references valid and prepare the context
  80  *                  for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
  81  *
  82  * \param ctx       The key wrapping context to initialize.
  83  *
  84  */
  85 void mbedtls_nist_kw_init( mbedtls_nist_kw_context *ctx );
  86
  87 /**
  88  * \brief           This function initializes the key wrapping context set in the
  89  *                  \p ctx parameter and sets the encryption key.
  90  *
  91  * \param ctx       The key wrapping context.
  92  * \param cipher    The 128-bit block cipher to use. Only AES is supported.
  93  * \param key       The Key Encryption Key (KEK).
  94  * \param keybits   The KEK size in bits. This must be acceptable by the cipher.
  95  * \param is_wrap   Specify whether the operation within the context is wrapping or unwrapping
  96  *
  97  * \return          \c 0 on success.
  98  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
  99  * \return          \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
 100  *                  which are not supported.
 101  * \return          cipher-specific error code on failure of the underlying cipher.
 102  */
 103 int mbedtls_nist_kw_setkey( mbedtls_nist_kw_context *ctx,
 104                             mbedtls_cipher_id_t cipher,
 105                             const unsigned char *key,
 106                             unsigned int keybits,
 107                             const int is_wrap );
 108
 109 /**
 110  * \brief   This function releases and clears the specified key wrapping context
 111  *          and underlying cipher sub-context.
 112  *
 113  * \param ctx       The key wrapping context to clear.
 114  */
 115 void mbedtls_nist_kw_free( mbedtls_nist_kw_context *ctx );
 116
 117 /**
 118  * \brief           This function encrypts a buffer using key wrapping.
 119  *
 120  * \param ctx       The key wrapping context to use for encryption.
 121  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
 122  * \param input     The buffer holding the input data.
 123  * \param in_len    The length of the input data in Bytes.
 124  *                  The input uses units of 8 Bytes called semiblocks.
 125  *                  <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
 126  *                  <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
 127  * \param[out] output    The buffer holding the output data.
 128  *                  <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
 129  *                  <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
 130  *                  8 bytes for KWP (15 bytes at most).</li></ul>
 131  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
 132  * \param[in] out_size The capacity of the output buffer.
 133  *
 134  * \return          \c 0 on success.
 135  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
 136  * \return          cipher-specific error code on failure of the underlying cipher.
 137  */
 138 int mbedtls_nist_kw_wrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
 139                           const unsigned char *input, size_t in_len,
 140                           unsigned char *output, size_t* out_len, size_t out_size );
 141
 142 /**
 143  * \brief           This function decrypts a buffer using key wrapping.
 144  *
 145  * \param ctx       The key wrapping context to use for decryption.
 146  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
 147  * \param input     The buffer holding the input data.
 148  * \param in_len    The length of the input data in Bytes.
 149  *                  The input uses units of 8 Bytes called semiblocks.
 150  *                  The input must be a multiple of semiblocks.
 151  *                  <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
 152  *                  <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
 153  * \param[out] output    The buffer holding the output data.
 154  *                  The output buffer's minimal length is 8 bytes shorter than \p in_len.
 155  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
 156  *                  For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
 157  *                  depending on how much padding was added to the data.
 158  * \param[in] out_size The capacity of the output buffer.
 159  *
 160  * \return          \c 0 on success.
 161  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
 162  * \return          \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
 163  * \return          cipher-specific error code on failure of the underlying cipher.
 164  */
 165 int mbedtls_nist_kw_unwrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
 166                             const unsigned char *input, size_t in_len,
 167                             unsigned char *output, size_t* out_len, size_t out_size);
 168
 169
 170 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
 171 /**
 172  * \brief          The key wrapping checkup routine.
 173  *
 174  * \return         \c 0 on success.
 175  * \return         \c 1 on failure.
 176  */
 177 int mbedtls_nist_kw_self_test( int verbose );
 178 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 #endif /* MBEDTLS_NIST_KW_H */