1OSSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)OpenSSLOSSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)
2
6 OSSL_PARAM_allocate_from_text - OSSL_PARAM construction utilities
7
9 #include <openssl/params.h>
10 int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
12 const OSSL_PARAM *paramdefs,
13 const char *key, const char *value,
14 size_t value_n,
15 int *found);
16
18 With OpenSSL before version 3.0, parameters were passed down to or
19 retrieved from algorithm implementations via control functions. Some
20 of these control functions existed in variants that took string
21 parameters, for example EVP_PKEY_CTX_ctrl_str(3).
22 OpenSSL 3.0 introduces a new mechanism to do the same thing with an
24 array of parameters that contain name, value, value type and value size
25 (see OSSL_PARAM(3) for more information).
26 OSSL_PARAM_allocate_from_text() uses key to look up an item in
28 paramdefs. If an item was found, it converts value to something
29 suitable for that item's data_type, and stores the result in to->data
30 as well as its size in to->data_size. to->key and to->data_type are
31 assigned the corresponding values from the item that was found, and
32 to->return_size is set to zero.
33 to->data is always allocated using OPENSSL_zalloc(3) and needs to be
35 freed by the caller when it's not useful any more, using
36 OPENSSL_free(3).
37 If found is not NULL, *found is set to 1 if key could be located in
39 paramdefs, and to 0 otherwise.
40 The use of key and value in detail
42 OSSL_PARAM_allocate_from_text() takes note if key starts with "hex",
43 and will only use the rest of key to look up an item in paramdefs in
44 that case. As an example, if key is "hexid", "id" will be looked up in
45 paramdefs.
46 When an item in paramdefs has been found, value is converted depending
48 on that item's data_type, as follows:
49 OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER
51 If key didn't start with "hex", value is assumed to contain value_n
52 decimal characters, which are decoded, and the resulting bytes
53 become the number stored in the to->data storage.
54 If value starts with "0x", it is assumed to contain value_n
56 hexadecimal characters.
57 If key started with "hex", value is assumed to contain value_n
59 hexadecimal characters without the "0x" prefix.
60 If value contains characters that couldn't be decoded as
62 hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
63 considers that an error.
64 OSSL_PARAM_UTF8_STRING
66 If key started with "hex", OSSL_PARAM_allocate_from_text()
67 considers that an error.
68 Otherwise, value is considered a C string and is copied to the
70 to->data storage. On systems where the native character encoding
71 is EBCDIC, the bytes in to->data are converted to ASCII.
72 OSSL_PARAM_OCTET_STRING
74 If key started with "hex", value is assumed to contain value_n
75 hexadecimal characters, which are decoded, and the resulting bytes
76 are stored in the to->data storage. If value contains characters
77 that couldn't be decoded as hexadecimal or decimal characters,
78 OSSL_PARAM_allocate_from_text() considers that an error.
79 If key didn't start with "hex", value_n bytes from value are copied
81 to the to->data storage.
82
84 OSSL_PARAM_allocate_from_text() returns 1 if key was found in paramdefs
85 and there was no other failure, otherwise 0.
86
88 The parameter descriptor array comes from functions dedicated to return
89 them. The following OSSL_PARAM(3) attributes are used:
90 key
92 data_type
93 data_size
94 All other attributes are ignored.
96 The data_size attribute can be zero, meaning that the parameter it
98 describes expects arbitrary length data.
99
101 Code that looked like this:
102 int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
104 {
105 int rv;
106 char *stmp, *vtmp = NULL;
107 stmp = OPENSSL_strdup(value);
109 if (stmp == NULL)
110 return -1;
111 vtmp = strchr(stmp, ':');
112 if (vtmp != NULL)
113 *vtmp++ = '\0';
114 rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
115 OPENSSL_free(stmp);
116 return rv;
117 }
118 ...
120 for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
123 char *macopt = sk_OPENSSL_STRING_value(macopts, i);
124 if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
126 BIO_printf(bio_err,
127 "MAC parameter error \"%s\"\n", macopt);
128 ERR_print_errors(bio_err);
129 goto mac_end;
130 }
131 }
132 Can be written like this instead:
134 OSSL_PARAM *params =
136 OPENSSL_zalloc(sizeof(*params)
137 * (sk_OPENSSL_STRING_num(opts) + 1));
138 const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
139 size_t params_n;
140 char *opt = "<unknown>";
141 for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
143 params_n++) {
144 char *stmp, *vtmp = NULL;
145 opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
147 if ((stmp = OPENSSL_strdup(opt)) == NULL
148 || (vtmp = strchr(stmp, ':')) == NULL)
149 goto err;
150 *vtmp++ = '\0';
152 if (!OSSL_PARAM_allocate_from_text(¶ms[params_n],
153 paramdefs, stmp,
154 vtmp, strlen(vtmp), NULL))
155 goto err;
156 }
157 params[params_n] = OSSL_PARAM_construct_end();
158 if (!EVP_MAC_CTX_set_params(ctx, params))
159 goto err;
160 while (params_n-- > 0)
161 OPENSSL_free(params[params_n].data);
162 OPENSSL_free(params);
163 /* ... */
164 return;
165 err:
167 BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
168 ERR_print_errors(bio_err);
169
171 OSSL_PARAM(3), OSSL_PARAM_int(3)
172
174 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
175 Licensed under the Apache License 2.0 (the "License"). You may not use
177 this file except in compliance with the License. You can obtain a copy
178 in the file LICENSE in the source distribution or at
179 <https://www.openssl.org/source/license.html>.
1803.1.1 2023-08-3O1SSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)