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 82=head1 NOTES 83 84A context for X942KDF can be obtained by calling: 85 86 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); 87 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 88 89The output length of an X942KDF is specified via the I<keylen> 90parameter to the L<EVP_KDF_derive(3)> function. 91 92=head1 EXAMPLES 93 94This example derives 24 bytes, with the secret key "secret" and random user 95keying material: 96 97 EVP_KDF_CTX *kctx; 98 EVP_KDF_CTX *kctx; 99 unsigned char out[192/8]; 100 unsignred char ukm[64]; 101 OSSL_PARAM params[5], *p = params; 102 103 if (RAND_bytes(ukm, sizeof(ukm)) <= 0) 104 error("RAND_bytes"); 105 106 kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); 107 if (kctx == NULL) 108 error("EVP_KDF_fetch"); 109 kctx = EVP_KDF_CTX_new(kdf); 110 EVP_KDF_free(kdf); 111 if (kctx == NULL) 112 error("EVP_KDF_CTX_new"); 113 114 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0); 115 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 116 "secret", (size_t)6); 117 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); 118 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES-256-WRAP, 0); 119 *p = OSSL_PARAM_construct_end(); 120 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 121 error("EVP_KDF_derive"); 122 123 EVP_KDF_CTX_free(kctx); 124 125=head1 CONFORMING TO 126 127ANS1 X9.42-2003 128RFC 2631 129 130=head1 SEE ALSO 131 132L<EVP_KDF(3)>, 133L<EVP_KDF_CTX_new(3)>, 134L<EVP_KDF_CTX_free(3)>, 135L<EVP_KDF_CTX_set_params(3)>, 136L<EVP_KDF_CTX_get_kdf_size(3)>, 137L<EVP_KDF_derive(3)>, 138L<EVP_KDF(3)/PARAMETERS> 139 140=head1 HISTORY 141 142This functionality was added in OpenSSL 3.0. 143 144=head1 COPYRIGHT 145 146Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. 147 148Licensed under the Apache License 2.0 (the "License"). You may not use 149this file except in compliance with the License. You can obtain a copy 150in the file LICENSE in the source distribution or at 151L<https://www.openssl.org/source/license.html>. 152 153=cut 154