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 #include "cipher.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 typedef enum
00047 {
00048     MBEDTLS_KW_MODE_KW = 0,
00049     MBEDTLS_KW_MODE_KWP = 1
00050 } mbedtls_nist_kw_mode_t;
00051 
00052 #if !defined(MBEDTLS_NIST_KW_ALT)
00053 // Regular implementation
00054 //
00055 
00056 /**
00057  * \brief    The key wrapping context-type definition. The key wrapping context is passed
00058  *           to the APIs called.
00059  *
00060  * \note     The definition of this type may change in future library versions.
00061  *           Don't make any assumptions on this context!
00062  */
00063 typedef struct {
00064     mbedtls_cipher_context_t cipher_ctx ;    /*!< The cipher context used. */
00065 } mbedtls_nist_kw_context;
00066 
00067 #else  /* MBEDTLS_NIST_key wrapping_ALT */
00068 #include "nist_kw_alt.h"
00069 #endif /* MBEDTLS_NIST_KW_ALT */
00070 
00071 /**
00072  * \brief           This function initializes the specified key wrapping context
00073  *                  to make references valid and prepare the context
00074  *                  for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
00075  *
00076  * \param ctx       The key wrapping context to initialize.
00077  *
00078  */
00079 void mbedtls_nist_kw_init( mbedtls_nist_kw_context *ctx );
00080 
00081 /**
00082  * \brief           This function initializes the key wrapping context set in the
00083  *                  \p ctx parameter and sets the encryption key.
00084  *
00085  * \param ctx       The key wrapping context.
00086  * \param cipher    The 128-bit block cipher to use. Only AES is supported.
00087  * \param key       The Key Encryption Key (KEK).
00088  * \param keybits   The KEK size in bits. This must be acceptable by the cipher.
00089  * \param is_wrap   Specify whether the operation within the context is wrapping or unwrapping
00090  *
00091  * \return          \c 0 on success.
00092  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
00093  * \return          \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
00094  *                  which are not supported.
00095  * \return          cipher-specific error code on failure of the underlying cipher.
00096  */
00097 int mbedtls_nist_kw_setkey( mbedtls_nist_kw_context *ctx,
00098                             mbedtls_cipher_id_t cipher,
00099                             const unsigned char *key,
00100                             unsigned int keybits,
00101                             const int is_wrap );
00102 
00103 /**
00104  * \brief   This function releases and clears the specified key wrapping context
00105  *          and underlying cipher sub-context.
00106  *
00107  * \param ctx       The key wrapping context to clear.
00108  */
00109 void mbedtls_nist_kw_free( mbedtls_nist_kw_context *ctx );
00110 
00111 /**
00112  * \brief           This function encrypts a buffer using key wrapping.
00113  *
00114  * \param ctx       The key wrapping context to use for encryption.
00115  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
00116  * \param input     The buffer holding the input data.
00117  * \param in_len    The length of the input data in Bytes.
00118  *                  The input uses units of 8 Bytes called semiblocks.
00119  *                  <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
00120  *                  <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
00121  * \param[out] output    The buffer holding the output data.
00122  *                  <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
00123  *                  <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
00124  *                  8 bytes for KWP (15 bytes at most).</li></ul>
00125  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
00126  * \param[in] out_size The capacity of the output buffer.
00127  *
00128  * \return          \c 0 on success.
00129  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
00130  * \return          cipher-specific error code on failure of the underlying cipher.
00131  */
00132 int mbedtls_nist_kw_wrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
00133                           const unsigned char *input, size_t in_len,
00134                           unsigned char *output, size_t* out_len, size_t out_size );
00135 
00136 /**
00137  * \brief           This function decrypts a buffer using key wrapping.
00138  *
00139  * \param ctx       The key wrapping context to use for decryption.
00140  * \param mode      The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
00141  * \param input     The buffer holding the input data.
00142  * \param in_len    The length of the input data in Bytes.
00143  *                  The input uses units of 8 Bytes called semiblocks.
00144  *                  The input must be a multiple of semiblocks.
00145  *                  <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
00146  *                  <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
00147  * \param[out] output    The buffer holding the output data.
00148  *                  The output buffer's minimal length is 8 bytes shorter than \p in_len.
00149  * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
00150  *                  For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
00151  *                  depending on how much padding was added to the data.
00152  * \param[in] out_size The capacity of the output buffer.
00153  *
00154  * \return          \c 0 on success.
00155  * \return          \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
00156  * \return          \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
00157  * \return          cipher-specific error code on failure of the underlying cipher.
00158  */
00159 int mbedtls_nist_kw_unwrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
00160                             const unsigned char *input, size_t in_len,
00161                             unsigned char *output, size_t* out_len, size_t out_size);
00162 
00163 
00164 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
00165 /**
00166  * \brief          The key wrapping checkup routine.
00167  *
00168  * \return         \c 0 on success.
00169  * \return         \c 1 on failure.
00170  */
00171 int mbedtls_nist_kw_self_test( int verbose );
00172 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
00173 
00174 #ifdef __cplusplus
00175 }
00176 #endif
00177 
00178 #endif /* MBEDTLS_NIST_KW_H */