1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 DESCRIPTION 8*b077aed3SPierre Pronchery 9*b077aed3SPierre ProncheryThe EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). 10*b077aed3SPierre ProncheryX963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to 11*b077aed3SPierre Proncheryderive a key using input such as a shared secret key and shared info. 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery=head2 Identity 14*b077aed3SPierre Pronchery 15*b077aed3SPierre Pronchery"X963KDF" is the name for this implementation; it 16*b077aed3SPierre Proncherycan be used with the EVP_KDF_fetch() function. 17*b077aed3SPierre Pronchery 18*b077aed3SPierre Pronchery=head2 Supported parameters 19*b077aed3SPierre Pronchery 20*b077aed3SPierre ProncheryThe supported parameters are: 21*b077aed3SPierre Pronchery 22*b077aed3SPierre Pronchery=over 4 23*b077aed3SPierre Pronchery 24*b077aed3SPierre Pronchery=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 25*b077aed3SPierre Pronchery 26*b077aed3SPierre Pronchery=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 27*b077aed3SPierre Pronchery 28*b077aed3SPierre ProncheryThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 29*b077aed3SPierre Pronchery 30*b077aed3SPierre Pronchery=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 31*b077aed3SPierre Pronchery 32*b077aed3SPierre ProncheryThe shared secret used for key derivation. 33*b077aed3SPierre ProncheryThis parameter sets the secret. 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 36*b077aed3SPierre Pronchery 37*b077aed3SPierre ProncheryThis parameter specifies an optional value for shared info. 38*b077aed3SPierre Pronchery 39*b077aed3SPierre Pronchery=back 40*b077aed3SPierre Pronchery 41*b077aed3SPierre Pronchery=head1 NOTES 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryX963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, 44*b077aed3SPierre ProncheryX963KDF appends the counter to the secret, whereas SSKDF prepends the counter. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryA context for X963KDF can be obtained by calling: 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 49*b077aed3SPierre Pronchery EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 50*b077aed3SPierre Pronchery 51*b077aed3SPierre ProncheryThe output length of an X963KDF is specified via the I<keylen> 52*b077aed3SPierre Proncheryparameter to the L<EVP_KDF_derive(3)> function. 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=head1 EXAMPLES 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryThis example derives 10 bytes, with the secret key "secret" and sharedinfo 57*b077aed3SPierre Proncheryvalue "label": 58*b077aed3SPierre Pronchery 59*b077aed3SPierre Pronchery EVP_KDF *kdf; 60*b077aed3SPierre Pronchery EVP_KDF_CTX *kctx; 61*b077aed3SPierre Pronchery unsigned char out[10]; 62*b077aed3SPierre Pronchery OSSL_PARAM params[4], *p = params; 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 65*b077aed3SPierre Pronchery kctx = EVP_KDF_CTX_new(kdf); 66*b077aed3SPierre Pronchery EVP_KDF_free(kdf); 67*b077aed3SPierre Pronchery 68*b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 69*b077aed3SPierre Pronchery SN_sha256, strlen(SN_sha256)); 70*b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 71*b077aed3SPierre Pronchery "secret", (size_t)6); 72*b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 73*b077aed3SPierre Pronchery "label", (size_t)5); 74*b077aed3SPierre Pronchery *p = OSSL_PARAM_construct_end(); 75*b077aed3SPierre Pronchery if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 76*b077aed3SPierre Pronchery error("EVP_KDF_derive"); 77*b077aed3SPierre Pronchery } 78*b077aed3SPierre Pronchery 79*b077aed3SPierre Pronchery EVP_KDF_CTX_free(kctx); 80*b077aed3SPierre Pronchery 81*b077aed3SPierre Pronchery=head1 CONFORMING TO 82*b077aed3SPierre Pronchery 83*b077aed3SPierre Pronchery"SEC 1: Elliptic Curve Cryptography" 84*b077aed3SPierre Pronchery 85*b077aed3SPierre Pronchery=head1 SEE ALSO 86*b077aed3SPierre Pronchery 87*b077aed3SPierre ProncheryL<EVP_KDF(3)>, 88*b077aed3SPierre ProncheryL<EVP_KDF_CTX_new(3)>, 89*b077aed3SPierre ProncheryL<EVP_KDF_CTX_free(3)>, 90*b077aed3SPierre ProncheryL<EVP_KDF_CTX_set_params(3)>, 91*b077aed3SPierre ProncheryL<EVP_KDF_CTX_get_kdf_size(3)>, 92*b077aed3SPierre ProncheryL<EVP_KDF_derive(3)>, 93*b077aed3SPierre ProncheryL<EVP_KDF(3)/PARAMETERS> 94*b077aed3SPierre Pronchery 95*b077aed3SPierre Pronchery=head1 HISTORY 96*b077aed3SPierre Pronchery 97*b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 98*b077aed3SPierre Pronchery 99*b077aed3SPierre Pronchery=head1 COPYRIGHT 100*b077aed3SPierre Pronchery 101*b077aed3SPierre ProncheryCopyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 102*b077aed3SPierre Pronchery 103*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 104*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 105*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 106*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 107*b077aed3SPierre Pronchery 108*b077aed3SPierre Pronchery=cut 109