Debian Codegraph @

upstream/debian-unstable/man3/OSSL_PARAM_allocate_from_text.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 "OSSL_PARAM_ALLOCATE_FROM_TEXT 3SSL"
58 .TH OSSL_PARAM_ALLOCATE_FROM_TEXT 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 OSSL_PARAM_allocate_from_text
65 \&\- OSSL_PARAM construction utilities
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/params.h>
70 \&
71 \& int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
72 \& const OSSL_PARAM *paramdefs,
73 \& const char *key, const char *value,
74 \& size_t value_n,
75 \& int *found);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 With OpenSSL before version 3.0, parameters were passed down to or
80 retrieved from algorithm implementations via control functions.
81 Some of these control functions existed in variants that took string
82 parameters, for example \fBEVP_PKEY_CTX_ctrl_str\fR\|(3).
83 .PP
84 OpenSSL 3.0 introduces a new mechanism to do the same thing with an
85 array of parameters that contain name, value, value type and value
86 size (see \fBOSSL_PARAM\fR\|(3) for more information).
87 .PP
88 \&\fBOSSL_PARAM_allocate_from_text()\fR uses \fIkey\fR to look up an item in
89 \&\fIparamdefs\fR. If an item was found, it converts \fIvalue\fR to something
90 suitable for that item's \fIdata_type\fR, and stores the result in
91 \&\fIto\->data\fR as well as its size in \fIto\->data_size\fR.
92 \&\fIto\->key\fR and \fIto\->data_type\fR are assigned the corresponding
93 values from the item that was found, and \fIto\->return_size\fR is set
94 to zero.
95 .PP
96 \&\fIto\->data\fR is always allocated using \fBOPENSSL_zalloc\fR\|(3) and
97 needs to be freed by the caller when it's not useful any more, using
98 \&\fBOPENSSL_free\fR\|(3).
99 .PP
100 If \fIfound\fR is not NULL, \fI*found\fR is set to 1 if \fIkey\fR could be
101 located in \fIparamdefs\fR, and to 0 otherwise.
102 .SS "The use of \fIkey\fP and \fIvalue\fP in detail"
103 .IX Subsection "The use of key and value in detail"
104 \&\fBOSSL_PARAM_allocate_from_text()\fR takes note if \fIkey\fR starts with
105 "hex", and will only use the rest of \fIkey\fR to look up an item in
106 \&\fIparamdefs\fR in that case. As an example, if \fIkey\fR is "hexid", "id"
107 will be looked up in \fIparamdefs\fR.
108 .PP
109 When an item in \fIparamdefs\fR has been found, \fIvalue\fR is converted
110 depending on that item's \fIdata_type\fR, as follows:
111 .IP "\fBOSSL_PARAM_INTEGER\fR and \fBOSSL_PARAM_UNSIGNED_INTEGER\fR" 4
112 .IX Item "OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER"
113 If \fIkey\fR didn't start with "hex", \fIvalue\fR is assumed to contain
114 \&\fIvalue_n\fR decimal characters, which are decoded, and the resulting
115 bytes become the number stored in the \fIto\->data\fR storage.
116 .Sp
117 If \fIvalue\fR starts with "0x", it is assumed to contain \fIvalue_n\fR
118 hexadecimal characters.
119 .Sp
120 If \fIkey\fR started with "hex", \fIvalue\fR is assumed to contain
121 \&\fIvalue_n\fR hexadecimal characters without the "0x" prefix.
122 .Sp
123 If \fIvalue\fR contains characters that couldn't be decoded as
124 hexadecimal or decimal characters, \fBOSSL_PARAM_allocate_from_text()\fR
125 considers that an error.
126 .IP \fBOSSL_PARAM_UTF8_STRING\fR 4
127 .IX Item "OSSL_PARAM_UTF8_STRING"
128 If \fIkey\fR started with "hex", \fBOSSL_PARAM_allocate_from_text()\fR
129 considers that an error.
130 .Sp
131 Otherwise, \fIvalue\fR is considered a C string and is copied to the
132 \&\fIto\->data\fR storage.
133 On systems where the native character encoding is EBCDIC, the bytes in
134 \&\fIto\->data\fR are converted to ASCII.
135 .IP \fBOSSL_PARAM_OCTET_STRING\fR 4
136 .IX Item "OSSL_PARAM_OCTET_STRING"
137 If \fIkey\fR started with "hex", \fIvalue\fR is assumed to contain
138 \&\fIvalue_n\fR hexadecimal characters, which are decoded, and the
139 resulting bytes are stored in the \fIto\->data\fR storage.
140 If \fIvalue\fR contains characters that couldn't be decoded as
141 hexadecimal or decimal characters, \fBOSSL_PARAM_allocate_from_text()\fR
142 considers that an error.
143 .Sp
144 If \fIkey\fR didn't start with "hex", \fIvalue_n\fR bytes from \fIvalue\fR are
145 copied to the \fIto\->data\fR storage.
146 .SH "RETURN VALUES"
147 .IX Header "RETURN VALUES"
148 \&\fBOSSL_PARAM_allocate_from_text()\fR returns 1 if \fIkey\fR was found in
149 \&\fIparamdefs\fR and there was no other failure, otherwise 0.
150 .SH NOTES
151 .IX Header "NOTES"
152 The parameter descriptor array comes from functions dedicated to
153 return them.
154 The following \fBOSSL_PARAM\fR\|(3) attributes are used:
155 .IP \fIkey\fR 4
156 .IX Item "key"
157 .PD 0
158 .IP \fIdata_type\fR 4
159 .IX Item "data_type"
160 .IP \fIdata_size\fR 4
161 .IX Item "data_size"
162 .PD
163 .PP
164 All other attributes are ignored.
165 .PP
166 The \fIdata_size\fR attribute can be zero, meaning that the parameter it
167 describes expects arbitrary length data.
168 .SH EXAMPLES
169 .IX Header "EXAMPLES"
170 Code that looked like this:
171 .PP
172 .Vb 4
173 \& int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
174 \& {
175 \& int rv;
176 \& char *stmp, *vtmp = NULL;
177 \&
178 \& stmp = OPENSSL_strdup(value);
179 \& if (stmp == NULL)
180 \& return \-1;
181 \& vtmp = strchr(stmp, \*(Aq:\*(Aq);
182 \& if (vtmp != NULL)
183 \& *vtmp++ = \*(Aq\e0\*(Aq;
184 \& rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
185 \& OPENSSL_free(stmp);
186 \& return rv;
187 \& }
188 \&
189 \& ...
190 \&
191 \&
192 \& for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
193 \& char *macopt = sk_OPENSSL_STRING_value(macopts, i);
194 \&
195 \& if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
196 \& BIO_printf(bio_err,
197 \& "MAC parameter error \e"%s\e"\en", macopt);
198 \& ERR_print_errors(bio_err);
199 \& goto mac_end;
200 \& }
201 \& }
202 .Ve
203 .PP
204 Can be written like this instead:
205 .PP
206 .Vb 6
207 \& OSSL_PARAM *params =
208 \& OPENSSL_zalloc(sizeof(*params)
209 \& * (sk_OPENSSL_STRING_num(opts) + 1));
210 \& const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
211 \& size_t params_n;
212 \& char *opt = "<unknown>";
213 \&
214 \& for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
215 \& params_n++) {
216 \& char *stmp, *vtmp = NULL;
217 \&
218 \& opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
219 \& if ((stmp = OPENSSL_strdup(opt)) == NULL
220 \& || (vtmp = strchr(stmp, \*(Aq:\*(Aq)) == NULL)
221 \& goto err;
222 \&
223 \& *vtmp++ = \*(Aq\e0\*(Aq;
224 \& if (!OSSL_PARAM_allocate_from_text(&params[params_n],
225 \& paramdefs, stmp,
226 \& vtmp, strlen(vtmp), NULL))
227 \& goto err;
228 \& }
229 \& params[params_n] = OSSL_PARAM_construct_end();
230 \& if (!EVP_MAC_CTX_set_params(ctx, params))
231 \& goto err;
232 \& while (params_n\-\- > 0)
233 \& OPENSSL_free(params[params_n].data);
234 \& OPENSSL_free(params);
235 \& /* ... */
236 \& return;
237 \&
238 \& err:
239 \& BIO_printf(bio_err, "MAC parameter error \*(Aq%s\*(Aq\en", opt);
240 \& ERR_print_errors(bio_err);
241 .Ve
242 .SH "SEE ALSO"
243 .IX Header "SEE ALSO"
244 \&\fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_int\fR\|(3)
245 .SH COPYRIGHT
246 .IX Header "COPYRIGHT"
247 Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved.
248 .PP
249 Licensed under the Apache License 2.0 (the "License"). You may not use
250 this file except in compliance with the License. You can obtain a copy
251 in the file LICENSE in the source distribution or at
252 <https://www.openssl.org/source/license.html>.