1=pod 2 3=head1 NAME 4 5EVP_KDF-X942-ASN1 - The X9.42-2003 asn1 EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9The EVP_KDF-X942-ASN1 algorithm implements the key derivation function 10X942KDF-ASN1. It is used by DH KeyAgreement, to derive a key using input such as 11a shared secret key and other info. The other info is DER encoded data that 12contains a 32 bit counter as well as optional fields for "partyu-info", 13"partyv-info", "supp-pubinfo" and "supp-privinfo". 14This kdf is used by Cryptographic Message Syntax (CMS). 15 16The output is considered to be keying material. 17 18=head2 Identity 19 20"X942KDF-ASN1" or "X942KDF" is the name for this implementation; it 21can be used with the EVP_KDF_fetch() function. 22 23=head2 Supported parameters 24 25The supported parameters are: 26 27=over 4 28 29=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 30 31=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 32 33These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 34 35=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> 36 37The shared secret used for key derivation. This parameter sets the secret. 38 39=item "acvp-info" (B<OSSL_KDF_PARAM_X942_ACVPINFO>) <octet string> 40 41This value should not be used in production and should only be used for ACVP 42testing. It is an optional octet string containing a combined DER encoded blob 43of any of the optional fields related to "partyu-info", "partyv-info", 44"supp-pubinfo" and "supp-privinfo". If it is specified then none of these other 45fields should be used. 46 47=item "partyu-info" (B<OSSL_KDF_PARAM_X942_PARTYUINFO>) <octet string> 48 49An optional octet string containing public info contributed by the initiator. 50 51=item "ukm" (B<OSSL_KDF_PARAM_UKM>) <octet string> 52 53An alias for "partyu-info". 54In CMS this is the user keying material. 55 56=item "partyv-info" (B<OSSL_KDF_PARAM_X942_PARTYVINFO>) <octet string> 57 58An optional octet string containing public info contributed by the responder. 59 60=item "supp-pubinfo" (B<OSSL_KDF_PARAM_X942_SUPP_PUBINFO>) <octet string> 61 62An optional octet string containing some additional, mutually-known public 63information. Setting this value also sets "use-keybits" to 0. 64 65=item "use-keybits" (B<OSSL_KDF_PARAM_X942_USE_KEYBITS>) <integer> 66 67The default value of 1 will use the KEK key length (in bits) as the 68"supp-pubinfo". A value of 0 disables setting the "supp-pubinfo". 69 70=item "supp-privinfo" (B<OSSL_KDF_PARAM_X942_SUPP_PRIVINFO>) <octet string> 71 72An optional octet string containing some additional, mutually-known private 73information. 74 75=item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <UTF8 string> 76 77This parameter sets the CEK wrapping algorithm name. 78Valid values are "AES-128-WRAP", "AES-192-WRAP", "AES-256-WRAP" and "DES3-WRAP". 79 80=back 81 82The OpenSSL FIPS provider also supports the following parameters: 83 84=over 4 85 86=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 87 88A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 89This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" 90parameter is set to 0 and the check fails. 91 92=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 93 94The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 95length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 96bits. 97Setting this to zero will ignore the error and set the approved 98"fips-indicator" to 0. 99This option breaks FIPS compliance if it causes the approved "fips-indicator" 100to return 0. 101 102=back 103 104=head1 NOTES 105 106A context for X942KDF can be obtained by calling: 107 108 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); 109 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 110 111The output length of an X942KDF is specified via the I<keylen> 112parameter to the L<EVP_KDF_derive(3)> function. 113 114=head1 EXAMPLES 115 116This example derives 24 bytes, with the secret key "secret" and random user 117keying material: 118 119 EVP_KDF_CTX *kctx; 120 EVP_KDF_CTX *kctx; 121 unsigned char out[192/8]; 122 unsignred char ukm[64]; 123 OSSL_PARAM params[5], *p = params; 124 125 if (RAND_bytes(ukm, sizeof(ukm)) <= 0) 126 error("RAND_bytes"); 127 128 kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); 129 if (kctx == NULL) 130 error("EVP_KDF_fetch"); 131 kctx = EVP_KDF_CTX_new(kdf); 132 EVP_KDF_free(kdf); 133 if (kctx == NULL) 134 error("EVP_KDF_CTX_new"); 135 136 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0); 137 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 138 "secret", (size_t)6); 139 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); 140 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES-256-WRAP, 0); 141 *p = OSSL_PARAM_construct_end(); 142 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 143 error("EVP_KDF_derive"); 144 145 EVP_KDF_CTX_free(kctx); 146 147=head1 CONFORMING TO 148 149ANS1 X9.42-2003 150RFC 2631 151 152=head1 SEE ALSO 153 154L<EVP_KDF(3)>, 155L<EVP_KDF_CTX_new(3)>, 156L<EVP_KDF_CTX_free(3)>, 157L<EVP_KDF_CTX_set_params(3)>, 158L<EVP_KDF_CTX_get_kdf_size(3)>, 159L<EVP_KDF_derive(3)>, 160L<EVP_KDF(3)/PARAMETERS> 161 162=head1 HISTORY 163 164This functionality was added in OpenSSL 3.0. 165 166=head1 COPYRIGHT 167 168Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 169 170Licensed under the Apache License 2.0 (the "License"). You may not use 171this file except in compliance with the License. You can obtain a copy 172in the file LICENSE in the source distribution or at 173L<https://www.openssl.org/source/license.html>. 174 175=cut 176
