NAME

HMAC, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free, HMAC_CTX_init, HMAC_CTX_cleanup, HMAC_cleanup, HMAC_Init_ex, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags, HMAC_CTX_get_md, HMAC_size — HMAC message authentication code

SYNOPSIS

#include <openssl/hmac.h> unsigned char *
HMAC(const EVP_MD *evp_md, const void *key, int key_len, const unsigned char *d, size_t n, unsigned char *md, unsigned int *md_len); HMAC_CTX *
HMAC_CTX_new(void); int
HMAC_CTX_reset(HMAC_CTX *ctx); void
HMAC_CTX_free(HMAC_CTX *ctx); void
HMAC_CTX_init(HMAC_CTX *ctx); void
HMAC_CTX_cleanup(HMAC_CTX *ctx); void
HMAC_cleanup(HMAC_CTX *ctx); int
HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md, ENGINE *impl); int
HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md); int
HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len); int
HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); int
HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); void
HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); const EVP_MD *
HMAC_CTX_get_md(const HMAC_CTX *ctx); size_t
HMAC_size(const HMAC_CTX *e);

DESCRIPTION

HMAC is a MAC (message authentication code), i.e. a keyed hash function used for message authentication, which is based on a hash function. HMAC() computes the message authentication code of the n bytes at d using the hash function evp_md and the key key which is key_len bytes long. It places the result in md, which must have space for the output of the hash function, which is no more than EVP_MAX_MD_SIZE bytes. If md is NULL, the digest is placed in a static array, which is not thread safe. The size of the output is placed in md_len, unless it is NULL. evp_md can be EVP_sha1(3), EVP_ripemd160(3), etc. HMAC_CTX_new() allocates and initializes a new HMAC_CTX object. HMAC_CTX_reset() zeroes and re-initializes ctx and associated resources, making it suitable for new computations as if it was deleted with HMAC_CTX_free() and newly created with HMAC_CTX_new(). HMAC_CTX_free() erases the key and other data from ctx, releases any associated resources, and finally frees ctx itself. HMAC_CTX_init() is a deprecated function to initialize an empty HMAC_CTX object, similar to CTX_new() but without the allocation. Calling it is required for static objects and objects on the stack before using them. HMAC_CTX_cleanup() is a deprecated function to erase the key and other data from ctx and release any associated resources, similar to HMAC_CTX_free() but without freeing ctx itself. Calling it is required for static objects and objects on the stack that were initialized with HMAC_CTX_init() and are no longer needed. HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for backward compatibility with 0.9.6b. It is deprecated and implemented as a macro. The following functions may be used if the message is not completely stored in memory: HMAC_Init_ex() sets up or reuses ctx to use the hash function evp_md and the key key. Either can be NULL, in which case the existing one is reused. The ctx must have been created with HMAC_CTX_new() or initialized with HMAC_CTX_init() before the first use in this function. If HMAC_Init_ex() is called with a NULL key but evp_md is neither NULL nor the same as the previous digest used by ctx, then an error is returned because reuse of an existing key with a different digest is not supported. HMAC_Init() is a deprecated wrapper around HMAC_Init_ex(). If called with both key and md, it calls HMAC_CTX_init() first, which only makes sense for an empty, uninitialized ctx, but not for one already initialized with HMAC_CTX_new() or HMAC_CTX_init(). If key or md is NULL, it does not call HMAC_CTX_init(); so in this case, ctx already needs to be initialized with HMAC_CTX_new() or HMAC_CTX_init(). HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (len bytes at data). HMAC_Final() places the message authentication code in md, which must have space for the hash function output. HMAC_CTX_copy() copies all of the internal state from sctx into dctx. HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTX objects. Possible flag values EVP_MD_CTX_FLAG_* are defined in <openssl/evp.h>. HMAC_size() returns the length in bytes of the underlying hash function output. It is implemented as a macro.

RETURN VALUES

HMAC() returns a pointer to the message authentication code or NULL if an error occurred. HMAC_CTX_new() returns a pointer to the new HMAC_CTX object or NULL if an error occurred. HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final(), and HMAC_CTX_copy() return 1 for success or 0 if an error occurred. HMAC_CTX_get_md() returns the message digest that was previously set for ctx with HMAC_Init_ex(), or NULL if none was set. HMAC_size() returns the length in bytes of the underlying hash function output or 0 on error.

SEE ALSO

CMAC_Init(3), EVP_DigestInit(3)

STANDARDS

RFC 2104

HISTORY

HMAC(), HMAC_cleanup(), HMAC_Init(), HMAC_Update(), HMAC_Final(), and HMAC_size() first appeared in SSLeay 0.9.0 and have been available since OpenBSD 2.4. HMAC_CTX_init(), HMAC_CTX_cleanup(), and HMAC_Init_ex() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. HMAC_CTX_set_flags() first appeared in OpenSSL 0.9.7f and have been available since OpenBSD 3.8. HMAC_CTX_copy() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9. HMAC_CTX_new(), HMAC_CTX_reset(), HMAC_CTX_free(), and HMAC_CTX_get_md() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3.