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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 "EVP_PKEY_CTX_SET_HKDF_MD 3"
 136 .TH EVP_PKEY_CTX_SET_HKDF_MD 3 "2022-05-03" "1.1.1o" "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 EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info, EVP_PKEY_CTX_hkdf_mode \- HMAC\-based Extract\-and\-Expand key derivation algorithm
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/kdf.h>
 147 \&
 148 \& int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *pctx, int mode);
 149 \&
 150 \& int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
 151 \&
 152 \& int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
 153 \&                                 int saltlen);
 154 \&
 155 \& int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,
 156 \&                                int keylen);
 157 \&
 158 \& int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,
 159 \&                                 int infolen);
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 The \s-1EVP_PKEY_HKDF\s0 algorithm implements the \s-1HKDF\s0 key derivation function.
 164 \&\s-1HKDF\s0 follows the \*(L"extract-then-expand\*(R" paradigm, where the \s-1KDF\s0 logically
 165 consists of two modules. The first stage takes the input keying material
 166 and \*(L"extracts\*(R" from it a fixed-length pseudorandom key K. The second stage
 167 \&\*(L"expands\*(R" the key K into several additional pseudorandom keys (the output
 168 of the \s-1KDF\s0).
 169 .PP
 170 \&\fBEVP_PKEY_CTX_hkdf_mode()\fR sets the mode for the \s-1HKDF\s0 operation. There are three
 171 modes that are currently defined:
 172 .IP "\s-1EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND\s0" 4
 173 .IX Item "EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND"
 174 This is the default mode. Calling \fBEVP_PKEY_derive\fR\|(3) on an \s-1EVP_PKEY_CTX\s0 set
 175 up for \s-1HKDF\s0 will perform an extract followed by an expand operation in one go.
 176 The derived key returned will be the result after the expand operation. The
 177 intermediate fixed-length pseudorandom key K is not returned.
 178 .Sp
 179 In this mode the digest, key, salt and info values must be set before a key is
 180 derived or an error occurs.
 181 .IP "\s-1EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY\s0" 4
 182 .IX Item "EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY"
 183 In this mode calling \fBEVP_PKEY_derive\fR\|(3) will just perform the extract
 184 operation. The value returned will be the intermediate fixed-length pseudorandom
 185 key K.
 186 .Sp
 187 The digest, key and salt values must be set before a key is derived or an
 188 error occurs.
 189 .IP "\s-1EVP_PKEY_HKDEF_MODE_EXPAND_ONLY\s0" 4
 190 .IX Item "EVP_PKEY_HKDEF_MODE_EXPAND_ONLY"
 191 In this mode calling \fBEVP_PKEY_derive\fR\|(3) will just perform the expand
 192 operation. The input key should be set to the intermediate fixed-length
 193 pseudorandom key K returned from a previous extract operation.
 194 .Sp
 195 The digest, key and info values must be set before a key is derived or an
 196 error occurs.
 197 .PP
 198 \&\fBEVP_PKEY_CTX_set_hkdf_md()\fR sets the message digest associated with the \s-1HKDF.\s0
 199 .PP
 200 \&\fBEVP_PKEY_CTX_set1_hkdf_salt()\fR sets the salt to \fBsaltlen\fR bytes of the
 201 buffer \fBsalt\fR. Any existing value is replaced.
 202 .PP
 203 \&\fBEVP_PKEY_CTX_set1_hkdf_key()\fR sets the key to \fBkeylen\fR bytes of the buffer
 204 \&\fBkey\fR. Any existing value is replaced.
 205 .PP
 206 \&\fBEVP_PKEY_CTX_add1_hkdf_info()\fR sets the info value to \fBinfolen\fR bytes of the
 207 buffer \fBinfo\fR. If a value is already set, it is appended to the existing
 208 value.
 209 .SH "STRING CTRLS"
 210 .IX Header "STRING CTRLS"
 211 \&\s-1HKDF\s0 also supports string based control operations via
 212 \&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3).
 213 The \fBtype\fR parameter \*(L"md\*(R" uses the supplied \fBvalue\fR as the name of the digest
 214 algorithm to use.
 215 The \fBtype\fR parameter \*(L"mode\*(R" uses the values \*(L"\s-1EXTRACT_AND_EXPAND\*(R",
 216 \&\*(L"EXTRACT_ONLY\*(R"\s0 and \*(L"\s-1EXPAND_ONLY\*(R"\s0 to determine the mode to use.
 217 The \fBtype\fR parameters \*(L"salt\*(R", \*(L"key\*(R" and \*(L"info\*(R" use the supplied \fBvalue\fR
 218 parameter as a \fBseed\fR, \fBkey\fR or \fBinfo\fR value.
 219 The names \*(L"hexsalt\*(R", \*(L"hexkey\*(R" and \*(L"hexinfo\*(R" are similar except they take a hex
 220 string which is converted to binary.
 221 .SH "NOTES"
 222 .IX Header "NOTES"
 223 All these functions are implemented as macros.
 224 .PP
 225 A context for \s-1HKDF\s0 can be obtained by calling:
 226 .PP
 227 .Vb 1
 228 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
 229 .Ve
 230 .PP
 231 The total length of the info buffer cannot exceed 1024 bytes in length: this
 232 should be more than enough for any normal use of \s-1HKDF.\s0
 233 .PP
 234 The output length of an \s-1HKDF\s0 expand operation is specified via the length
 235 parameter to the \fBEVP_PKEY_derive\fR\|(3) function.
 236 Since the \s-1HKDF\s0 output length is variable, passing a \fB\s-1NULL\s0\fR buffer as a means
 237 to obtain the requisite length is not meaningful with \s-1HKDF\s0 in any mode that
 238 performs an expand operation. Instead, the caller must allocate a buffer of the
 239 desired length, and pass that buffer to \fBEVP_PKEY_derive\fR\|(3) along with (a
 240 pointer initialized to) the desired length. Passing a \fB\s-1NULL\s0\fR buffer to obtain
 241 the length is allowed when using \s-1EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY.\s0
 242 .PP
 243 Optimised versions of \s-1HKDF\s0 can be implemented in an \s-1ENGINE.\s0
 244 .SH "RETURN VALUES"
 245 .IX Header "RETURN VALUES"
 246 All these functions return 1 for success and 0 or a negative value for failure.
 247 In particular a return value of \-2 indicates the operation is not supported by
 248 the public key algorithm.
 249 .SH "EXAMPLES"
 250 .IX Header "EXAMPLES"
 251 This example derives 10 bytes using \s-1SHA\-256\s0 with the secret key \*(L"secret\*(R",
 252 salt value \*(L"salt\*(R" and info value \*(L"label\*(R":
 253 .PP
 254 .Vb 4
 255 \& EVP_PKEY_CTX *pctx;
 256 \& unsigned char out[10];
 257 \& size_t outlen = sizeof(out);
 258 \& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
 259 \&
 260 \& if (EVP_PKEY_derive_init(pctx) <= 0)
 261 \&     /* Error */
 262 \& if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)
 263 \&     /* Error */
 264 \& if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, "salt", 4) <= 0)
 265 \&     /* Error */
 266 \& if (EVP_PKEY_CTX_set1_hkdf_key(pctx, "secret", 6) <= 0)
 267 \&     /* Error */
 268 \& if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 5) <= 0)
 269 \&     /* Error */
 270 \& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
 271 \&     /* Error */
 272 .Ve
 273 .SH "CONFORMING TO"
 274 .IX Header "CONFORMING TO"
 275 \&\s-1RFC 5869\s0
 276 .SH "SEE ALSO"
 277 .IX Header "SEE ALSO"
 278 \&\fBEVP_PKEY_CTX_new\fR\|(3),
 279 \&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3),
 280 \&\fBEVP_PKEY_derive\fR\|(3)
 281 .SH "COPYRIGHT"
 282 .IX Header "COPYRIGHT"
 283 Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved.
 284 .PP
 285 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 286 this file except in compliance with the License.  You can obtain a copy
 287 in the file \s-1LICENSE\s0 in the source distribution or at
 288 <https://www.openssl.org/source/license.html>.