nist_kw.h

00001 /**
00002  * \file nist_kw.h
00003  *
00004  * \brief This file provides an API for key wrapping (KW) and key wrapping with
00005  *        padding (KWP) as defined in NIST SP 800-38F.
00006  *        https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
00007  *
00008  *        Key wrapping specifies a deterministic authenticated-encryption mode
00009  *        of operation, according to <em>NIST SP 800-38F: Recommendation for
00010  *        Block Cipher Modes of Operation: Methods for Key Wrapping</em>. Its
00011  *        purpose is to protect cryptographic keys.
00012  *
00013  *        Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP.
00014  *        https://tools.ietf.org/html/rfc3394
00015  *        https://tools.ietf.org/html/rfc5649
00016  *
00017  */
00018 /*
00019  *  Copyright (C) 2018, Arm Limited (or its affiliates), All Rights Reserved
00020  *  SPDX-License-Identifier: Apache-2.0
00021  *
00022  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00023  *  not use this file except in compliance with the License.
00024  *  You may obtain a copy of the License at
00025  *
00026  *  http://www.apache.org/licenses/LICENSE-2.0
00027  *
00028  *  Unless required by applicable law or agreed to in writing, software
00029  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00030  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00031  *  See the License for the specific language governing permissions and
00032  *  limitations under the License.
00033  *
00034  *  This file is part of Mbed TLS (https://tls.mbed.org)
00035  */
00036 
00037 #ifndef MBEDTLS_NIST_KW_H
00038 #define MBEDTLS_NIST_KW_H
00039 
00040 #if !defined(MBEDTLS_CONFIG_FILE)
00041 #include "mbedtls/config.h"
00042 #else
00043 #include MBEDTLS_CONFIG_FILE
00044 #endif
00045 
00046 #include "mbedtls/cipher.h"
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 typedef enum
00053 {
00054     MBEDTLS_KW_MODE_KW = 0,
00055     MBEDTLS_KW_MODE_KWP = 1
00056 } mbedtls_nist_kw_mode_t;
00057 
00058 #if !defined(MBEDTLS_NIST_KW_ALT)
00059 // Regular implementation
00060 //
00061 
00062 /**
00063  * \brief    The key wrapping context-type definition. The key wrapping context is passed
00064  *           to the APIs called.
00065  *
00066  * \note     The definition of this type may change in future library versions.
00067  *           Don't make any assumptions on this context!
00068  */
00069 typedef struct {
00070     mbedtls_cipher_context_t cipher_ctx ;    /*!< The cipher context used. */
00071 } mbedtls_nist_kw_context;
00072 
00073 #else  /* MBEDTLS_NIST_key wrapping_ALT */
00074 #include "nist_kw_alt.h"
00075 #endif /* MBEDTLS_NIST_KW_ALT */
00076 
00077 /**
00078  * \brief           This function initializes the specified key wrapping context
00079  *                  to make references valid and prepare the context
00080  *                  for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
00081  *
00082  * \param ctx       The key wrapping context to initialize.
00083  *
00084  */
00085 void mbedtls_nist_kw_init( mbedtls_nist_kw_context *ctx );
00086 
00087 /**
00088  * \brief           This function initializes the key wrapping context set in the
00089  *                  \p ctx parameter and sets the encryption key.
00090  *
00091  * \param ctx       The key wrapping context.
00092  * \param cipher    The 128-bit block cipher to use. Only AES is supported.
00093  * \param key       The Key Encryption Key (KEK).
00094  * \param keybits   The KEK size in bits. This must be acceptable by the cipher.
00095  * \param is_wrap   Specify whether the operation within the context is wrapping or unwrapping
00096  *
00097  * \return          \c 0 on success.
00098  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
00099  * \return          \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
00100  *                  which are not supported.
00101  * \return          cipher-specific error code on failure of the underlying cipher.
00102  */
00103 int mbedtls_nist_kw_setkey( mbedtls_nist_kw_context *ctx,
00104                             mbedtls_cipher_id_t cipher,
00105                             const unsigned char *key,
00106                             unsigned int keybits,
00107                             const int is_wrap );
00108 
00109 /**
00110  * \brief   This function releases and clears the specified key wrapping context
00111  *          and underlying cipher sub-context.
00112  *
00113  * \param ctx       The key wrapping context to clear.
00114  */
00115 void mbedtls_nist_kw_free( mbedtls_nist_kw_context *ctx );
00116 
00117 /**
00118  * \brief           This function encrypts a buffer using key wrapping.
00119  *
00120  * \param ctx       The key wrapping context to use for encryption.
00121  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
00122  * \param input     The buffer holding the input data.
00123  * \param in_len    The length of the input data in Bytes.
00124  *                  The input uses units of 8 Bytes called semiblocks.
00125  *                  <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
00126  *                  <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
00127  * \param[out] output    The buffer holding the output data.
00128  *                  <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
00129  *                  <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
00130  *                  8 bytes for KWP (15 bytes at most).</li></ul>
00131  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
00132  * \param[in] out_size The capacity of the output buffer.
00133  *
00134  * \return          \c 0 on success.
00135  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
00136  * \return          cipher-specific error code on failure of the underlying cipher.
00137  */
00138 int mbedtls_nist_kw_wrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
00139                           const unsigned char *input, size_t in_len,
00140                           unsigned char *output, size_t* out_len, size_t out_size );
00141 
00142 /**
00143  * \brief           This function decrypts a buffer using key wrapping.
00144  *
00145  * \param ctx       The key wrapping context to use for decryption.
00146  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
00147  * \param input     The buffer holding the input data.
00148  * \param in_len    The length of the input data in Bytes.
00149  *                  The input uses units of 8 Bytes called semiblocks.
00150  *                  The input must be a multiple of semiblocks.
00151  *                  <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
00152  *                  <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
00153  * \param[out] output    The buffer holding the output data.
00154  *                  The output buffer's minimal length is 8 bytes shorter than \p in_len.
00155  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
00156  *                  For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
00157  *                  depending on how much padding was added to the data.
00158  * \param[in] out_size The capacity of the output buffer.
00159  *
00160  * \return          \c 0 on success.
00161  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
00162  * \return          \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
00163  * \return          cipher-specific error code on failure of the underlying cipher.
00164  */
00165 int mbedtls_nist_kw_unwrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
00166                             const unsigned char *input, size_t in_len,
00167                             unsigned char *output, size_t* out_len, size_t out_size);
00168 
00169 
00170 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
00171 /**
00172  * \brief          The key wrapping checkup routine.
00173  *
00174  * \return         \c 0 on success.
00175  * \return         \c 1 on failure.
00176  */
00177 int mbedtls_nist_kw_self_test( int verbose );
00178 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
00179 
00180 #ifdef __cplusplus
00181 }
00182 #endif
00183 
00184 #endif /* MBEDTLS_NIST_KW_H */