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