#use wml::openssl-macros area=docs page=hmac

<title>Documents, hmac(3)</title>

<h1>hmac(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#CONFORMING_TO">CONFORMING TO</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message
authentication code

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/hmac.h&gt;
</PRE>
<PRE> 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);
</PRE>
<PRE> void HMAC_CTX_init(HMAC_CTX *ctx);
</PRE>
<PRE> int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
               const EVP_MD *md);
 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);
</PRE>
<PRE> void HMAC_CTX_cleanup(HMAC_CTX *ctx);
 void HMAC_cleanup(HMAC_CTX *ctx);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
HMAC is a MAC (message authentication code), i.e. a keyed hash function
used for message authentication, which is based on a hash function.

</P>
<P>
<CODE>HMAC()</CODE> computes the message authentication code of the <STRONG>n</STRONG> bytes at
<STRONG>d</STRONG> using the hash function <STRONG>evp_md</STRONG> and the key <STRONG>key</STRONG> which is
<STRONG>key_len</STRONG> bytes long.

</P>
<P>
It places the result in <STRONG>md</STRONG> (which must have space for the output of the hash function, which is no
more than <STRONG>EVP_MAX_MD_SIZE</STRONG> bytes). If <STRONG>md</STRONG> is NULL, the digest is placed in a static array. The size of the output is
placed in <STRONG>md_len</STRONG>, unless it is <STRONG>NULL</STRONG>.

</P>
<P>
<STRONG>evp_md</STRONG> can be <CODE>EVP_sha1(),</CODE> <CODE>EVP_ripemd160()</CODE> etc.

</P>
<P>
<CODE>HMAC_CTX_init()</CODE> initialises a <STRONG>HMAC_CTX</STRONG> before first use. It must be called.

</P>
<P>
<CODE>HMAC_CTX_cleanup()</CODE> erases the key and other data from the <STRONG>HMAC_CTX</STRONG>
and releases any associated resources. It must be called when an
<STRONG>HMAC_CTX</STRONG> is no longer required.

</P>
<P>
<CODE>HMAC_cleanup()</CODE> is an alias for <CODE>HMAC_CTX_cleanup()</CODE>
included for back compatibility with 0.9.6b, it is deprecated.

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

</P>
<P>
<CODE>HMAC_Init()</CODE> initializes a <STRONG>HMAC_CTX</STRONG> structure to use the hash function <STRONG>evp_md</STRONG> and the key <STRONG>key</STRONG> which is <STRONG>key_len</STRONG> bytes long. It is deprecated and only included for backward compatibility
with OpenSSL 0.9.6b.

</P>
<P>
<CODE>HMAC_Init_ex()</CODE> initializes or reuses a <STRONG>HMAC_CTX</STRONG> structure to use the function <STRONG>evp_md</STRONG> and key <STRONG>key</STRONG>. Either can be NULL, in which case the existing one will be reused.
<CODE>HMAC_CTX_init()</CODE> must have been called before the first use of
an <STRONG>HMAC_CTX</STRONG> in this function. <STRONG>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</STRONG>.

</P>
<P>
<CODE>HMAC_Update()</CODE> can be called repeatedly with chunks of the
message to be authenticated (<STRONG>len</STRONG> bytes at <STRONG>data</STRONG>).

</P>
<P>
<CODE>HMAC_Final()</CODE> places the message authentication code in <STRONG>md</STRONG>, which must have space for the hash function output.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>HMAC()</CODE> returns a pointer to the message authentication code or
NULL if an error occurred.

</P>
<P>
<CODE>HMAC_Init_ex(),</CODE> <CODE>HMAC_Update()</CODE> and
<CODE>HMAC_Final()</CODE> return 1 for success or 0 if an error occurred.

</P>
<P>
<CODE>HMAC_CTX_init()</CODE> and <CODE>HMAC_CTX_cleanup()</CODE> do not
return values.

</P>
<P>
<HR>
<H1><A NAME="CONFORMING_TO">CONFORMING TO</A></H1>
<P>
RFC 2104

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/sha.html#">sha(3)</A>, <A HREF="../crypto/evp.html#">evp(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>HMAC(),</CODE> <CODE>HMAC_Init(),</CODE> <CODE>HMAC_Update(),</CODE>
<CODE>HMAC_Final()</CODE> and <CODE>HMAC_cleanup()</CODE> are available
since SSLeay 0.9.0.

</P>
<P>
<CODE>HMAC_CTX_init(),</CODE> <CODE>HMAC_Init_ex()</CODE> and
<CODE>HMAC_CTX_cleanup()</CODE> are available since OpenSSL 0.9.7.

</P>
<P>
<CODE>HMAC_Init_ex(),</CODE> <CODE>HMAC_Update()</CODE> and
<CODE>HMAC_Final()</CODE> did not return values in versions of OpenSSL
before 1.0.0.

</P>
:}