hmac.pod 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
  1. =pod
  2. =head1 NAME
  3. HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message
  4. authentication code
  5. =head1 SYNOPSIS
  6. #include <openssl/hmac.h>
  7. unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
  8. int key_len, const unsigned char *d, int n,
  9. unsigned char *md, unsigned int *md_len);
  10. void HMAC_CTX_init(HMAC_CTX *ctx);
  11. int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
  12. const EVP_MD *md);
  13. int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
  14. const EVP_MD *md, ENGINE *impl);
  15. int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
  16. int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
  17. void HMAC_CTX_cleanup(HMAC_CTX *ctx);
  18. void HMAC_cleanup(HMAC_CTX *ctx);
  19. =head1 DESCRIPTION
  20. HMAC is a MAC (message authentication code), i.e. a keyed hash
  21. function used for message authentication, which is based on a hash
  22. function.
  23. HMAC() computes the message authentication code of the B<n> bytes at
  24. B<d> using the hash function B<evp_md> and the key B<key> which is
  25. B<key_len> bytes long.
  26. It places the result in B<md> (which must have space for the output of
  27. the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes).
  28. If B<md> is NULL, the digest is placed in a static array. The size of
  29. the output is placed in B<md_len>, unless it is B<NULL>.
  30. B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
  31. HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be
  32. called.
  33. HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX>
  34. and releases any associated resources. It must be called when an
  35. B<HMAC_CTX> is no longer required.
  36. HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back
  37. compatibility with 0.9.6b, it is deprecated.
  38. The following functions may be used if the message is not completely
  39. stored in memory:
  40. HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
  41. function B<evp_md> and the key B<key> which is B<key_len> bytes
  42. long. It is deprecated and only included for backward compatibility
  43. with OpenSSL 0.9.6b.
  44. HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use
  45. the function B<evp_md> and key B<key>. Either can be NULL, in which
  46. case the existing one will be reused. HMAC_CTX_init() must have been
  47. called before the first use of an B<HMAC_CTX> in this
  48. function. B<N.B. HMAC_Init() had this undocumented behaviour in
  49. previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in
  50. programs that expect it will cause them to stop working>.
  51. HMAC_Update() can be called repeatedly with chunks of the message to
  52. be authenticated (B<len> bytes at B<data>).
  53. HMAC_Final() places the message authentication code in B<md>, which
  54. must have space for the hash function output.
  55. =head1 RETURN VALUES
  56. HMAC() returns a pointer to the message authentication code or NULL if
  57. an error occurred.
  58. HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if
  59. an error occurred.
  60. HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values.
  61. =head1 CONFORMING TO
  62. RFC 2104
  63. =head1 SEE ALSO
  64. L<sha(3)|sha(3)>, L<evp(3)|evp(3)>
  65. =head1 HISTORY
  66. HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup()
  67. are available since SSLeay 0.9.0.
  68. HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available
  69. since OpenSSL 0.9.7.
  70. HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in
  71. versions of OpenSSL before 1.0.0.
  72. =cut