[OpenBSD]

Manual Page Search Parameters

HMAC(3) Library Functions Manual HMAC(3)

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_sizeHMAC 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, int 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, int 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

evp(3)

STANDARDS

RFC 2104

HISTORY

HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final(), and HMAC_cleanup() are available since SSLeay 0.9.0.
HMAC_CTX_init(), HMAC_Init_ex(), and HMAC_CTX_cleanup() are available since OpenSSL 0.9.7.
HMAC_CTX_new(), HMAC_CTX_reset(), HMAC_CTX_free(), and HMAC_CTX_get_md() first appeared in OpenSSL 1.1.0.
HMAC_Init_ex(), HMAC_Update(), and HMAC_Final() did not return values in versions of OpenSSL before 1.0.0.
February 18, 2018 OpenBSD-current