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