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