xref: /netbsd-src/crypto/external/bsd/openssl.old/dist/doc/man3/HMAC.pod (revision 4724848cf0da353df257f730694b7882798e5daf)
1*4724848cSchristos=pod
2*4724848cSchristos
3*4724848cSchristos=head1 NAME
4*4724848cSchristos
5*4724848cSchristosHMAC,
6*4724848cSchristosHMAC_CTX_new,
7*4724848cSchristosHMAC_CTX_reset,
8*4724848cSchristosHMAC_CTX_free,
9*4724848cSchristosHMAC_Init,
10*4724848cSchristosHMAC_Init_ex,
11*4724848cSchristosHMAC_Update,
12*4724848cSchristosHMAC_Final,
13*4724848cSchristosHMAC_CTX_copy,
14*4724848cSchristosHMAC_CTX_set_flags,
15*4724848cSchristosHMAC_CTX_get_md,
16*4724848cSchristosHMAC_size
17*4724848cSchristos- HMAC message authentication code
18*4724848cSchristos
19*4724848cSchristos=head1 SYNOPSIS
20*4724848cSchristos
21*4724848cSchristos #include <openssl/hmac.h>
22*4724848cSchristos
23*4724848cSchristos unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
24*4724848cSchristos                     int key_len, const unsigned char *d, size_t n,
25*4724848cSchristos                     unsigned char *md, unsigned int *md_len);
26*4724848cSchristos
27*4724848cSchristos HMAC_CTX *HMAC_CTX_new(void);
28*4724848cSchristos int HMAC_CTX_reset(HMAC_CTX *ctx);
29*4724848cSchristos
30*4724848cSchristos int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
31*4724848cSchristos                  const EVP_MD *md, ENGINE *impl);
32*4724848cSchristos int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len);
33*4724848cSchristos int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
34*4724848cSchristos
35*4724848cSchristos void HMAC_CTX_free(HMAC_CTX *ctx);
36*4724848cSchristos
37*4724848cSchristos int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
38*4724848cSchristos void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
39*4724848cSchristos const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
40*4724848cSchristos
41*4724848cSchristos size_t HMAC_size(const HMAC_CTX *e);
42*4724848cSchristos
43*4724848cSchristosDeprecated:
44*4724848cSchristos
45*4724848cSchristos #if OPENSSL_API_COMPAT < 0x10100000L
46*4724848cSchristos int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
47*4724848cSchristos               const EVP_MD *md);
48*4724848cSchristos #endif
49*4724848cSchristos
50*4724848cSchristos=head1 DESCRIPTION
51*4724848cSchristos
52*4724848cSchristosHMAC is a MAC (message authentication code), i.e. a keyed hash
53*4724848cSchristosfunction used for message authentication, which is based on a hash
54*4724848cSchristosfunction.
55*4724848cSchristos
56*4724848cSchristosHMAC() computes the message authentication code of the B<n> bytes at
57*4724848cSchristosB<d> using the hash function B<evp_md> and the key B<key> which is
58*4724848cSchristosB<key_len> bytes long.
59*4724848cSchristos
60*4724848cSchristosIt places the result in B<md> (which must have space for the output of
61*4724848cSchristosthe hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes).
62*4724848cSchristosIf B<md> is NULL, the digest is placed in a static array.  The size of
63*4724848cSchristosthe output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL
64*4724848cSchristosvalue for B<md>  to use the static array is not thread safe.
65*4724848cSchristos
66*4724848cSchristosB<evp_md> is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does
67*4724848cSchristosnot support variable output length digests such as EVP_shake128() and
68*4724848cSchristosEVP_shake256().
69*4724848cSchristos
70*4724848cSchristosHMAC_CTX_new() creates a new HMAC_CTX in heap memory.
71*4724848cSchristos
72*4724848cSchristosHMAC_CTX_reset() zeros an existing B<HMAC_CTX> and associated
73*4724848cSchristosresources, making it suitable for new computations as if it was newly
74*4724848cSchristoscreated with HMAC_CTX_new().
75*4724848cSchristos
76*4724848cSchristosHMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>,
77*4724848cSchristosreleases any associated resources and finally frees the B<HMAC_CTX>
78*4724848cSchristositself.
79*4724848cSchristos
80*4724848cSchristosThe following functions may be used if the message is not completely
81*4724848cSchristosstored in memory:
82*4724848cSchristos
83*4724848cSchristosHMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
84*4724848cSchristosfunction B<evp_md> and key B<key>. If both are NULL, or if B<key> is NULL
85*4724848cSchristosand B<evp_md> is the same as the previous call, then the
86*4724848cSchristosexisting key is
87*4724848cSchristosreused. B<ctx> must have been created with HMAC_CTX_new() before the first use
88*4724848cSchristosof an B<HMAC_CTX> in this function.
89*4724848cSchristos
90*4724848cSchristosIf HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
91*4724848cSchristossame as the previous digest used by B<ctx> then an error is returned
92*4724848cSchristosbecause reuse of an existing key with a different digest is not supported.
93*4724848cSchristos
94*4724848cSchristosHMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
95*4724848cSchristosfunction B<evp_md> and the key B<key> which is B<key_len> bytes
96*4724848cSchristoslong.
97*4724848cSchristos
98*4724848cSchristosHMAC_Update() can be called repeatedly with chunks of the message to
99*4724848cSchristosbe authenticated (B<len> bytes at B<data>).
100*4724848cSchristos
101*4724848cSchristosHMAC_Final() places the message authentication code in B<md>, which
102*4724848cSchristosmust have space for the hash function output.
103*4724848cSchristos
104*4724848cSchristosHMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>.
105*4724848cSchristos
106*4724848cSchristosHMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs.
107*4724848cSchristosThese flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>.
108*4724848cSchristos
109*4724848cSchristosHMAC_CTX_get_md() returns the EVP_MD that has previously been set for the
110*4724848cSchristossupplied HMAC_CTX.
111*4724848cSchristos
112*4724848cSchristosHMAC_size() returns the length in bytes of the underlying hash function output.
113*4724848cSchristos
114*4724848cSchristos=head1 RETURN VALUES
115*4724848cSchristos
116*4724848cSchristosHMAC() returns a pointer to the message authentication code or NULL if
117*4724848cSchristosan error occurred.
118*4724848cSchristos
119*4724848cSchristosHMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or
120*4724848cSchristosB<NULL> if an error occurred.
121*4724848cSchristos
122*4724848cSchristosHMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and
123*4724848cSchristosHMAC_CTX_copy() return 1 for success or 0 if an error occurred.
124*4724848cSchristos
125*4724848cSchristosHMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or
126*4724848cSchristosNULL if no EVP_MD has been set.
127*4724848cSchristos
128*4724848cSchristosHMAC_size() returns the length in bytes of the underlying hash function output
129*4724848cSchristosor zero on error.
130*4724848cSchristos
131*4724848cSchristos=head1 CONFORMING TO
132*4724848cSchristos
133*4724848cSchristosRFC 2104
134*4724848cSchristos
135*4724848cSchristos=head1 SEE ALSO
136*4724848cSchristos
137*4724848cSchristosL<SHA1(3)>, L<evp(7)>
138*4724848cSchristos
139*4724848cSchristos=head1 HISTORY
140*4724848cSchristos
141*4724848cSchristosHMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL 1.1.0.
142*4724848cSchristos
143*4724848cSchristosHMAC_CTX_cleanup() existed in OpenSSL before version 1.1.0.
144*4724848cSchristos
145*4724848cSchristosHMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL 1.1.0.
146*4724848cSchristos
147*4724848cSchristosHMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in
148*4724848cSchristosOpenSSL before version 1.0.0.
149*4724848cSchristos
150*4724848cSchristos=head1 COPYRIGHT
151*4724848cSchristos
152*4724848cSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
153*4724848cSchristos
154*4724848cSchristosLicensed under the OpenSSL license (the "License").  You may not use
155*4724848cSchristosthis file except in compliance with the License.  You can obtain a copy
156*4724848cSchristosin the file LICENSE in the source distribution or at
157*4724848cSchristosL<https://www.openssl.org/source/license.html>.
158*4724848cSchristos
159*4724848cSchristos=cut
160