1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_PKEY_gettable_params, EVP_PKEY_get_params, 6b077aed3SPierre ProncheryEVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param, 7b077aed3SPierre ProncheryEVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param, 8b077aed3SPierre ProncheryEVP_PKEY_get_octet_string_param 9b077aed3SPierre Pronchery- retrieve key parameters from a key 10b077aed3SPierre Pronchery 11b077aed3SPierre Pronchery=head1 SYNOPSIS 12b077aed3SPierre Pronchery 13b077aed3SPierre Pronchery #include <openssl/evp.h> 14b077aed3SPierre Pronchery 15b077aed3SPierre Pronchery const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey); 16b077aed3SPierre Pronchery int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]); 17b077aed3SPierre Pronchery int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name, 18b077aed3SPierre Pronchery int *out); 19b077aed3SPierre Pronchery int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name, 20b077aed3SPierre Pronchery size_t *out); 21b077aed3SPierre Pronchery int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name, 22b077aed3SPierre Pronchery BIGNUM **bn); 23b077aed3SPierre Pronchery int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name, 24b077aed3SPierre Pronchery char *str, size_t max_buf_sz, 25b077aed3SPierre Pronchery size_t *out_len); 26b077aed3SPierre Pronchery int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name, 27b077aed3SPierre Pronchery unsigned char *buf, size_t max_buf_sz, 28b077aed3SPierre Pronchery size_t *out_len); 29b077aed3SPierre Pronchery 30b077aed3SPierre Pronchery=head1 DESCRIPTION 31b077aed3SPierre Pronchery 32b077aed3SPierre ProncherySee L<OSSL_PARAM(3)> for information about parameters. 33b077aed3SPierre Pronchery 34b077aed3SPierre ProncheryEVP_PKEY_get_params() retrieves parameters from the key I<pkey>, according to 35b077aed3SPierre Proncherythe contents of I<params>. 36b077aed3SPierre Pronchery 37b077aed3SPierre ProncheryEVP_PKEY_gettable_params() returns a constant list of I<params> indicating 38b077aed3SPierre Proncherythe names and types of key parameters that can be retrieved. 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryAn L<OSSL_PARAM(3)> of type B<OSSL_PARAM_INTEGER> or 41b077aed3SPierre ProncheryB<OSSL_PARAM_UNSIGNED_INTEGER> is of arbitrary length. Such a parameter can be 42b077aed3SPierre Proncheryobtained using any of the functions EVP_PKEY_get_int_param(), 43b077aed3SPierre ProncheryEVP_PKEY_get_size_t_param() or EVP_PKEY_get_bn_param(). Attempting to 44b077aed3SPierre Proncheryobtain an integer value that does not fit into a native C B<int> type will cause 45b077aed3SPierre ProncheryEVP_PKEY_get_int_param() to fail. Similarly attempting to obtain an integer 46b077aed3SPierre Proncheryvalue that is negative or does not fit into a native C B<size_t> type using 47b077aed3SPierre ProncheryEVP_PKEY_get_size_t_param() will also fail. 48b077aed3SPierre Pronchery 49b077aed3SPierre ProncheryEVP_PKEY_get_int_param() retrieves a key I<pkey> integer value I<*out> 50b077aed3SPierre Proncheryassociated with a name of I<key_name> if it fits into C<int> type. For 51b077aed3SPierre Proncheryparameters that do not fit into C<int> use EVP_PKEY_get_bn_param(). 52b077aed3SPierre Pronchery 53b077aed3SPierre ProncheryEVP_PKEY_get_size_t_param() retrieves a key I<pkey> size_t value I<*out> 54b077aed3SPierre Proncheryassociated with a name of I<key_name> if it fits into C<size_t> type. For 55b077aed3SPierre Proncheryparameters that do not fit into C<size_t> use EVP_PKEY_get_bn_param(). 56b077aed3SPierre Pronchery 57b077aed3SPierre ProncheryEVP_PKEY_get_bn_param() retrieves a key I<pkey> BIGNUM value I<**bn> 58b077aed3SPierre Proncheryassociated with a name of I<key_name>. If I<*bn> is NULL then the BIGNUM 59b077aed3SPierre Proncheryis allocated by the method. 60b077aed3SPierre Pronchery 61b077aed3SPierre ProncheryEVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value into a 62b077aed3SPierre Proncherybuffer I<str> of maximum size I<max_buf_sz> associated with a name of 63*aa795734SPierre ProncheryI<key_name>. The maximum size must be large enough to accommodate the string 64b077aed3SPierre Proncheryvalue including a terminating NUL byte, or this function will fail. 65b077aed3SPierre ProncheryIf I<out_len> is not NULL, I<*out_len> is set to the length of the string 66b077aed3SPierre Proncherynot including the terminating NUL byte. The required buffer size not including 67b077aed3SPierre Proncherythe terminating NUL byte can be obtained from I<*out_len> by calling the 68b077aed3SPierre Proncheryfunction with I<str> set to NULL. 69b077aed3SPierre Pronchery 70b077aed3SPierre ProncheryEVP_PKEY_get_octet_string_param() get a key I<pkey>'s octet string value into a 71b077aed3SPierre Proncherybuffer I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>. 72b077aed3SPierre ProncheryIf I<out_len> is not NULL, I<*out_len> is set to the length of the contents. 73b077aed3SPierre ProncheryThe required buffer size can be obtained from I<*out_len> by calling the 74b077aed3SPierre Proncheryfunction with I<buf> set to NULL. 75b077aed3SPierre Pronchery 76b077aed3SPierre Pronchery=head1 NOTES 77b077aed3SPierre Pronchery 78b077aed3SPierre ProncheryThese functions only work for B<EVP_PKEY>s that contain a provider side key. 79b077aed3SPierre Pronchery 80b077aed3SPierre Pronchery=head1 RETURN VALUES 81b077aed3SPierre Pronchery 82b077aed3SPierre ProncheryEVP_PKEY_gettable_params() returns NULL on error or if it is not supported. 83b077aed3SPierre Pronchery 84b077aed3SPierre ProncheryAll other methods return 1 if a value associated with the key's I<key_name> was 85b077aed3SPierre Proncherysuccessfully returned, or 0 if there was an error. 86b077aed3SPierre ProncheryAn error may be returned by methods EVP_PKEY_get_utf8_string_param() and 87b077aed3SPierre ProncheryEVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the 88b077aed3SPierre Proncheryvalue. If I<out_len> is not NULL, I<*out_len> will be assigned the required 89b077aed3SPierre Proncherybuffer size to hold the value. 90b077aed3SPierre Pronchery 91b077aed3SPierre Pronchery=head1 EXAMPLES 92b077aed3SPierre Pronchery 93b077aed3SPierre Pronchery #include <openssl/evp.h> 94b077aed3SPierre Pronchery 95b077aed3SPierre Pronchery char curve_name[64]; 96b077aed3SPierre Pronchery unsigned char pub[256]; 97b077aed3SPierre Pronchery BIGNUM *bn_priv = NULL; 98b077aed3SPierre Pronchery 99b077aed3SPierre Pronchery /* 100b077aed3SPierre Pronchery * NB: assumes 'key' is set up before the next step. In this example the key 101b077aed3SPierre Pronchery * is an EC key. 102b077aed3SPierre Pronchery */ 103b077aed3SPierre Pronchery 104b077aed3SPierre Pronchery if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME, 105b077aed3SPierre Pronchery curve_name, sizeof(curve_name), &len)) { 106b077aed3SPierre Pronchery /* Error */ 107b077aed3SPierre Pronchery } 108b077aed3SPierre Pronchery if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY, 109b077aed3SPierre Pronchery pub, sizeof(pub), &len)) { 110b077aed3SPierre Pronchery /* Error */ 111b077aed3SPierre Pronchery } 112b077aed3SPierre Pronchery if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) { 113b077aed3SPierre Pronchery /* Error */ 114b077aed3SPierre Pronchery } 115b077aed3SPierre Pronchery 116b077aed3SPierre Pronchery BN_clear_free(bn_priv); 117b077aed3SPierre Pronchery 118b077aed3SPierre Pronchery=head1 SEE ALSO 119b077aed3SPierre Pronchery 120b077aed3SPierre ProncheryL<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)> 121b077aed3SPierre Pronchery 122b077aed3SPierre Pronchery=head1 HISTORY 123b077aed3SPierre Pronchery 124b077aed3SPierre ProncheryThese functions were added in OpenSSL 3.0. 125b077aed3SPierre Pronchery 126b077aed3SPierre Pronchery=head1 COPYRIGHT 127b077aed3SPierre Pronchery 128*aa795734SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 129b077aed3SPierre Pronchery 130b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 131b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 132b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 133b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 134b077aed3SPierre Pronchery 135b077aed3SPierre Pronchery=cut 136b077aed3SPierre Pronchery 137