secure/lib/libcrypto/man/HMAC.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "HMAC 3"
 132 .TH HMAC 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/hmac.h>
 143 \&
 144 \& unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
 145 \&                     int key_len, const unsigned char *d, int n,
 146 \&                     unsigned char *md, unsigned int *md_len);
 147 \&
 148 \& HMAC_CTX *HMAC_CTX_new(void);
 149 \& int HMAC_CTX_reset(HMAC_CTX *ctx);
 150 \&
 151 \& int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
 152 \&                  const EVP_MD *md, ENGINE *impl);
 153 \& int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
 154 \& int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
 155 \&
 156 \& void HMAC_CTX_free(HMAC_CTX *ctx);
 157 \&
 158 \& int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
 159 \& void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
 160 \& const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
 161 \&
 162 \& size_t HMAC_size(const HMAC_CTX *e);
 163 .Ve
 164 .PP
 165 Deprecated:
 166 .PP
 167 .Vb 4
 168 \& #if OPENSSL_API_COMPAT < 0x10100000L
 169 \& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
 170 \&               const EVP_MD *md);
 171 \& #endif
 172 .Ve
 173 .SH "DESCRIPTION"
 174 .IX Header "DESCRIPTION"
 175 \&\s-1HMAC\s0 is a \s-1MAC\s0 (message authentication code), i.e. a keyed hash
 176 function used for message authentication, which is based on a hash
 177 function.
 178 .PP
 179 \&\s-1\fIHMAC\s0()\fR computes the message authentication code of the \fBn\fR bytes at
 180 \&\fBd\fR using the hash function \fBevp_md\fR and the key \fBkey\fR which is
 181 \&\fBkey_len\fR bytes long.
 182 .PP
 183 It places the result in \fBmd\fR (which must have space for the output of
 184 the hash function, which is no more than \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes).
 185 If \fBmd\fR is \s-1NULL,\s0 the digest is placed in a static array.  The size of
 186 the output is placed in \fBmd_len\fR, unless it is \fB\s-1NULL\s0\fR. Note: passing a \s-1NULL\s0
 187 value for \fBmd\fR  to use the static array is not thread safe.
 188 .PP
 189 \&\fBevp_md\fR can be \fIEVP_sha1()\fR, \fIEVP_ripemd160()\fR etc.
 190 .PP
 191 \&\fIHMAC_CTX_new()\fR creates a new \s-1HMAC_CTX\s0 in heap memory.
 192 .PP
 193 \&\fIHMAC_CTX_reset()\fR zeroes an existing \fB\s-1HMAC_CTX\s0\fR and associated
 194 resources, making it suitable for new computations as if it was newly
 195 created with \fIHMAC_CTX_new()\fR.
 196 .PP
 197 \&\fIHMAC_CTX_free()\fR erases the key and other data from the \fB\s-1HMAC_CTX\s0\fR,
 198 releases any associated resources and finally frees the \fB\s-1HMAC_CTX\s0\fR
 199 itself.
 200 .PP
 201 The following functions may be used if the message is not completely
 202 stored in memory:
 203 .PP
 204 \&\fIHMAC_Init_ex()\fR initializes or reuses a \fB\s-1HMAC_CTX\s0\fR structure to use the hash
 205 function \fBevp_md\fR and key \fBkey\fR. If both are \s-1NULL,\s0 or if \fBkey\fR is \s-1NULL\s0
 206 and \fBevp_md\fR is the same as the previous call, then the
 207 existing key is
 208 reused. \fBctx\fR must have been created with \fIHMAC_CTX_new()\fR before the first use
 209 of an \fB\s-1HMAC_CTX\s0\fR in this function.
 210 .PP
 211 If \fIHMAC_Init_ex()\fR is called with \fBkey\fR \s-1NULL\s0 and \fBevp_md\fR is not the
 212 same as the previous digest used by \fBctx\fR then an error is returned
 213 because reuse of an existing key with a different digest is not supported.
 214 .PP
 215 \&\fIHMAC_Init()\fR initializes a \fB\s-1HMAC_CTX\s0\fR structure to use the hash
 216 function \fBevp_md\fR and the key \fBkey\fR which is \fBkey_len\fR bytes
 217 long.
 218 .PP
 219 \&\fIHMAC_Update()\fR can be called repeatedly with chunks of the message to
 220 be authenticated (\fBlen\fR bytes at \fBdata\fR).
 221 .PP
 222 \&\fIHMAC_Final()\fR places the message authentication code in \fBmd\fR, which
 223 must have space for the hash function output.
 224 .PP
 225 \&\fIHMAC_CTX_copy()\fR copies all of the internal state from \fBsctx\fR into \fBdctx\fR.
 226 .PP
 227 \&\fIHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs.
 228 These flags have the same meaning as for \fIEVP_MD_CTX_set_flags\fR\|(3).
 229 .PP
 230 \&\fIHMAC_CTX_get_md()\fR returns the \s-1EVP_MD\s0 that has previously been set for the
 231 supplied \s-1HMAC_CTX.\s0
 232 .PP
 233 \&\fIHMAC_size()\fR returns the length in bytes of the underlying hash function output.
 234 .SH "RETURN VALUES"
 235 .IX Header "RETURN VALUES"
 236 \&\s-1\fIHMAC\s0()\fR returns a pointer to the message authentication code or \s-1NULL\s0 if
 237 an error occurred.
 238 .PP
 239 \&\fIHMAC_CTX_new()\fR returns a pointer to a new \fB\s-1HMAC_CTX\s0\fR on success or
 240 \&\fB\s-1NULL\s0\fR if an error occurred.
 241 .PP
 242 \&\fIHMAC_CTX_reset()\fR, \fIHMAC_Init_ex()\fR, \fIHMAC_Update()\fR, \fIHMAC_Final()\fR and
 243 \&\fIHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred.
 244 .PP
 245 \&\fIHMAC_CTX_get_md()\fR return the \s-1EVP_MD\s0 previously set for the supplied \s-1HMAC_CTX\s0 or
 246 \&\s-1NULL\s0 if no \s-1EVP_MD\s0 has been set.
 247 .PP
 248 \&\fIHMAC_size()\fR returns the length in bytes of the underlying hash function output
 249 or zero on error.
 250 .SH "CONFORMING TO"
 251 .IX Header "CONFORMING TO"
 252 \&\s-1RFC 2104\s0
 253 .SH "SEE ALSO"
 254 .IX Header "SEE ALSO"
 255 \&\s-1\fISHA1\s0\fR\|(3), \fIevp\fR\|(7)
 256 .SH "HISTORY"
 257 .IX Header "HISTORY"
 258 \&\fIHMAC_CTX_init()\fR was replaced with \fIHMAC_CTX_reset()\fR in OpenSSL 1.1.0.
 259 .PP
 260 \&\fIHMAC_CTX_cleanup()\fR existed in OpenSSL before version 1.1.0.
 261 .PP
 262 \&\fIHMAC_CTX_new()\fR, \fIHMAC_CTX_free()\fR and \fIHMAC_CTX_get_md()\fR are new in OpenSSL 1.1.0.
 263 .PP
 264 \&\fIHMAC_Init_ex()\fR, \fIHMAC_Update()\fR and \fIHMAC_Final()\fR did not return values in
 265 OpenSSL before version 1.0.0.
 266 .SH "COPYRIGHT"
 267 .IX Header "COPYRIGHT"
 268 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 269 .PP
 270 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 271 this file except in compliance with the License.  You can obtain a copy
 272 in the file \s-1LICENSE\s0 in the source distribution or at
 273 <https://www.openssl.org/source/license.html>.