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