1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message 6*2175Sjp161948authentication code 7*2175Sjp161948 8*2175Sjp161948=head1 SYNOPSIS 9*2175Sjp161948 10*2175Sjp161948 #include <openssl/hmac.h> 11*2175Sjp161948 12*2175Sjp161948 unsigned char *HMAC(const EVP_MD *evp_md, const void *key, 13*2175Sjp161948 int key_len, const unsigned char *d, int n, 14*2175Sjp161948 unsigned char *md, unsigned int *md_len); 15*2175Sjp161948 16*2175Sjp161948 void HMAC_CTX_init(HMAC_CTX *ctx); 17*2175Sjp161948 18*2175Sjp161948 void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, 19*2175Sjp161948 const EVP_MD *md); 20*2175Sjp161948 void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, 21*2175Sjp161948 const EVP_MD *md); 22*2175Sjp161948 void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); 23*2175Sjp161948 void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); 24*2175Sjp161948 25*2175Sjp161948 void HMAC_CTX_cleanup(HMAC_CTX *ctx); 26*2175Sjp161948 void HMAC_cleanup(HMAC_CTX *ctx); 27*2175Sjp161948 28*2175Sjp161948=head1 DESCRIPTION 29*2175Sjp161948 30*2175Sjp161948HMAC is a MAC (message authentication code), i.e. a keyed hash 31*2175Sjp161948function used for message authentication, which is based on a hash 32*2175Sjp161948function. 33*2175Sjp161948 34*2175Sjp161948HMAC() computes the message authentication code of the B<n> bytes at 35*2175Sjp161948B<d> using the hash function B<evp_md> and the key B<key> which is 36*2175Sjp161948B<key_len> bytes long. 37*2175Sjp161948 38*2175Sjp161948It places the result in B<md> (which must have space for the output of 39*2175Sjp161948the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). 40*2175Sjp161948If B<md> is NULL, the digest is placed in a static array. The size of 41*2175Sjp161948the output is placed in B<md_len>, unless it is B<NULL>. 42*2175Sjp161948 43*2175Sjp161948B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. 44*2175Sjp161948B<key> and B<evp_md> may be B<NULL> if a key and hash function have 45*2175Sjp161948been set in a previous call to HMAC_Init() for that B<HMAC_CTX>. 46*2175Sjp161948 47*2175Sjp161948HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be 48*2175Sjp161948called. 49*2175Sjp161948 50*2175Sjp161948HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX> 51*2175Sjp161948and releases any associated resources. It must be called when an 52*2175Sjp161948B<HMAC_CTX> is no longer required. 53*2175Sjp161948 54*2175Sjp161948HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back 55*2175Sjp161948compatibility with 0.9.6b, it is deprecated. 56*2175Sjp161948 57*2175Sjp161948The following functions may be used if the message is not completely 58*2175Sjp161948stored in memory: 59*2175Sjp161948 60*2175Sjp161948HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash 61*2175Sjp161948function B<evp_md> and the key B<key> which is B<key_len> bytes 62*2175Sjp161948long. It is deprecated and only included for backward compatibility 63*2175Sjp161948with OpenSSL 0.9.6b. 64*2175Sjp161948 65*2175Sjp161948HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use 66*2175Sjp161948the function B<evp_md> and key B<key>. Either can be NULL, in which 67*2175Sjp161948case the existing one will be reused. HMAC_CTX_init() must have been 68*2175Sjp161948called before the first use of an B<HMAC_CTX> in this 69*2175Sjp161948function. B<N.B. HMAC_Init() had this undocumented behaviour in 70*2175Sjp161948previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in 71*2175Sjp161948programs that expect it will cause them to stop working>. 72*2175Sjp161948 73*2175Sjp161948HMAC_Update() can be called repeatedly with chunks of the message to 74*2175Sjp161948be authenticated (B<len> bytes at B<data>). 75*2175Sjp161948 76*2175Sjp161948HMAC_Final() places the message authentication code in B<md>, which 77*2175Sjp161948must have space for the hash function output. 78*2175Sjp161948 79*2175Sjp161948=head1 RETURN VALUES 80*2175Sjp161948 81*2175Sjp161948HMAC() returns a pointer to the message authentication code. 82*2175Sjp161948 83*2175Sjp161948HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and 84*2175Sjp161948HMAC_CTX_cleanup() do not return values. 85*2175Sjp161948 86*2175Sjp161948=head1 CONFORMING TO 87*2175Sjp161948 88*2175Sjp161948RFC 2104 89*2175Sjp161948 90*2175Sjp161948=head1 SEE ALSO 91*2175Sjp161948 92*2175Sjp161948L<sha(3)|sha(3)>, L<evp(3)|evp(3)> 93*2175Sjp161948 94*2175Sjp161948=head1 HISTORY 95*2175Sjp161948 96*2175Sjp161948HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() 97*2175Sjp161948are available since SSLeay 0.9.0. 98*2175Sjp161948 99*2175Sjp161948HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available 100*2175Sjp161948since OpenSSL 0.9.7. 101*2175Sjp161948 102*2175Sjp161948=cut 103