1=pod 2 3=head1 NAME 4 5EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). 10X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to 11derive a key using input such as a shared secret key and shared info. 12 13The output is considered to be keying material. 14 15=head2 Identity 16 17"X963KDF" is the name for this implementation; it 18can be used with the EVP_KDF_fetch() function. 19 20=head2 Supported parameters 21 22The supported parameters are: 23 24=over 4 25 26=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 27 28=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 29 30These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 31 32=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 33 34The shared secret used for key derivation. 35This parameter sets the secret. 36 37=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 38 39This parameter specifies an optional value for shared info. 40 41=back 42 43The OpenSSL FIPS provider also supports the following parameters: 44 45=over 4 46 47=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 48 49A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 50This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" 51related parameter is set to 0 and the check fails. 52 53=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <int> 54 55The default value of 1 causes an error during EVP_KDF_CTX_set_params() if 56used digest is not approved. 57Setting this to zero will ignore the error and set the approved 58"fips-indicator" to 0. 59This option breaks FIPS compliance if it causes the approved "fips-indicator" 60to return 0. 61 62According to ANSI X9.63-2001, the following are approved digest algorithms: 63SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224, SHA2-512/256, SHA3-224, 64SHA3-256, SHA3-384, SHA3-512. 65 66=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 67 68The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 69length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 70bits. 71Setting this to zero will ignore the error and set the approved 72"fips-indicator" to 0. 73This option breaks FIPS compliance if it causes the approved "fips-indicator" 74to return 0. 75 76=back 77 78=head1 NOTES 79 80X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, 81X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. 82 83A context for X963KDF can be obtained by calling: 84 85 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 86 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 87 88The output length of an X963KDF is specified via the I<keylen> 89parameter to the L<EVP_KDF_derive(3)> function. 90 91=head1 EXAMPLES 92 93This example derives 10 bytes, with the secret key "secret" and sharedinfo 94value "label": 95 96 EVP_KDF *kdf; 97 EVP_KDF_CTX *kctx; 98 unsigned char out[10]; 99 OSSL_PARAM params[4], *p = params; 100 101 kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 102 kctx = EVP_KDF_CTX_new(kdf); 103 EVP_KDF_free(kdf); 104 105 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 106 SN_sha256, strlen(SN_sha256)); 107 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 108 "secret", (size_t)6); 109 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 110 "label", (size_t)5); 111 *p = OSSL_PARAM_construct_end(); 112 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 113 error("EVP_KDF_derive"); 114 } 115 116 EVP_KDF_CTX_free(kctx); 117 118=head1 CONFORMING TO 119 120"SEC 1: Elliptic Curve Cryptography" 121 122=head1 SEE ALSO 123 124L<EVP_KDF(3)>, 125L<EVP_KDF_CTX_new(3)>, 126L<EVP_KDF_CTX_free(3)>, 127L<EVP_KDF_CTX_set_params(3)>, 128L<EVP_KDF_CTX_get_kdf_size(3)>, 129L<EVP_KDF_derive(3)>, 130L<EVP_KDF(3)/PARAMETERS> 131 132=head1 HISTORY 133 134This functionality was added in OpenSSL 3.0. 135 136=head1 COPYRIGHT 137 138Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 139 140Licensed under the Apache License 2.0 (the "License"). You may not use 141this file except in compliance with the License. You can obtain a copy 142in the file LICENSE in the source distribution or at 143L<https://www.openssl.org/source/license.html>. 144 145=cut 146
