Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_gettable_params.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_GETTABLE_PARAMS 3SSL"
58 .TH EVP_PKEY_GETTABLE_PARAMS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_gettable_params, EVP_PKEY_get_params,
65 EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param,
66 EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param,
67 EVP_PKEY_get_octet_string_param
68 \&\- retrieve key parameters from a key
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/evp.h>
73 \&
74 \& const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
75 \& int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);
76 \& int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,
77 \& int *out);
78 \& int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,
79 \& size_t *out);
80 \& int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,
81 \& BIGNUM **bn);
82 \& int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,
83 \& char *str, size_t max_buf_sz,
84 \& size_t *out_len);
85 \& int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,
86 \& unsigned char *buf, size_t max_buf_sz,
87 \& size_t *out_len);
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 See \fBOSSL_PARAM\fR\|(3) for information about parameters.
92 .PP
93 \&\fBEVP_PKEY_get_params()\fR retrieves parameters from the key \fIpkey\fR, according to
94 the contents of \fIparams\fR.
95 .PP
96 \&\fBEVP_PKEY_gettable_params()\fR returns a constant list of \fIparams\fR indicating
97 the names and types of key parameters that can be retrieved.
98 .PP
99 An \fBOSSL_PARAM\fR\|(3) of type \fBOSSL_PARAM_INTEGER\fR or
100 \&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR is of arbitrary length. Such a parameter can be
101 obtained using any of the functions \fBEVP_PKEY_get_int_param()\fR,
102 \&\fBEVP_PKEY_get_size_t_param()\fR or \fBEVP_PKEY_get_bn_param()\fR. Attempting to
103 obtain an integer value that does not fit into a native C \fBint\fR type will cause
104 \&\fBEVP_PKEY_get_int_param()\fR to fail. Similarly attempting to obtain an integer
105 value that is negative or does not fit into a native C \fBsize_t\fR type using
106 \&\fBEVP_PKEY_get_size_t_param()\fR will also fail.
107 .PP
108 \&\fBEVP_PKEY_get_int_param()\fR retrieves a key \fIpkey\fR integer value \fI*out\fR
109 associated with a name of \fIkey_name\fR if it fits into \f(CW\*(C`int\*(C'\fR type. For
110 parameters that do not fit into \f(CW\*(C`int\*(C'\fR use \fBEVP_PKEY_get_bn_param()\fR.
111 .PP
112 \&\fBEVP_PKEY_get_size_t_param()\fR retrieves a key \fIpkey\fR size_t value \fI*out\fR
113 associated with a name of \fIkey_name\fR if it fits into \f(CW\*(C`size_t\*(C'\fR type. For
114 parameters that do not fit into \f(CW\*(C`size_t\*(C'\fR use \fBEVP_PKEY_get_bn_param()\fR.
115 .PP
116 \&\fBEVP_PKEY_get_bn_param()\fR retrieves a key \fIpkey\fR BIGNUM value \fI**bn\fR
117 associated with a name of \fIkey_name\fR. If \fI*bn\fR is NULL then the BIGNUM
118 is allocated by the method.
119 .PP
120 \&\fBEVP_PKEY_get_utf8_string_param()\fR get a key \fIpkey\fR UTF8 string value into a
121 buffer \fIstr\fR of maximum size \fImax_buf_sz\fR associated with a name of
122 \&\fIkey_name\fR. The maximum size must be large enough to accommodate the string
123 value including a terminating NUL byte, or this function will fail.
124 If \fIout_len\fR is not NULL, \fI*out_len\fR is set to the length of the string
125 not including the terminating NUL byte. The required buffer size not including
126 the terminating NUL byte can be obtained from \fI*out_len\fR by calling the
127 function with \fIstr\fR set to NULL.
128 .PP
129 \&\fBEVP_PKEY_get_octet_string_param()\fR get a key \fIpkey\fR's octet string value into a
130 buffer \fIbuf\fR of maximum size \fImax_buf_sz\fR associated with a name of \fIkey_name\fR.
131 If \fIout_len\fR is not NULL, \fI*out_len\fR is set to the length of the contents.
132 The required buffer size can be obtained from \fI*out_len\fR by calling the
133 function with \fIbuf\fR set to NULL.
134 .SH NOTES
135 .IX Header "NOTES"
136 These functions only work for \fBEVP_PKEY\fRs that contain a provider side key.
137 .SH "RETURN VALUES"
138 .IX Header "RETURN VALUES"
139 \&\fBEVP_PKEY_gettable_params()\fR returns NULL on error or if it is not supported.
140 .PP
141 All other methods return 1 if a value associated with the key's \fIkey_name\fR was
142 successfully returned, or 0 if there was an error.
143 An error may be returned by methods \fBEVP_PKEY_get_utf8_string_param()\fR and
144 \&\fBEVP_PKEY_get_octet_string_param()\fR if \fImax_buf_sz\fR is not big enough to hold the
145 value. If \fIout_len\fR is not NULL, \fI*out_len\fR will be assigned the required
146 buffer size to hold the value.
147 .SH EXAMPLES
148 .IX Header "EXAMPLES"
149 .Vb 1
150 \& #include <openssl/evp.h>
151 \&
152 \& char curve_name[64];
153 \& unsigned char pub[256];
154 \& BIGNUM *bn_priv = NULL;
155 \&
156 \& /*
157 \& * NB: assumes \*(Aqkey\*(Aq is set up before the next step. In this example the key
158 \& * is an EC key.
159 \& */
160 \&
161 \& if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
162 \& curve_name, sizeof(curve_name), &len)) {
163 \& /* Error */
164 \& }
165 \& if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
166 \& pub, sizeof(pub), &len)) {
167 \& /* Error */
168 \& }
169 \& if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
170 \& /* Error */
171 \& }
172 \&
173 \& BN_clear_free(bn_priv);
174 .Ve
175 .SH "SEE ALSO"
176 .IX Header "SEE ALSO"
177 \&\fBEVP_PKEY_CTX_new\fR\|(3), \fBprovider\-keymgmt\fR\|(7), \fBOSSL_PARAM\fR\|(3)
178 .SH HISTORY
179 .IX Header "HISTORY"
180 These functions were added in OpenSSL 3.0.
181 .SH COPYRIGHT
182 .IX Header "COPYRIGHT"
183 Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved.
184 .PP
185 Licensed under the Apache License 2.0 (the "License"). You may not use
186 this file except in compliance with the License. You can obtain a copy
187 in the file LICENSE in the source distribution or at
188 <https://www.openssl.org/source/license.html>.