EVP_PKEY_get_bn_param(3ossl)

1EVP_PKEY_GETTABLE_PARAMS(3ossl)     OpenSSL    EVP_PKEY_GETTABLE_PARAMS(3ossl)
2
3
4

NAME

6       EVP_PKEY_gettable_params, EVP_PKEY_get_params, EVP_PKEY_get_int_param,
7       EVP_PKEY_get_size_t_param, EVP_PKEY_get_bn_param,
8       EVP_PKEY_get_utf8_string_param, EVP_PKEY_get_octet_string_param -
9       retrieve key parameters from a key
10

SYNOPSIS

12        #include <openssl/evp.h>
13
14        const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
15        int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);
16        int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,
17                                   int *out);
18        int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,
19                                      size_t *out);
20        int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,
21                                  BIGNUM **bn);
22        int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,
23                                           char *str, size_t max_buf_sz,
24                                           size_t *out_len);
25        int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,
26                                            unsigned char *buf, size_t max_buf_sz,
27                                            size_t *out_len);
28

DESCRIPTION

30       EVP_PKEY_get_params() retrieves parameters from the key pkey, according
31       to the contents of params.  See OSSL_PARAM(3) for information about
32       parameters.
33
34       EVP_PKEY_gettable_params() returns a constant list of params indicating
35       the names and types of key parameters that can be retrieved.  See
36       OSSL_PARAM(3) for information about parameters.
37
38       An OSSL_PARAM of type OSSL_PARAM_INTEGER or OSSL_PARAM_UNSIGNED_INTEGER
39       is of arbitrary length. Such a parameter can be obtained using any of
40       the functions EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param() or
41       EVP_PKEY_get_bn_param(). Attempting to obtain an integer value that
42       does not fit into a native C int type will cause
43       EVP_PKEY_get_int_param() to fail. Similarly attempting to obtain an
44       integer value that is negative or does not fit into a native C size_t
45       type using EVP_PKEY_get_size_t_param() will also fail.
46
47       EVP_PKEY_get_int_param() retrieves a key pkey integer value *out
48       associated with a name of key_name if it fits into "int" type. For
49       parameters that do not fit into "int" use EVP_PKEY_get_bn_param().
50
51       EVP_PKEY_get_size_t_param() retrieves a key pkey size_t value *out
52       associated with a name of key_name if it fits into "size_t" type. For
53       parameters that do not fit into "size_t" use EVP_PKEY_get_bn_param().
54
55       EVP_PKEY_get_bn_param() retrieves a key pkey BIGNUM value **bn
56       associated with a name of key_name. If *bn is NULL then the BIGNUM is
57       allocated by the method.
58
59       EVP_PKEY_get_utf8_string_param() get a key pkey UTF8 string value into
60       a buffer str of maximum size max_buf_sz associated with a name of
61       key_name.  The maximum size must be large enough to accomodate the
62       string value including a terminating NUL byte, or this function will
63       fail.  If out_len is not NULL, *out_len is set to the length of the
64       string not including the terminating NUL byte. The required buffer size
65       not including the terminating NUL byte can be obtained from *out_len by
66       calling the function with str set to NULL.
67
68       EVP_PKEY_get_octet_string_param() get a key pkey's octet string value
69       into a buffer buf of maximum size max_buf_sz associated with a name of
70       key_name.  If out_len is not NULL, *out_len is set to the length of the
71       contents.  The required buffer size can be obtained from *out_len by
72       calling the function with buf set to NULL.
73

NOTES

75       These functions only work for EVP_PKEYs that contain a provider side
76       key.
77

RETURN VALUES

79       EVP_PKEY_gettable_params() returns NULL on error or if it is not
80       supported.
81
82       All other methods return 1 if a value associated with the key's
83       key_name was successfully returned, or 0 if there was an error.  An
84       error may be returned by methods EVP_PKEY_get_utf8_string_param() and
85       EVP_PKEY_get_octet_string_param() if max_buf_sz is not big enough to
86       hold the value.  If out_len is not NULL, *out_len will be assigned the
87       required buffer size to hold the value.
88

EXAMPLES

90        #include <openssl/evp.h>
91
92        char *curve_name[64];
93        unsigned char pub[256];
94        BIGNUM *bn_priv = NULL;
95
96        /*
97         * NB: assumes 'key' is set up before the next step. In this example the key
98         * is an EC key.
99         */
100
101        if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
102                                            curve_name, sizeof(curve_name), &len)) {
103          /* Error */
104        }
105        if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
106                                             pub, sizeof(pub), &len)) {
107            /* Error */
108        }
109        if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
110            /* Error */
111        }
112
113
114        BN_clear_free(bn_priv);
115

HISTORY

120       These functions were added in OpenSSL 3.0.
121

COPYRIGHT

123       Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
124
125       Licensed under the Apache License 2.0 (the "License").  You may not use
126       this file except in compliance with the License.  You can obtain a copy
127       in the file LICENSE in the source distribution or at
128       <https://www.openssl.org/source/license.html>.
129
130
131
1323.0.5                             2022-11-01   EVP_PKEY_GETTABLE_PARAMS(3ossl)