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