chacha20.h 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226
  1. /**
  2. * \file chacha20.h
  3. *
  4. * \brief This file contains ChaCha20 definitions and functions.
  5. *
  6. * ChaCha20 is a stream cipher that can encrypt and decrypt
  7. * information. ChaCha was created by Daniel Bernstein as a variant of
  8. * its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
  9. * ChaCha20 is the variant with 20 rounds, that was also standardized
  10. * in RFC 7539.
  11. *
  12. * \author Daniel King <damaki.gh@gmail.com>
  13. */
  14. /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
  15. * SPDX-License-Identifier: Apache-2.0
  16. *
  17. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  18. * not use this file except in compliance with the License.
  19. * You may obtain a copy of the License at
  20. *
  21. * http://www.apache.org/licenses/LICENSE-2.0
  22. *
  23. * Unless required by applicable law or agreed to in writing, software
  24. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  25. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  26. * See the License for the specific language governing permissions and
  27. * limitations under the License.
  28. *
  29. * This file is part of Mbed TLS (https://tls.mbed.org)
  30. */
  31. #ifndef MBEDTLS_CHACHA20_H
  32. #define MBEDTLS_CHACHA20_H
  33. #if !defined(MBEDTLS_CONFIG_FILE)
  34. #include "config.h"
  35. #else
  36. #include MBEDTLS_CONFIG_FILE
  37. #endif
  38. #include <stdint.h>
  39. #include <stddef.h>
  40. #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051 /**< Invalid input parameter(s). */
  41. /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be
  42. * used. */
  43. #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053 /**< Feature not available. For example, s part of the API is not implemented. */
  44. /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used.
  45. */
  46. #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055 /**< Chacha20 hardware accelerator failed. */
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50. #if !defined(MBEDTLS_CHACHA20_ALT)
  51. typedef struct mbedtls_chacha20_context
  52. {
  53. uint32_t state[16]; /*! The state (before round operations). */
  54. uint8_t keystream8[64]; /*! Leftover keystream bytes. */
  55. size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
  56. }
  57. mbedtls_chacha20_context;
  58. #else /* MBEDTLS_CHACHA20_ALT */
  59. #include "chacha20_alt.h"
  60. #endif /* MBEDTLS_CHACHA20_ALT */
  61. /**
  62. * \brief This function initializes the specified ChaCha20 context.
  63. *
  64. * It must be the first API called before using
  65. * the context.
  66. *
  67. * It is usually followed by calls to
  68. * \c mbedtls_chacha20_setkey() and
  69. * \c mbedtls_chacha20_starts(), then one or more calls to
  70. * to \c mbedtls_chacha20_update(), and finally to
  71. * \c mbedtls_chacha20_free().
  72. *
  73. * \param ctx The ChaCha20 context to initialize.
  74. * This must not be \c NULL.
  75. */
  76. void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
  77. /**
  78. * \brief This function releases and clears the specified
  79. * ChaCha20 context.
  80. *
  81. * \param ctx The ChaCha20 context to clear. This may be \c NULL,
  82. * in which case this function is a no-op. If it is not
  83. * \c NULL, it must point to an initialized context.
  84. *
  85. */
  86. void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
  87. /**
  88. * \brief This function sets the encryption/decryption key.
  89. *
  90. * \note After using this function, you must also call
  91. * \c mbedtls_chacha20_starts() to set a nonce before you
  92. * start encrypting/decrypting data with
  93. * \c mbedtls_chacha_update().
  94. *
  95. * \param ctx The ChaCha20 context to which the key should be bound.
  96. * It must be initialized.
  97. * \param key The encryption/decryption key. This must be \c 32 Bytes
  98. * in length.
  99. *
  100. * \return \c 0 on success.
  101. * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
  102. */
  103. int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
  104. const unsigned char key[32] );
  105. /**
  106. * \brief This function sets the nonce and initial counter value.
  107. *
  108. * \note A ChaCha20 context can be re-used with the same key by
  109. * calling this function to change the nonce.
  110. *
  111. * \warning You must never use the same nonce twice with the same key.
  112. * This would void any confidentiality guarantees for the
  113. * messages encrypted with the same nonce and key.
  114. *
  115. * \param ctx The ChaCha20 context to which the nonce should be bound.
  116. * It must be initialized and bound to a key.
  117. * \param nonce The nonce. This must be \c 12 Bytes in size.
  118. * \param counter The initial counter value. This is usually \c 0.
  119. *
  120. * \return \c 0 on success.
  121. * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
  122. * NULL.
  123. */
  124. int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
  125. const unsigned char nonce[12],
  126. uint32_t counter );
  127. /**
  128. * \brief This function encrypts or decrypts data.
  129. *
  130. * Since ChaCha20 is a stream cipher, the same operation is
  131. * used for encrypting and decrypting data.
  132. *
  133. * \note The \p input and \p output pointers must either be equal or
  134. * point to non-overlapping buffers.
  135. *
  136. * \note \c mbedtls_chacha20_setkey() and
  137. * \c mbedtls_chacha20_starts() must be called at least once
  138. * to setup the context before this function can be called.
  139. *
  140. * \note This function can be called multiple times in a row in
  141. * order to encrypt of decrypt data piecewise with the same
  142. * key and nonce.
  143. *
  144. * \param ctx The ChaCha20 context to use for encryption or decryption.
  145. * It must be initialized and bound to a key and nonce.
  146. * \param size The length of the input data in Bytes.
  147. * \param input The buffer holding the input data.
  148. * This pointer can be \c NULL if `size == 0`.
  149. * \param output The buffer holding the output data.
  150. * This must be able to hold \p size Bytes.
  151. * This pointer can be \c NULL if `size == 0`.
  152. *
  153. * \return \c 0 on success.
  154. * \return A negative error code on failure.
  155. */
  156. int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
  157. size_t size,
  158. const unsigned char *input,
  159. unsigned char *output );
  160. /**
  161. * \brief This function encrypts or decrypts data with ChaCha20 and
  162. * the given key and nonce.
  163. *
  164. * Since ChaCha20 is a stream cipher, the same operation is
  165. * used for encrypting and decrypting data.
  166. *
  167. * \warning You must never use the same (key, nonce) pair more than
  168. * once. This would void any confidentiality guarantees for
  169. * the messages encrypted with the same nonce and key.
  170. *
  171. * \note The \p input and \p output pointers must either be equal or
  172. * point to non-overlapping buffers.
  173. *
  174. * \param key The encryption/decryption key.
  175. * This must be \c 32 Bytes in length.
  176. * \param nonce The nonce. This must be \c 12 Bytes in size.
  177. * \param counter The initial counter value. This is usually \c 0.
  178. * \param size The length of the input data in Bytes.
  179. * \param input The buffer holding the input data.
  180. * This pointer can be \c NULL if `size == 0`.
  181. * \param output The buffer holding the output data.
  182. * This must be able to hold \p size Bytes.
  183. * This pointer can be \c NULL if `size == 0`.
  184. *
  185. * \return \c 0 on success.
  186. * \return A negative error code on failure.
  187. */
  188. int mbedtls_chacha20_crypt( const unsigned char key[32],
  189. const unsigned char nonce[12],
  190. uint32_t counter,
  191. size_t size,
  192. const unsigned char* input,
  193. unsigned char* output );
  194. #if defined(MBEDTLS_SELF_TEST)
  195. /**
  196. * \brief The ChaCha20 checkup routine.
  197. *
  198. * \return \c 0 on success.
  199. * \return \c 1 on failure.
  200. */
  201. int mbedtls_chacha20_self_test( int verbose );
  202. #endif /* MBEDTLS_SELF_TEST */
  203. #ifdef __cplusplus
  204. }
  205. #endif
  206. #endif /* MBEDTLS_CHACHA20_H */