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