md.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453
  1. /**
  2. * \file md.h
  3. *
  4. * \brief The generic message-digest wrapper.
  5. *
  6. * \author Adriaan de Jong <dejong@fox-it.com>
  7. */
  8. /*
  9. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  10. * SPDX-License-Identifier: Apache-2.0
  11. *
  12. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  13. * not use this file except in compliance with the License.
  14. * You may obtain a copy of the License at
  15. *
  16. * http://www.apache.org/licenses/LICENSE-2.0
  17. *
  18. * Unless required by applicable law or agreed to in writing, software
  19. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  20. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21. * See the License for the specific language governing permissions and
  22. * limitations under the License.
  23. *
  24. * This file is part of Mbed TLS (https://tls.mbed.org)
  25. */
  26. #ifndef MBEDTLS_MD_H
  27. #define MBEDTLS_MD_H
  28. #include <stddef.h>
  29. #if !defined(MBEDTLS_CONFIG_FILE)
  30. #include "config.h"
  31. #else
  32. #include MBEDTLS_CONFIG_FILE
  33. #endif
  34. #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 /**< The selected feature is not available. */
  35. #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */
  36. #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */
  37. #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */
  38. #define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 /**< MD hardware accelerator failed. */
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42. /**
  43. * \brief Enumeration of supported message digests
  44. *
  45. * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and
  46. * their use constitutes a security risk. We recommend considering
  47. * stronger message digests instead.
  48. *
  49. */
  50. typedef enum {
  51. MBEDTLS_MD_NONE=0,
  52. MBEDTLS_MD_MD2,
  53. MBEDTLS_MD_MD4,
  54. MBEDTLS_MD_MD5,
  55. MBEDTLS_MD_SHA1,
  56. MBEDTLS_MD_SHA224,
  57. MBEDTLS_MD_SHA256,
  58. MBEDTLS_MD_SHA384,
  59. MBEDTLS_MD_SHA512,
  60. MBEDTLS_MD_RIPEMD160,
  61. } mbedtls_md_type_t;
  62. #if defined(MBEDTLS_SHA512_C)
  63. #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
  64. #else
  65. #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */
  66. #endif
  67. /**
  68. * Opaque struct defined in md_internal.h.
  69. */
  70. typedef struct mbedtls_md_info_t mbedtls_md_info_t;
  71. /**
  72. * The generic message-digest context.
  73. */
  74. typedef struct {
  75. /** Information about the associated message digest. */
  76. const mbedtls_md_info_t *md_info;
  77. /** The digest-specific context. */
  78. void *md_ctx;
  79. /** The HMAC part of the context. */
  80. void *hmac_ctx;
  81. } mbedtls_md_context_t;
  82. /**
  83. * \brief This function returns the list of digests supported by the
  84. * generic digest module.
  85. *
  86. * \return A statically allocated array of digests. Each element
  87. * in the returned list is an integer belonging to the
  88. * message-digest enumeration #mbedtls_md_type_t.
  89. * The last entry is 0.
  90. */
  91. const int *mbedtls_md_list( void );
  92. /**
  93. * \brief This function returns the message-digest information
  94. * associated with the given digest name.
  95. *
  96. * \param md_name The name of the digest to search for.
  97. *
  98. * \return The message-digest information associated with \p md_name,
  99. * or NULL if not found.
  100. */
  101. const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
  102. /**
  103. * \brief This function returns the message-digest information
  104. * associated with the given digest type.
  105. *
  106. * \param md_type The type of digest to search for.
  107. *
  108. * \return The message-digest information associated with \p md_type,
  109. * or NULL if not found.
  110. */
  111. const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
  112. /**
  113. * \brief This function initializes a message-digest context without
  114. * binding it to a particular message-digest algorithm.
  115. *
  116. * This function should always be called first. It prepares the
  117. * context for mbedtls_md_setup() for binding it to a
  118. * message-digest algorithm.
  119. */
  120. void mbedtls_md_init( mbedtls_md_context_t *ctx );
  121. /**
  122. * \brief This function clears the internal structure of \p ctx and
  123. * frees any embedded internal structure, but does not free
  124. * \p ctx itself.
  125. *
  126. * If you have called mbedtls_md_setup() on \p ctx, you must
  127. * call mbedtls_md_free() when you are no longer using the
  128. * context.
  129. * Calling this function if you have previously
  130. * called mbedtls_md_init() and nothing else is optional.
  131. * You must not call this function if you have not called
  132. * mbedtls_md_init().
  133. */
  134. void mbedtls_md_free( mbedtls_md_context_t *ctx );
  135. #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
  136. #if defined(MBEDTLS_DEPRECATED_WARNING)
  137. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  138. #else
  139. #define MBEDTLS_DEPRECATED
  140. #endif
  141. /**
  142. * \brief This function selects the message digest algorithm to use,
  143. * and allocates internal structures.
  144. *
  145. * It should be called after mbedtls_md_init() or mbedtls_md_free().
  146. * Makes it necessary to call mbedtls_md_free() later.
  147. *
  148. * \deprecated Superseded by mbedtls_md_setup() in 2.0.0
  149. *
  150. * \param ctx The context to set up.
  151. * \param md_info The information structure of the message-digest algorithm
  152. * to use.
  153. *
  154. * \returns \c 0 on success,
  155. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
  156. * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
  157. */
  158. int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
  159. #undef MBEDTLS_DEPRECATED
  160. #endif /* MBEDTLS_DEPRECATED_REMOVED */
  161. /**
  162. * \brief This function selects the message digest algorithm to use,
  163. * and allocates internal structures.
  164. *
  165. * It should be called after mbedtls_md_init() or
  166. * mbedtls_md_free(). Makes it necessary to call
  167. * mbedtls_md_free() later.
  168. *
  169. * \param ctx The context to set up.
  170. * \param md_info The information structure of the message-digest algorithm
  171. * to use.
  172. * \param hmac <ul><li>0: HMAC is not used. Saves some memory.</li>
  173. * <li>non-zero: HMAC is used with this context.</li></ul>
  174. *
  175. * \returns \c 0 on success,
  176. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
  177. * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
  178. */
  179. int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
  180. /**
  181. * \brief This function clones the state of an message-digest
  182. * context.
  183. *
  184. * \note You must call mbedtls_md_setup() on \c dst before calling
  185. * this function.
  186. *
  187. * \note The two contexts must have the same type,
  188. * for example, both are SHA-256.
  189. *
  190. * \warning This function clones the message-digest state, not the
  191. * HMAC state.
  192. *
  193. * \param dst The destination context.
  194. * \param src The context to be cloned.
  195. *
  196. * \return \c 0 on success,
  197. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
  198. */
  199. int mbedtls_md_clone( mbedtls_md_context_t *dst,
  200. const mbedtls_md_context_t *src );
  201. /**
  202. * \brief This function extracts the message-digest size from the
  203. * message-digest information structure.
  204. *
  205. * \param md_info The information structure of the message-digest algorithm
  206. * to use.
  207. *
  208. * \return The size of the message-digest output in Bytes.
  209. */
  210. unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );
  211. /**
  212. * \brief This function extracts the message-digest type from the
  213. * message-digest information structure.
  214. *
  215. * \param md_info The information structure of the message-digest algorithm
  216. * to use.
  217. *
  218. * \return The type of the message digest.
  219. */
  220. mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );
  221. /**
  222. * \brief This function extracts the message-digest name from the
  223. * message-digest information structure.
  224. *
  225. * \param md_info The information structure of the message-digest algorithm
  226. * to use.
  227. *
  228. * \return The name of the message digest.
  229. */
  230. const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
  231. /**
  232. * \brief This function starts a message-digest computation.
  233. *
  234. * You must call this function after setting up the context
  235. * with mbedtls_md_setup(), and before passing data with
  236. * mbedtls_md_update().
  237. *
  238. * \param ctx The generic message-digest context.
  239. *
  240. * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  241. * parameter verification fails.
  242. */
  243. int mbedtls_md_starts( mbedtls_md_context_t *ctx );
  244. /**
  245. * \brief This function feeds an input buffer into an ongoing
  246. * message-digest computation.
  247. *
  248. * You must call mbedtls_md_starts() before calling this
  249. * function. You may call this function multiple times.
  250. * Afterwards, call mbedtls_md_finish().
  251. *
  252. * \param ctx The generic message-digest context.
  253. * \param input The buffer holding the input data.
  254. * \param ilen The length of the input data.
  255. *
  256. * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  257. * parameter verification fails.
  258. */
  259. int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
  260. /**
  261. * \brief This function finishes the digest operation,
  262. * and writes the result to the output buffer.
  263. *
  264. * Call this function after a call to mbedtls_md_starts(),
  265. * followed by any number of calls to mbedtls_md_update().
  266. * Afterwards, you may either clear the context with
  267. * mbedtls_md_free(), or call mbedtls_md_starts() to reuse
  268. * the context for another digest operation with the same
  269. * algorithm.
  270. *
  271. * \param ctx The generic message-digest context.
  272. * \param output The buffer for the generic message-digest checksum result.
  273. *
  274. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  275. * parameter verification fails.
  276. */
  277. int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
  278. /**
  279. * \brief This function calculates the message-digest of a buffer,
  280. * with respect to a configurable message-digest algorithm
  281. * in a single call.
  282. *
  283. * The result is calculated as
  284. * Output = message_digest(input buffer).
  285. *
  286. * \param md_info The information structure of the message-digest algorithm
  287. * to use.
  288. * \param input The buffer holding the data.
  289. * \param ilen The length of the input data.
  290. * \param output The generic message-digest checksum result.
  291. *
  292. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  293. * parameter verification fails.
  294. */
  295. int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
  296. unsigned char *output );
  297. #if defined(MBEDTLS_FS_IO)
  298. /**
  299. * \brief This function calculates the message-digest checksum
  300. * result of the contents of the provided file.
  301. *
  302. * The result is calculated as
  303. * Output = message_digest(file contents).
  304. *
  305. * \param md_info The information structure of the message-digest algorithm
  306. * to use.
  307. * \param path The input file name.
  308. * \param output The generic message-digest checksum result.
  309. *
  310. * \return \c 0 on success,
  311. * #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
  312. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
  313. */
  314. int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
  315. unsigned char *output );
  316. #endif /* MBEDTLS_FS_IO */
  317. /**
  318. * \brief This function sets the HMAC key and prepares to
  319. * authenticate a new message.
  320. *
  321. * Call this function after mbedtls_md_setup(), to use
  322. * the MD context for an HMAC calculation, then call
  323. * mbedtls_md_hmac_update() to provide the input data, and
  324. * mbedtls_md_hmac_finish() to get the HMAC value.
  325. *
  326. * \param ctx The message digest context containing an embedded HMAC
  327. * context.
  328. * \param key The HMAC secret key.
  329. * \param keylen The length of the HMAC key in Bytes.
  330. *
  331. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  332. * parameter verification fails.
  333. */
  334. int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
  335. size_t keylen );
  336. /**
  337. * \brief This function feeds an input buffer into an ongoing HMAC
  338. * computation.
  339. *
  340. * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
  341. * before calling this function.
  342. * You may call this function multiple times to pass the
  343. * input piecewise.
  344. * Afterwards, call mbedtls_md_hmac_finish().
  345. *
  346. * \param ctx The message digest context containing an embedded HMAC
  347. * context.
  348. * \param input The buffer holding the input data.
  349. * \param ilen The length of the input data.
  350. *
  351. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  352. * parameter verification fails.
  353. */
  354. int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
  355. size_t ilen );
  356. /**
  357. * \brief This function finishes the HMAC operation, and writes
  358. * the result to the output buffer.
  359. *
  360. * Call this function after mbedtls_md_hmac_starts() and
  361. * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
  362. * you may either call mbedtls_md_free() to clear the context,
  363. * or call mbedtls_md_hmac_reset() to reuse the context with
  364. * the same HMAC key.
  365. *
  366. * \param ctx The message digest context containing an embedded HMAC
  367. * context.
  368. * \param output The generic HMAC checksum result.
  369. *
  370. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  371. * parameter verification fails.
  372. */
  373. int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
  374. /**
  375. * \brief This function prepares to authenticate a new message with
  376. * the same key as the previous HMAC operation.
  377. *
  378. * You may call this function after mbedtls_md_hmac_finish().
  379. * Afterwards call mbedtls_md_hmac_update() to pass the new
  380. * input.
  381. *
  382. * \param ctx The message digest context containing an embedded HMAC
  383. * context.
  384. *
  385. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  386. * parameter verification fails.
  387. */
  388. int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
  389. /**
  390. * \brief This function calculates the full generic HMAC
  391. * on the input buffer with the provided key.
  392. *
  393. * The function allocates the context, performs the
  394. * calculation, and frees the context.
  395. *
  396. * The HMAC result is calculated as
  397. * output = generic HMAC(hmac key, input buffer).
  398. *
  399. * \param md_info The information structure of the message-digest algorithm
  400. * to use.
  401. * \param key The HMAC secret key.
  402. * \param keylen The length of the HMAC secret key in Bytes.
  403. * \param input The buffer holding the input data.
  404. * \param ilen The length of the input data.
  405. * \param output The generic HMAC result.
  406. *
  407. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
  408. * parameter verification fails.
  409. */
  410. int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
  411. const unsigned char *input, size_t ilen,
  412. unsigned char *output );
  413. /* Internal use */
  414. int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data );
  415. #ifdef __cplusplus
  416. }
  417. #endif
  418. #endif /* MBEDTLS_MD_H */