HMAC_CTX_free (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/HMAC_CTX_free.3ssl".)

NAME

HMAC, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags, HMAC_CTX_get_md - 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);

 int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
                   const EVP_MD *md, ENGINE *impl);
 int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
 int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);

 void HMAC_CTX_free(HMAC_CTX *ctx);

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

Deprecated:

 #if OPENSSL_API_COMPAT < 0x10100000L
 int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
               const EVP_MD *md);
 #endif

DESCRIPTION

is a (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

bytes). If md is the digest is placed in a static array. The size of the output is placed in md_len, unless it is . Note: passing a value for md to use the static array is not thread safe.

evp_md can be EVP_sha1(), EVP_ripemd160() etc.

HMAC_CTX_new() creates a new

in heap memory.

HMAC_CTX_reset() zeroes an existing

and associated resources, making it suitable for new computations as if it was newly created with HMAC_CTX_new().

HMAC_CTX_free() erases the key and other data from the

, releases any associated resources and finally frees the itself.

The following functions may be used if the message is not completely stored in memory:

HMAC_Init() initializes a

structure to use the hash function evp_md and the key key which is key_len bytes long. It is deprecated and only included for backward compatibility with OpenSSL 0.9.6b.

HMAC_Init_ex() initializes or reuses a

structure to use the hash function evp_md and key key. If both are (or evp_md is the same as the previous digest used by ctx and key is ) the existing key is reused. ctx must have been created with HMAC_CTX_new() before the first use of an in this function. N.B. HMAC_Init() had this undocumented behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in programs that expect it will cause them to stop working.

If HMAC_Init_ex() is called with key and evp_md is not 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_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_CTXs. These flags have the same meaning as for EVP_MD_CTX_set_flags(3).

HMAC_CTX_get_md() returns the

that has previously been set for the supplied

RETURN VALUES

() returns a pointer to the message authentication code or if an error occurred.

HMAC_CTX_new() returns a pointer to a new

on success or 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() return the

previously set for the supplied or if no has been set.

CONFORMING TO

SEE ALSO

sha(3), evp(3)

HISTORY

HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0.

HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0.

HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version 1.1.0.

HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in versions of OpenSSL before 1.0.0.

COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the ``License''). You may not use this file except in compliance with the License. You can obtain a copy in the file

in the source distribution or at <www.openssl.org/source/license.html>.