digests.h 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. #ifndef _CRYPTO_DIGESTS_H_
  2. #define _CRYPTO_DIGESTS_H_
  3. #include <stdint.h>
  4. #include <stddef.h>
  5. typedef void (*create_ctx_fn)(void *ctx);
  6. typedef void (*update_ctx_fn)(void *ctx, const uint8_t *msg, int len);
  7. typedef void (*finalize_ctx_fn)(uint8_t *digest, void *ctx);
  8. typedef int32_t ( *read_fn )(int fd, void *ptr, size_t len);
  9. /**
  10. * Description of a message digest mechanism.
  11. *
  12. * Typical usage (if not using the crypto_xxxx() functions below):
  13. * digest_mech_info_t *mi = crypto_digest_mech (chosen_algorithm);
  14. * void *ctx = os_malloc (mi->ctx_size);
  15. * mi->create (ctx);
  16. * mi->update (ctx, data, len);
  17. * ...
  18. * uint8_t *digest = os_malloc (mi->digest_size);
  19. * mi->finalize (digest, ctx);
  20. * ...
  21. * os_free (ctx);
  22. * os_free (digest);
  23. */
  24. typedef struct
  25. {
  26. /* Note: All entries are 32bit to enable placement using ICACHE_RODATA_ATTR.*/
  27. const char * name;
  28. create_ctx_fn create;
  29. update_ctx_fn update;
  30. finalize_ctx_fn finalize;
  31. uint32_t ctx_size;
  32. uint32_t digest_size;
  33. uint32_t block_size;
  34. } digest_mech_info_t;
  35. /**
  36. * Looks up the mech data for a specified digest algorithm.
  37. * @param mech The name of the algorithm, e.g. "MD5", "SHA256"
  38. * @returns The mech data, or null if the mech is unknown.
  39. */
  40. const digest_mech_info_t *crypto_digest_mech (const char *mech);
  41. /**
  42. * Wrapper function for performing a one-in-all hashing operation.
  43. * @param mi A mech from @c crypto_digest_mech(). A null pointer @c mi
  44. * is harmless, but will of course result in an error return.
  45. * @param data The data to create a digest for.
  46. * @param data_len Number of bytes at @c data to digest.
  47. * @param digest Output buffer, must be at least @c mi->digest_size in size.
  48. * @return 0 on success, non-zero on error.
  49. */
  50. int crypto_hash (const digest_mech_info_t *mi, const char *data, size_t data_len, uint8_t *digest);
  51. /**
  52. * Wrapper function for performing a one-in-all hashing operation of a file.
  53. * @param mi A mech from @c crypto_digest_mech(). A null pointer @c mi
  54. * is harmless, but will of course result in an error return.
  55. * @param read Pointer to the read function (e.g. fs_read)
  56. * @param readarg Argument to pass to the read function (e.g. file descriptor)
  57. * @param digest Output buffer, must be at least @c mi->digest_size in size.
  58. * @return 0 on success, non-zero on error.
  59. */
  60. int crypto_fhash (const digest_mech_info_t *mi, read_fn read, int readarg, uint8_t *digest);
  61. /**
  62. * Commence calculating a HMAC signature.
  63. *
  64. * Once this fuction returns successfully, the @c ctx may be updated with
  65. * data in multiple passes uses @c mi->update(), before being finalized via
  66. * @c crypto_hmac_finalize().
  67. *
  68. * @param ctx A created context for the given mech @c mi.
  69. * @param mi A mech from @c crypto_digest_mech().
  70. * @param key The key bytes to use.
  71. * @param key_len Number of bytes the @c key comprises.
  72. * @param k_opad Buffer of size @c mi->block_size bytes to store the second
  73. * round of key material in.
  74. * Must be passed to @c crypto_hmac_finalize().
  75. */
  76. void crypto_hmac_begin (void *ctx, const digest_mech_info_t *mi, const char *key, size_t key_len, uint8_t *k_opad);
  77. /**
  78. * Finalizes calculating a HMAC signature.
  79. * @param ctx The created context used with @c crypto_hmac_begin().
  80. * @param mi The mech used with @c crypto_hmac_begin().
  81. * @param k_opad Second round of keying material, obtained
  82. * from @c crypto_hmac_begin().
  83. * @param digest Output buffer, must be at least @c mi->digest_size in size.
  84. */
  85. void crypto_hmac_finalize (void *ctx, const digest_mech_info_t *mi, const uint8_t *k_opad, uint8_t *digest);
  86. /**
  87. * Generate a HMAC signature in one pass.
  88. * Implemented in terms of @c crypto_hmac_begin() / @c crypto_hmac_end().
  89. * @param mi A mech from @c crypto_digest_mech(). A null pointer @c mi
  90. * is harmless, but will of course result in an error return.
  91. * @param data The data to generate a signature for.
  92. * @param data_len Number of bytes at @c data to process.
  93. * @param key The key to use.
  94. * @param key_len Number of bytes the @c key comprises.
  95. * @param digest Output buffer, must be at least @c mi->digest_size in size.
  96. * @return 0 on success, non-zero on error.
  97. */
  98. int crypto_hmac (const digest_mech_info_t *mi, const char *data, size_t data_len, const char *key, size_t key_len, uint8_t *digest);
  99. /**
  100. * Perform ASCII Hex encoding. Does not null-terminate the buffer.
  101. *
  102. * @param bin The buffer to ascii-hex encode.
  103. * @param bin_len Number of bytes in @c bin to encode.
  104. * @param outbuf Output buffer, must be at least @c bin_len*2 bytes in size.
  105. * Note that in-place encoding is supported, and as such
  106. * bin==outbuf is safe, provided the buffer is large enough.
  107. */
  108. void crypto_encode_asciihex (const char *bin, size_t bin_len, char *outbuf);
  109. /** Text string "0123456789abcdef" */
  110. const char crypto_hexbytes[17];
  111. #endif