]>
Commit | Line | Data |
---|---|---|
ccd7115a P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-X942 - The X9.42-2001 asn1 EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | The EVP_KDF-X942 algorithm implements the key derivation function (X942KDF). | |
10 | X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to | |
11 | derive a key using input such as a shared secret key and other info. The other | |
12 | info is DER encoded data that contains a 32 bit counter. | |
13 | ||
14 | =head2 Identity | |
15 | ||
16 | "X942KDF" is the name for this implementation; it | |
17 | can be used with the EVP_KDF_fetch() function. | |
18 | ||
19 | =head2 Supported parameters | |
20 | ||
21 | The supported parameters are: | |
22 | ||
23 | =over 4 | |
24 | ||
25 | =item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> | |
26 | ||
27 | =item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> | |
28 | ||
29 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. | |
30 | ||
31 | =item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> | |
32 | ||
33 | The shared secret used for key derivation. This parameter sets the secret. | |
34 | ||
35 | =item B<OSSL_KDF_PARAM_UKM> ("ukm") <octet string> | |
36 | ||
37 | This parameter is an optional random string that is provided | |
38 | by the sender called "partyAInfo". | |
39 | In CMS this is the user keying material. | |
40 | ||
41 | =item B<OSSL_KDF_PARAM_CEK_ALG> ("cekalg") <UTF8 string> | |
42 | ||
43 | This parameter sets the CEK wrapping algorithm name. | |
44 | ||
45 | =back | |
46 | ||
47 | =head1 NOTES | |
48 | ||
49 | A context for X942KDF can be obtained by calling: | |
50 | ||
51 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); | |
52 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); | |
53 | ||
54 | The output length of an X942KDF is specified via the C<keylen> | |
55 | parameter to the L<EVP_KDF-derive(3)> function. | |
56 | ||
57 | =head1 EXAMPLES | |
58 | ||
59 | This example derives 24 bytes, with the secret key "secret" and a random user | |
60 | keying material: | |
61 | ||
62 | EVP_KDF_CTX *kctx; | |
63 | EVP_KDF_CTX *kctx; | |
64 | unsigned char out[192/8]; | |
65 | unsignred char ukm[64]; | |
66 | OSSL_PARAM params[5], *p = params; | |
67 | ||
68 | if (RAND_bytes(ukm, sizeof(ukm)) <= 0) | |
69 | error("RAND_bytes"); | |
70 | ||
71 | kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); | |
72 | if (kctx == NULL) | |
73 | error("EVP_KDF_fetch"); | |
74 | kctx = EVP_KDF_CTX_new(kdf); | |
75 | if (kctx == NULL) | |
76 | error("EVP_KDF_CTX_new"); | |
77 | EVP_KDF_free(kdf); | |
78 | ||
79 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
80 | SN_sha256, strlen(SN_sha256)); | |
81 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, | |
82 | "secret", (size_t)6); | |
83 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); | |
84 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, | |
85 | SN_id_smime_alg_CMS3DESwrap, | |
86 | strlen(SN_id_smime_alg_CMS3DESwrap)); | |
87 | *p = OSSL_PARAM_construct_end(); | |
a218770d P |
88 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) |
89 | error("EVP_KDF_CTX_set_params"); | |
ccd7115a P |
90 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) |
91 | error("EVP_KDF_derive"); | |
92 | ||
93 | EVP_KDF_CTX_free(kctx); | |
94 | ||
95 | =head1 CONFORMING TO | |
96 | ||
97 | RFC 2631 | |
98 | ||
99 | =head1 SEE ALSO | |
100 | ||
101 | L<EVP_KDF>, | |
102 | L<EVP_KDF-CTX_new_id(3)>, | |
103 | L<EVP_KDF-CTX_free(3)>, | |
104 | L<EVP_KDF-ctrl(3)>, | |
105 | L<EVP_KDF-size(3)>, | |
106 | L<EVP_KDF-derive(3)>, | |
107 | L<EVP_KDF(3)/PARAMETERS> | |
108 | ||
109 | =head1 HISTORY | |
110 | ||
111 | This functionality was added to OpenSSL 3.0. | |
112 | ||
113 | =head1 COPYRIGHT | |
114 | ||
115 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
116 | ||
117 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
118 | this file except in compliance with the License. You can obtain a copy | |
119 | in the file LICENSE in the source distribution or at | |
120 | L<https://www.openssl.org/source/license.html>. | |
121 | ||
122 | =cut |