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