secure/lib/libcrypto/man/man3/HMAC.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "HMAC 3"
 136 .TH HMAC 3 "2020-03-31" "1.1.1f" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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_size \&\- HMAC message authentication code
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/hmac.h>
 147 \&
 148 \& unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
 149 \&                     int key_len, const unsigned char *d, int n,
 150 \&                     unsigned char *md, unsigned int *md_len);
 151 \&
 152 \& HMAC_CTX *HMAC_CTX_new(void);
 153 \& int HMAC_CTX_reset(HMAC_CTX *ctx);
 154 \&
 155 \& int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
 156 \&                  const EVP_MD *md, ENGINE *impl);
 157 \& int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
 158 \& int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
 159 \&
 160 \& void HMAC_CTX_free(HMAC_CTX *ctx);
 161 \&
 162 \& int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
 163 \& void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
 164 \& const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
 165 \&
 166 \& size_t HMAC_size(const HMAC_CTX *e);
 167 .Ve
 168 .PP
 169 Deprecated:
 170 .PP
 171 .Vb 4
 172 \& #if OPENSSL_API_COMPAT < 0x10100000L
 173 \& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
 174 \&               const EVP_MD *md);
 175 \& #endif
 176 .Ve
 177 .SH "DESCRIPTION"
 178 .IX Header "DESCRIPTION"
 179 \&\s-1HMAC\s0 is a \s-1MAC\s0 (message authentication code), i.e. a keyed hash
 180 function used for message authentication, which is based on a hash
 181 function.
 182 .PP
 183 \&\s-1\fBHMAC\s0()\fR computes the message authentication code of the \fBn\fR bytes at
 184 \&\fBd\fR using the hash function \fBevp_md\fR and the key \fBkey\fR which is
 185 \&\fBkey_len\fR bytes long.
 186 .PP
 187 It places the result in \fBmd\fR (which must have space for the output of
 188 the hash function, which is no more than \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes).
 189 If \fBmd\fR is \s-1NULL,\s0 the digest is placed in a static array.  The size of
 190 the output is placed in \fBmd_len\fR, unless it is \fB\s-1NULL\s0\fR. Note: passing a \s-1NULL\s0
 191 value for \fBmd\fR  to use the static array is not thread safe.
 192 .PP
 193 \&\fBevp_md\fR is a message digest such as \fBEVP_sha1()\fR, \fBEVP_ripemd160()\fR etc. \s-1HMAC\s0 does
 194 not support variable output length digests such as \fBEVP_shake128()\fR and
 195 \&\fBEVP_shake256()\fR.
 196 .PP
 197 \&\fBHMAC_CTX_new()\fR creates a new \s-1HMAC_CTX\s0 in heap memory.
 198 .PP
 199 \&\fBHMAC_CTX_reset()\fR zeroes an existing \fB\s-1HMAC_CTX\s0\fR and associated
 200 resources, making it suitable for new computations as if it was newly
 201 created with \fBHMAC_CTX_new()\fR.
 202 .PP
 203 \&\fBHMAC_CTX_free()\fR erases the key and other data from the \fB\s-1HMAC_CTX\s0\fR,
 204 releases any associated resources and finally frees the \fB\s-1HMAC_CTX\s0\fR
 205 itself.
 206 .PP
 207 The following functions may be used if the message is not completely
 208 stored in memory:
 209 .PP
 210 \&\fBHMAC_Init_ex()\fR initializes or reuses a \fB\s-1HMAC_CTX\s0\fR structure to use the hash
 211 function \fBevp_md\fR and key \fBkey\fR. If both are \s-1NULL,\s0 or if \fBkey\fR is \s-1NULL\s0
 212 and \fBevp_md\fR is the same as the previous call, then the
 213 existing key is
 214 reused. \fBctx\fR must have been created with \fBHMAC_CTX_new()\fR before the first use
 215 of an \fB\s-1HMAC_CTX\s0\fR in this function.
 216 .PP
 217 If \fBHMAC_Init_ex()\fR is called with \fBkey\fR \s-1NULL\s0 and \fBevp_md\fR is not the
 218 same as the previous digest used by \fBctx\fR then an error is returned
 219 because reuse of an existing key with a different digest is not supported.
 220 .PP
 221 \&\fBHMAC_Init()\fR initializes a \fB\s-1HMAC_CTX\s0\fR structure to use the hash
 222 function \fBevp_md\fR and the key \fBkey\fR which is \fBkey_len\fR bytes
 223 long.
 224 .PP
 225 \&\fBHMAC_Update()\fR can be called repeatedly with chunks of the message to
 226 be authenticated (\fBlen\fR bytes at \fBdata\fR).
 227 .PP
 228 \&\fBHMAC_Final()\fR places the message authentication code in \fBmd\fR, which
 229 must have space for the hash function output.
 230 .PP
 231 \&\fBHMAC_CTX_copy()\fR copies all of the internal state from \fBsctx\fR into \fBdctx\fR.
 232 .PP
 233 \&\fBHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs.
 234 These flags have the same meaning as for \fBEVP_MD_CTX_set_flags\fR\|(3).
 235 .PP
 236 \&\fBHMAC_CTX_get_md()\fR returns the \s-1EVP_MD\s0 that has previously been set for the
 237 supplied \s-1HMAC_CTX.\s0
 238 .PP
 239 \&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output.
 240 .SH "RETURN VALUES"
 241 .IX Header "RETURN VALUES"
 242 \&\s-1\fBHMAC\s0()\fR returns a pointer to the message authentication code or \s-1NULL\s0 if
 243 an error occurred.
 244 .PP
 245 \&\fBHMAC_CTX_new()\fR returns a pointer to a new \fB\s-1HMAC_CTX\s0\fR on success or
 246 \&\fB\s-1NULL\s0\fR if an error occurred.
 247 .PP
 248 \&\fBHMAC_CTX_reset()\fR, \fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR and
 249 \&\fBHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred.
 250 .PP
 251 \&\fBHMAC_CTX_get_md()\fR return the \s-1EVP_MD\s0 previously set for the supplied \s-1HMAC_CTX\s0 or
 252 \&\s-1NULL\s0 if no \s-1EVP_MD\s0 has been set.
 253 .PP
 254 \&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output
 255 or zero on error.
 256 .SH "CONFORMING TO"
 257 .IX Header "CONFORMING TO"
 258 \&\s-1RFC 2104\s0
 259 .SH "SEE ALSO"
 260 .IX Header "SEE ALSO"
 261 \&\s-1\fBSHA1\s0\fR\|(3), \fBevp\fR\|(7)
 262 .SH "HISTORY"
 263 .IX Header "HISTORY"
 264 \&\fBHMAC_CTX_init()\fR was replaced with \fBHMAC_CTX_reset()\fR in OpenSSL 1.1.0.
 265 .PP
 266 \&\fBHMAC_CTX_cleanup()\fR existed in OpenSSL before version 1.1.0.
 267 .PP
 268 \&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR and \fBHMAC_CTX_get_md()\fR are new in OpenSSL 1.1.0.
 269 .PP
 270 \&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR and \fBHMAC_Final()\fR did not return values in
 271 OpenSSL before version 1.0.0.
 272 .SH "COPYRIGHT"
 273 .IX Header "COPYRIGHT"
 274 Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
 275 .PP
 276 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 277 this file except in compliance with the License.  You can obtain a copy
 278 in the file \s-1LICENSE\s0 in the source distribution or at
 279 <https://www.openssl.org/source/license.html>.