nist_kw.h 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  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. #ifndef MBEDTLS_NIST_KW_H
  37. #define MBEDTLS_NIST_KW_H
  38. #if !defined(MBEDTLS_CONFIG_FILE)
  39. #include "config.h"
  40. #else
  41. #include MBEDTLS_CONFIG_FILE
  42. #endif
  43. #include "cipher.h"
  44. #ifdef __cplusplus
  45. extern "C" {
  46. #endif
  47. typedef enum
  48. {
  49. MBEDTLS_KW_MODE_KW = 0,
  50. MBEDTLS_KW_MODE_KWP = 1
  51. } mbedtls_nist_kw_mode_t;
  52. #if !defined(MBEDTLS_NIST_KW_ALT)
  53. // Regular implementation
  54. //
  55. /**
  56. * \brief The key wrapping context-type definition. The key wrapping context is passed
  57. * to the APIs called.
  58. *
  59. * \note The definition of this type may change in future library versions.
  60. * Don't make any assumptions on this context!
  61. */
  62. typedef struct {
  63. mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
  64. } mbedtls_nist_kw_context;
  65. #else /* MBEDTLS_NIST_key wrapping_ALT */
  66. #include "nist_kw_alt.h"
  67. #endif /* MBEDTLS_NIST_KW_ALT */
  68. /**
  69. * \brief This function initializes the specified key wrapping context
  70. * to make references valid and prepare the context
  71. * for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
  72. *
  73. * \param ctx The key wrapping context to initialize.
  74. *
  75. */
  76. void mbedtls_nist_kw_init( mbedtls_nist_kw_context *ctx );
  77. /**
  78. * \brief This function initializes the key wrapping context set in the
  79. * \p ctx parameter and sets the encryption key.
  80. *
  81. * \param ctx The key wrapping context.
  82. * \param cipher The 128-bit block cipher to use. Only AES is supported.
  83. * \param key The Key Encryption Key (KEK).
  84. * \param keybits The KEK size in bits. This must be acceptable by the cipher.
  85. * \param is_wrap Specify whether the operation within the context is wrapping or unwrapping
  86. *
  87. * \return \c 0 on success.
  88. * \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for any invalid input.
  89. * \return \c MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE for 128-bit block ciphers
  90. * which are not supported.
  91. * \return cipher-specific error code on failure of the underlying cipher.
  92. */
  93. int mbedtls_nist_kw_setkey( mbedtls_nist_kw_context *ctx,
  94. mbedtls_cipher_id_t cipher,
  95. const unsigned char *key,
  96. unsigned int keybits,
  97. const int is_wrap );
  98. /**
  99. * \brief This function releases and clears the specified key wrapping context
  100. * and underlying cipher sub-context.
  101. *
  102. * \param ctx The key wrapping context to clear.
  103. */
  104. void mbedtls_nist_kw_free( mbedtls_nist_kw_context *ctx );
  105. /**
  106. * \brief This function encrypts a buffer using key wrapping.
  107. *
  108. * \param ctx The key wrapping context to use for encryption.
  109. * \param mode The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
  110. * \param input The buffer holding the input data.
  111. * \param in_len The length of the input data in Bytes.
  112. * The input uses units of 8 Bytes called semiblocks.
  113. * <ul><li>For KW mode: a multiple of 8 bytes between 16 and 2^57-8 inclusive. </li>
  114. * <li>For KWP mode: any length between 1 and 2^32-1 inclusive.</li></ul>
  115. * \param[out] output The buffer holding the output data.
  116. * <ul><li>For KW mode: Must be at least 8 bytes larger than \p in_len.</li>
  117. * <li>For KWP mode: Must be at least 8 bytes larger rounded up to a multiple of
  118. * 8 bytes for KWP (15 bytes at most).</li></ul>
  119. * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
  120. * \param[in] out_size The capacity of the output buffer.
  121. *
  122. * \return \c 0 on success.
  123. * \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
  124. * \return cipher-specific error code on failure of the underlying cipher.
  125. */
  126. int mbedtls_nist_kw_wrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
  127. const unsigned char *input, size_t in_len,
  128. unsigned char *output, size_t* out_len, size_t out_size );
  129. /**
  130. * \brief This function decrypts a buffer using key wrapping.
  131. *
  132. * \param ctx The key wrapping context to use for decryption.
  133. * \param mode The key wrapping mode to use (MBEDTLS_KW_MODE_KW or MBEDTLS_KW_MODE_KWP)
  134. * \param input The buffer holding the input data.
  135. * \param in_len The length of the input data in Bytes.
  136. * The input uses units of 8 Bytes called semiblocks.
  137. * The input must be a multiple of semiblocks.
  138. * <ul><li>For KW mode: a multiple of 8 bytes between 24 and 2^57 inclusive. </li>
  139. * <li>For KWP mode: a multiple of 8 bytes between 16 and 2^32 inclusive.</li></ul>
  140. * \param[out] output The buffer holding the output data.
  141. * The output buffer's minimal length is 8 bytes shorter than \p in_len.
  142. * \param[out] out_len The number of bytes written to the output buffer. \c 0 on failure.
  143. * For KWP mode, the length could be up to 15 bytes shorter than \p in_len,
  144. * depending on how much padding was added to the data.
  145. * \param[in] out_size The capacity of the output buffer.
  146. *
  147. * \return \c 0 on success.
  148. * \return \c MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA for invalid input length.
  149. * \return \c MBEDTLS_ERR_CIPHER_AUTH_FAILED for verification failure of the ciphertext.
  150. * \return cipher-specific error code on failure of the underlying cipher.
  151. */
  152. int mbedtls_nist_kw_unwrap( mbedtls_nist_kw_context *ctx, mbedtls_nist_kw_mode_t mode,
  153. const unsigned char *input, size_t in_len,
  154. unsigned char *output, size_t* out_len, size_t out_size);
  155. #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
  156. /**
  157. * \brief The key wrapping checkup routine.
  158. *
  159. * \return \c 0 on success.
  160. * \return \c 1 on failure.
  161. */
  162. int mbedtls_nist_kw_self_test( int verbose );
  163. #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
  164. #ifdef __cplusplus
  165. }
  166. #endif
  167. #endif /* MBEDTLS_NIST_KW_H */