1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosHMAC, 6*4724848cSchristosHMAC_CTX_new, 7*4724848cSchristosHMAC_CTX_reset, 8*4724848cSchristosHMAC_CTX_free, 9*4724848cSchristosHMAC_Init, 10*4724848cSchristosHMAC_Init_ex, 11*4724848cSchristosHMAC_Update, 12*4724848cSchristosHMAC_Final, 13*4724848cSchristosHMAC_CTX_copy, 14*4724848cSchristosHMAC_CTX_set_flags, 15*4724848cSchristosHMAC_CTX_get_md, 16*4724848cSchristosHMAC_size 17*4724848cSchristos- HMAC message authentication code 18*4724848cSchristos 19*4724848cSchristos=head1 SYNOPSIS 20*4724848cSchristos 21*4724848cSchristos #include <openssl/hmac.h> 22*4724848cSchristos 23*4724848cSchristos unsigned char *HMAC(const EVP_MD *evp_md, const void *key, 24*4724848cSchristos int key_len, const unsigned char *d, size_t n, 25*4724848cSchristos unsigned char *md, unsigned int *md_len); 26*4724848cSchristos 27*4724848cSchristos HMAC_CTX *HMAC_CTX_new(void); 28*4724848cSchristos int HMAC_CTX_reset(HMAC_CTX *ctx); 29*4724848cSchristos 30*4724848cSchristos int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, 31*4724848cSchristos const EVP_MD *md, ENGINE *impl); 32*4724848cSchristos int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len); 33*4724848cSchristos int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); 34*4724848cSchristos 35*4724848cSchristos void HMAC_CTX_free(HMAC_CTX *ctx); 36*4724848cSchristos 37*4724848cSchristos int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); 38*4724848cSchristos void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); 39*4724848cSchristos const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); 40*4724848cSchristos 41*4724848cSchristos size_t HMAC_size(const HMAC_CTX *e); 42*4724848cSchristos 43*4724848cSchristosDeprecated: 44*4724848cSchristos 45*4724848cSchristos #if OPENSSL_API_COMPAT < 0x10100000L 46*4724848cSchristos int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, 47*4724848cSchristos const EVP_MD *md); 48*4724848cSchristos #endif 49*4724848cSchristos 50*4724848cSchristos=head1 DESCRIPTION 51*4724848cSchristos 52*4724848cSchristosHMAC is a MAC (message authentication code), i.e. a keyed hash 53*4724848cSchristosfunction used for message authentication, which is based on a hash 54*4724848cSchristosfunction. 55*4724848cSchristos 56*4724848cSchristosHMAC() computes the message authentication code of the B<n> bytes at 57*4724848cSchristosB<d> using the hash function B<evp_md> and the key B<key> which is 58*4724848cSchristosB<key_len> bytes long. 59*4724848cSchristos 60*4724848cSchristosIt places the result in B<md> (which must have space for the output of 61*4724848cSchristosthe hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). 62*4724848cSchristosIf B<md> is NULL, the digest is placed in a static array. The size of 63*4724848cSchristosthe output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL 64*4724848cSchristosvalue for B<md> to use the static array is not thread safe. 65*4724848cSchristos 66*4724848cSchristosB<evp_md> is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does 67*4724848cSchristosnot support variable output length digests such as EVP_shake128() and 68*4724848cSchristosEVP_shake256(). 69*4724848cSchristos 70*4724848cSchristosHMAC_CTX_new() creates a new HMAC_CTX in heap memory. 71*4724848cSchristos 72*4724848cSchristosHMAC_CTX_reset() zeros an existing B<HMAC_CTX> and associated 73*4724848cSchristosresources, making it suitable for new computations as if it was newly 74*4724848cSchristoscreated with HMAC_CTX_new(). 75*4724848cSchristos 76*4724848cSchristosHMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>, 77*4724848cSchristosreleases any associated resources and finally frees the B<HMAC_CTX> 78*4724848cSchristositself. 79*4724848cSchristos 80*4724848cSchristosThe following functions may be used if the message is not completely 81*4724848cSchristosstored in memory: 82*4724848cSchristos 83*4724848cSchristosHMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash 84*4724848cSchristosfunction B<evp_md> and key B<key>. If both are NULL, or if B<key> is NULL 85*4724848cSchristosand B<evp_md> is the same as the previous call, then the 86*4724848cSchristosexisting key is 87*4724848cSchristosreused. B<ctx> must have been created with HMAC_CTX_new() before the first use 88*4724848cSchristosof an B<HMAC_CTX> in this function. 89*4724848cSchristos 90*4724848cSchristosIf HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the 91*4724848cSchristossame as the previous digest used by B<ctx> then an error is returned 92*4724848cSchristosbecause reuse of an existing key with a different digest is not supported. 93*4724848cSchristos 94*4724848cSchristosHMAC_Init() initializes a B<HMAC_CTX> structure to use the hash 95*4724848cSchristosfunction B<evp_md> and the key B<key> which is B<key_len> bytes 96*4724848cSchristoslong. 97*4724848cSchristos 98*4724848cSchristosHMAC_Update() can be called repeatedly with chunks of the message to 99*4724848cSchristosbe authenticated (B<len> bytes at B<data>). 100*4724848cSchristos 101*4724848cSchristosHMAC_Final() places the message authentication code in B<md>, which 102*4724848cSchristosmust have space for the hash function output. 103*4724848cSchristos 104*4724848cSchristosHMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>. 105*4724848cSchristos 106*4724848cSchristosHMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs. 107*4724848cSchristosThese flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>. 108*4724848cSchristos 109*4724848cSchristosHMAC_CTX_get_md() returns the EVP_MD that has previously been set for the 110*4724848cSchristossupplied HMAC_CTX. 111*4724848cSchristos 112*4724848cSchristosHMAC_size() returns the length in bytes of the underlying hash function output. 113*4724848cSchristos 114*4724848cSchristos=head1 RETURN VALUES 115*4724848cSchristos 116*4724848cSchristosHMAC() returns a pointer to the message authentication code or NULL if 117*4724848cSchristosan error occurred. 118*4724848cSchristos 119*4724848cSchristosHMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or 120*4724848cSchristosB<NULL> if an error occurred. 121*4724848cSchristos 122*4724848cSchristosHMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and 123*4724848cSchristosHMAC_CTX_copy() return 1 for success or 0 if an error occurred. 124*4724848cSchristos 125*4724848cSchristosHMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or 126*4724848cSchristosNULL if no EVP_MD has been set. 127*4724848cSchristos 128*4724848cSchristosHMAC_size() returns the length in bytes of the underlying hash function output 129*4724848cSchristosor zero on error. 130*4724848cSchristos 131*4724848cSchristos=head1 CONFORMING TO 132*4724848cSchristos 133*4724848cSchristosRFC 2104 134*4724848cSchristos 135*4724848cSchristos=head1 SEE ALSO 136*4724848cSchristos 137*4724848cSchristosL<SHA1(3)>, L<evp(7)> 138*4724848cSchristos 139*4724848cSchristos=head1 HISTORY 140*4724848cSchristos 141*4724848cSchristosHMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL 1.1.0. 142*4724848cSchristos 143*4724848cSchristosHMAC_CTX_cleanup() existed in OpenSSL before version 1.1.0. 144*4724848cSchristos 145*4724848cSchristosHMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL 1.1.0. 146*4724848cSchristos 147*4724848cSchristosHMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in 148*4724848cSchristosOpenSSL before version 1.0.0. 149*4724848cSchristos 150*4724848cSchristos=head1 COPYRIGHT 151*4724848cSchristos 152*4724848cSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 153*4724848cSchristos 154*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 155*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 156*4724848cSchristosin the file LICENSE in the source distribution or at 157*4724848cSchristosL<https://www.openssl.org/source/license.html>. 158*4724848cSchristos 159*4724848cSchristos=cut 160