HMAC(3) | Library Functions Manual | HMAC(3)

# NAME

`HMAC`, `HMAC_CTX_new`, `HMAC_CTX_reset`, `HMAC_CTX_free`, `HMAC_Init_ex`, `HMAC_Update`, `HMAC_Final`, `HMAC_CTX_copy`, `HMAC_CTX_set_flags`, `HMAC_CTX_get_md`, `HMAC_size` — HMAC message authentication code

# SYNOPSIS

library “libcrypto”
`#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);

int
`HMAC_Init_ex`(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md, ENGINE *engine);

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. 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.

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`() 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. The ENGINE *engine argument is always ignored and passing `NULL` is recommended.

`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_Update`(), `HMAC_Final`(), and `HMAC_size`() first appeared in SSLeay 0.9.0 and have been available since OpenBSD 2.4.

`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.

# CAVEATS

Other implementations allow md in `HMAC`() to be `NULL` and return a static array, which is not thread safe.

June 8, 2025 | Debian