DOCS: Fix the description of OSSL_PARAM_allocate_from_text()
[openssl.git] / doc / man3 / OSSL_PARAM_allocate_from_text.pod
1 =pod
2
3 =head1 NAME
4
5 OSSL_PARAM_allocate_from_text
6 - OSSL_PARAM construction utilities
7
8 =head1 SYNOPSIS
9
10  #include <openssl/params.h>
11
12  int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
13                                    const OSSL_PARAM *paramdefs,
14                                    const char *key, const char *value,
15                                    size_t value_n,
16                                    int *found);
17
18 =head1 DESCRIPTION
19
20 With OpenSSL before version 3.0, parameters were passed down to or
21 retrieved from algorithm implementations via control functions.
22 Some of these control functions existed in variants that took string
23 parameters, for example L<EVP_PKEY_CTX_ctrl_str(3)>.
24
25 OpenSSL 3.0 introduces a new mechanism to do the same thing with an
26 array of parameters that contain name, value, value type and value
27 size (see L<OSSL_PARAM(3)> for more information).
28
29 OSSL_PARAM_allocate_from_text() uses I<key> to look up an item in
30 I<paramdefs>.  If an item was found, it converts I<value> to something
31 suitable for that item's I<data_type>, and stores the result in
32 I<< to->data >> as well as its size in I<< to->data_size >>.
33 I<< to->key >> and I<< to->data_type >> are assigned the corresponding
34 values from the item that was found, and I<< to->return_size >> is set
35 to zero.
36
37 I<< to->data >> is always allocated using L<OPENSSL_zalloc(3)> and
38 needs to be freed by the caller when it's not useful any more, using
39 L<OPENSSL_free(3)>.
40
41 If I<found> is not NULL, I<*found> is set to 1 if I<key> could be
42 located in I<paramdefs>, and to 0 otherwise.
43
44 =head2 The use of I<key> and I<value> in detail
45
46 OSSL_PARAM_allocate_from_text() takes note if I<key> starts with
47 "hex", and will only use the rest of I<key> to look up an item in
48 I<paramdefs> in that case.  As an example, if I<key> is "hexid", "id"
49 will be looked up in I<paramdefs>.
50
51 When an item in I<paramdefs> has been found, I<value> is converted
52 depending on that item's I<data_type>, as follows:
53
54 =over 4
55
56 =item B<OSSL_PARAM_INTEGER> and B<OSSL_PARAM_UNSIGNED_INTEGER>
57
58 If I<key> started with "hex", I<value> is assumed to contain
59 I<value_n> hexadecimal characters, which are decoded, and the
60 resulting bytes become the number stored in the I<< to->data >>
61 storage.
62
63 If I<key> didn't start with "hex", I<value> is assumed to contain
64 I<value_n> decimal characters, which are decoded, and the resulting
65 bytes become the number stored in the I<< to->data >> storage.
66
67 If I<value> contains characters that couldn't be decoded as
68 hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
69 considers that an error.
70
71 =item B<OSSL_PARAM_UTF8_STRING>
72
73 If I<key> started with "hex", OSSL_PARAM_allocate_from_text()
74 considers that an error.
75
76 Otherwise, I<value> is considered a C string and is copied with no
77 further checks to the I<< to->data >> storage.
78
79 =item B<OSSL_PARAM_OCTET_STRING>
80
81 If I<key> started with "hex", I<value> is assumed to contain
82 I<value_n> hexadecimal characters, which are decoded, and the
83 resulting bytes are stored in the I<< to->data >> storage.
84 If I<value> contains characters that couldn't be decoded as
85 hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
86 considers that an error.
87
88 If I<key> didn't start with "hex", I<value_n> bytes from I<value> are
89 copied to the I<< to->data >> storage.
90
91 =back
92
93 =head1 RETURN VALUES
94
95 OSSL_PARAM_allocate_from_text() returns 1 if I<key> was found in
96 I<paramdefs> and there was no other failure, otherwise 0.
97
98 =head1 NOTES
99
100 The parameter descriptor array comes from functions dedicated to
101 return them.
102 The following B<OSSL_PARAM> attributes are used:
103
104 =over 4
105
106 =item I<key>
107
108 =item I<data_type>
109
110 =item I<data_size>
111
112 =back
113
114 All other attributes are ignored.
115
116 The I<data_size> attribute can be zero, meaning that the parameter it
117 describes expects arbitrary length data.
118
119 =head1 EXAMPLES
120
121 Code that looked like this:
122
123   int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
124   {
125       int rv;
126       char *stmp, *vtmp = NULL;
127
128       stmp = OPENSSL_strdup(value);
129       if (stmp == NULL)
130           return -1;
131       vtmp = strchr(stmp, ':');
132       if (vtmp != NULL)
133           *vtmp++ = '\0';
134       rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
135       OPENSSL_free(stmp);
136       return rv;
137   }
138
139   ...
140
141
142   for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
143       char *macopt = sk_OPENSSL_STRING_value(macopts, i);
144
145       if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
146           BIO_printf(bio_err,
147                      "MAC parameter error \"%s\"\n", macopt);
148           ERR_print_errors(bio_err);
149           goto mac_end;
150       }
151   }
152
153 Can be written like this instead:
154
155   OSSL_PARAM *params =
156       OPENSSL_zalloc(sizeof(*params)
157                      * (sk_OPENSSL_STRING_num(opts) + 1));
158   const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
159   size_t params_n;
160   char *opt = "<unknown>";
161
162   for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
163        params_n++) {
164       char *stmp, *vtmp = NULL;
165
166       opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
167       if ((stmp = OPENSSL_strdup(opt)) == NULL
168               || (vtmp = strchr(stmp, ':')) == NULL)
169           goto err;
170
171       *vtmp++ = '\0';
172       if (!OSSL_PARAM_allocate_from_text(&params[params_n],
173                                          paramdefs, stmp,
174                                          vtmp, strlen(vtmp), NULL))
175           goto err;
176   }
177   params[params_n] = OSSL_PARAM_construct_end();
178   if (!EVP_MAC_CTX_set_params(ctx, params))
179       goto err;
180   while (params_n-- > 0)
181       OPENSSL_free(params[params_n].data);
182   OPENSSL_free(params);
183   /* ... */
184   return;
185
186  err:
187   BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
188   ERR_print_errors(bio_err);
189
190
191 =head1 SEE ALSO
192
193 L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)>
194
195 =head1 COPYRIGHT
196
197 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
198
199 Licensed under the Apache License 2.0 (the "License").  You may not use
200 this file except in compliance with the License.  You can obtain a copy
201 in the file LICENSE in the source distribution or at
202 L<https://www.openssl.org/source/license.html>.
203
204 =cut