md.h 18 KB

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