OpenBSD manual page server

Manual Page Search Parameters

HMAC(3) Library Functions Manual HMAC(3)

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_sizeHMAC message authentication code

#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);

HMAC is a MAC (message authentication code), i.e. a keyed hash function used for message authentication, which is based on a hash function.

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

() allocates and initializes a new HMAC_CTX object.

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

() erases the key and other data from ctx, releases any associated resources, and finally frees ctx itself.

() is a deprecated function to initialize an empty HMAC_CTX object, similar to () but without the allocation. Calling it is required for static objects and objects on the stack before using them.

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

() 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:

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

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

() can be called repeatedly with chunks of the message to be authenticated (len bytes at data).

() places the message authentication code in md, which must have space for the hash function output.

() copies all of the internal state from sctx into dctx.

() applies the specified flags to the internal EVP_MD_CTX objects. Possible flag values EVP_MD_CTX_FLAG_* are defined in <openssl/evp.h>.

() returns the length in bytes of the underlying hash function output. It is implemented as a macro.

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.

CMAC_Init(3), EVP_DigestInit(3)

RFC 2104

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.

June 24, 2020 OpenBSD-6.9