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.
56
57EVP_PKEY_get_octet_string_param() get a key I<pkey>'s octet string value into a
58buffer I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
59If I<out_len> is not NULL, I<*out_len> is set to the length of the contents.
60
61=head1 NOTES
62
63These functions only work for B<EVP_PKEY>s that contain a provider side key.
64
65=head1 RETURN VALUES
66
67EVP_PKEY_gettable_params() returns NULL on error or if it is not supported,
68
69All other methods return 1 if a value associated with the key's I<key_name> was
70successfully returned, or 0 if there was an error.
71An error may be returned by methods EVP_PKEY_get_utf8_string_param() and
72EVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the
73value.  If I<out_len> is not NULL, I<*out_len> will be assigned the required
74buffer size to hold the value.
75
76=head1 EXAMPLES
77
78 #include <openssl/evp.h>
79
80 char *curve_name[64];
81 unsigned char pub[256];
82 BIGNUM *bn_priv = NULL;
83
84 /*
85  * NB: assumes 'key' is set up before the next step. In this example the key
86  * is an EC key.
87  */
88
89 if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
90                                     curve_name, sizeof(curve_name), &len)) {
91   /* Error */
92 }
93 if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
94                                      pub, sizeof(pub), &len)) {
95     /* Error */
96 }
97 if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
98     /* Error */
99 }
100
101
102 BN_clear_free(bn_priv);
103
104=head1 SEE ALSO
105
106L<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)>
107
108=head1 HISTORY
109
110These functions were added in OpenSSL 3.0.
111
112=head1 COPYRIGHT
113
114Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
115
116Licensed under the Apache License 2.0 (the "License").  You may not use
117this file except in compliance with the License.  You can obtain a copy
118in the file LICENSE in the source distribution or at
119L<https://www.openssl.org/source/license.html>.
120
121=cut
122
123