Debian Codegraph @

upstream/debian-unstable/man7/EVP_KDF-X942-ASN1.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_KDF-X942-ASN1 7SSL"
58 .TH EVP_KDF-X942-ASN1 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_KDF\-X942\-ASN1 \- The X9.42\-2003 asn1 EVP_KDF implementation
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 The EVP_KDF\-X942\-ASN1 algorithm implements the key derivation function
68 X942KDF\-ASN1. It is used by DH KeyAgreement, to derive a key using input such as
69 a shared secret key and other info. The other info is DER encoded data that
70 contains a 32 bit counter as well as optional fields for "partyu-info",
71 "partyv-info", "supp-pubinfo" and "supp-privinfo".
72 This kdf is used by Cryptographic Message Syntax (CMS).
73 .PP
74 The output is considered to be keying material.
75 .SS Identity
76 .IX Subsection "Identity"
77 "X942KDF\-ASN1" or "X942KDF" is the name for this implementation; it
78 can be used with the \fBEVP_KDF_fetch()\fR function.
79 .SS "Supported parameters"
80 .IX Subsection "Supported parameters"
81 The supported parameters are:
82 .IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) <UTF8 string>" 4
83 .IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>"
84 .PD 0
85 .IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) <UTF8 string>" 4
86 .IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>"
87 .PD
88 These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3).
89 .IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) <octet string>" 4
90 .IX Item """secret"" (OSSL_KDF_PARAM_SECRET) <octet string>"
91 The shared secret used for key derivation. This parameter sets the secret.
92 .IP """acvp-info"" (\fBOSSL_KDF_PARAM_X942_ACVPINFO\fR) <octet string>" 4
93 .IX Item """acvp-info"" (OSSL_KDF_PARAM_X942_ACVPINFO) <octet string>"
94 This value should not be used in production and should only be used for ACVP
95 testing. It is an optional octet string containing a combined DER encoded blob
96 of any of the optional fields related to "partyu-info", "partyv-info",
97 "supp-pubinfo" and "supp-privinfo". If it is specified then none of these other
98 fields should be used.
99 .IP """partyu-info"" (\fBOSSL_KDF_PARAM_X942_PARTYUINFO\fR) <octet string>" 4
100 .IX Item """partyu-info"" (OSSL_KDF_PARAM_X942_PARTYUINFO) <octet string>"
101 An optional octet string containing public info contributed by the initiator.
102 .IP """ukm"" (\fBOSSL_KDF_PARAM_UKM\fR) <octet string>" 4
103 .IX Item """ukm"" (OSSL_KDF_PARAM_UKM) <octet string>"
104 An alias for "partyu-info".
105 In CMS this is the user keying material.
106 .IP """partyv-info"" (\fBOSSL_KDF_PARAM_X942_PARTYVINFO\fR) <octet string>" 4
107 .IX Item """partyv-info"" (OSSL_KDF_PARAM_X942_PARTYVINFO) <octet string>"
108 An optional octet string containing public info contributed by the responder.
109 .IP """supp-pubinfo"" (\fBOSSL_KDF_PARAM_X942_SUPP_PUBINFO\fR) <octet string>" 4
110 .IX Item """supp-pubinfo"" (OSSL_KDF_PARAM_X942_SUPP_PUBINFO) <octet string>"
111 An optional octet string containing some additional, mutually-known public
112 information. Setting this value also sets "use-keybits" to 0.
113 .IP """use-keybits"" (\fBOSSL_KDF_PARAM_X942_USE_KEYBITS\fR) <integer>" 4
114 .IX Item """use-keybits"" (OSSL_KDF_PARAM_X942_USE_KEYBITS) <integer>"
115 The default value of 1 will use the KEK key length (in bits) as the
116 "supp-pubinfo". A value of 0 disables setting the "supp-pubinfo".
117 .IP """supp-privinfo"" (\fBOSSL_KDF_PARAM_X942_SUPP_PRIVINFO\fR) <octet string>" 4
118 .IX Item """supp-privinfo"" (OSSL_KDF_PARAM_X942_SUPP_PRIVINFO) <octet string>"
119 An optional octet string containing some additional, mutually-known private
120 information.
121 .IP """cekalg"" (\fBOSSL_KDF_PARAM_CEK_ALG\fR) <UTF8 string>" 4
122 .IX Item """cekalg"" (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string>"
123 This parameter sets the CEK wrapping algorithm name.
124 Valid values are "AES\-128\-WRAP", "AES\-192\-WRAP", "AES\-256\-WRAP" and "DES3\-WRAP".
125 .PP
126 The OpenSSL FIPS provider also supports the following parameters:
127 .IP """fips-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
128 .IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
129 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
130 This may be used after calling EVP_KDF_derive. It returns 0 if "key-check"
131 parameter is set to 0 and the check fails.
132 .IP """key-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) <integer>" 4
133 .IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>"
134 The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the
135 length of used key-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112
136 bits.
137 Setting this to zero will ignore the error and set the approved
138 "fips-indicator" to 0.
139 This option breaks FIPS compliance if it causes the approved "fips-indicator"
140 to return 0.
141 .SH NOTES
142 .IX Header "NOTES"
143 A context for X942KDF can be obtained by calling:
144 .PP
145 .Vb 2
146 \& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
147 \& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
148 .Ve
149 .PP
150 The output length of an X942KDF is specified via the \fIkeylen\fR
151 parameter to the \fBEVP_KDF_derive\fR\|(3) function.
152 .SH EXAMPLES
153 .IX Header "EXAMPLES"
154 This example derives 24 bytes, with the secret key "secret" and random user
155 keying material:
156 .PP
157 .Vb 5
158 \& EVP_KDF_CTX *kctx;
159 \& EVP_KDF_CTX *kctx;
160 \& unsigned char out[192/8];
161 \& unsignred char ukm[64];
162 \& OSSL_PARAM params[5], *p = params;
163 \&
164 \& if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
165 \& error("RAND_bytes");
166 \&
167 \& kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
168 \& if (kctx == NULL)
169 \& error("EVP_KDF_fetch");
170 \& kctx = EVP_KDF_CTX_new(kdf);
171 \& EVP_KDF_free(kdf);
172 \& if (kctx == NULL)
173 \& error("EVP_KDF_CTX_new");
174 \&
175 \& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0);
176 \& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
177 \& "secret", (size_t)6);
178 \& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm));
179 \& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES\-256\-WRAP, 0);
180 \& *p = OSSL_PARAM_construct_end();
181 \& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
182 \& error("EVP_KDF_derive");
183 \&
184 \& EVP_KDF_CTX_free(kctx);
185 .Ve
186 .SH "CONFORMING TO"
187 .IX Header "CONFORMING TO"
188 ANS1 X9.42\-2003
189 RFC 2631
190 .SH "SEE ALSO"
191 .IX Header "SEE ALSO"
192 \&\fBEVP_KDF\fR\|(3),
193 \&\fBEVP_KDF_CTX_new\fR\|(3),
194 \&\fBEVP_KDF_CTX_free\fR\|(3),
195 \&\fBEVP_KDF_CTX_set_params\fR\|(3),
196 \&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3),
197 \&\fBEVP_KDF_derive\fR\|(3),
198 "PARAMETERS" in \fBEVP_KDF\fR\|(3)
199 .SH HISTORY
200 .IX Header "HISTORY"
201 This functionality was added in OpenSSL 3.0.
202 .SH COPYRIGHT
203 .IX Header "COPYRIGHT"
204 Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved.
205 .PP
206 Licensed under the Apache License 2.0 (the "License"). You may not use
207 this file except in compliance with the License. You can obtain a copy
208 in the file LICENSE in the source distribution or at
209 <https://www.openssl.org/source/license.html>.