5 OSSL_PARAM_allocate_from_text
6 - OSSL_PARAM construction utilities
10 #include <openssl/params.h>
12 int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
13 const OSSL_PARAM *paramdefs,
14 const char *key, const char *value,
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)>.
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).
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
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
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.
44 =head2 The use of I<key> and I<value> in detail
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>.
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:
56 =item B<OSSL_PARAM_INTEGER> and B<OSSL_PARAM_UNSIGNED_INTEGER>
58 If I<key> didn't start with "hex", I<value> is assumed to contain
59 I<value_n> decimal characters, which are decoded, and the resulting
60 bytes become the number stored in the I<< to->data >> storage.
62 If I<value> starts with "0x", it is assumed to contain I<value_n>
63 hexadecimal characters.
65 If I<key> started with "hex", I<value> is assumed to contain
66 I<value_n> hexadecimal characters without the "0x" prefix.
68 If I<value> contains characters that couldn't be decoded as
69 hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
70 considers that an error.
72 =item B<OSSL_PARAM_UTF8_STRING>
74 If I<key> started with "hex", OSSL_PARAM_allocate_from_text()
75 considers that an error.
77 Otherwise, I<value> is considered a C string and is copied to the
78 I<< to->data >> storage.
79 On systems where the native character encoding is EBCDIC, the bytes in
80 I<< to->data >> are converted to ASCII.
82 =item B<OSSL_PARAM_OCTET_STRING>
84 If I<key> started with "hex", I<value> is assumed to contain
85 I<value_n> hexadecimal characters, which are decoded, and the
86 resulting bytes are stored in the I<< to->data >> storage.
87 If I<value> contains characters that couldn't be decoded as
88 hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
89 considers that an error.
91 If I<key> didn't start with "hex", I<value_n> bytes from I<value> are
92 copied to the I<< to->data >> storage.
98 OSSL_PARAM_allocate_from_text() returns 1 if I<key> was found in
99 I<paramdefs> and there was no other failure, otherwise 0.
103 The parameter descriptor array comes from functions dedicated to
105 The following B<OSSL_PARAM> attributes are used:
117 All other attributes are ignored.
119 The I<data_size> attribute can be zero, meaning that the parameter it
120 describes expects arbitrary length data.
124 Code that looked like this:
126 int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
129 char *stmp, *vtmp = NULL;
131 stmp = OPENSSL_strdup(value);
134 vtmp = strchr(stmp, ':');
137 rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
145 for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
146 char *macopt = sk_OPENSSL_STRING_value(macopts, i);
148 if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
150 "MAC parameter error \"%s\"\n", macopt);
151 ERR_print_errors(bio_err);
156 Can be written like this instead:
159 OPENSSL_zalloc(sizeof(*params)
160 * (sk_OPENSSL_STRING_num(opts) + 1));
161 const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
163 char *opt = "<unknown>";
165 for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
167 char *stmp, *vtmp = NULL;
169 opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
170 if ((stmp = OPENSSL_strdup(opt)) == NULL
171 || (vtmp = strchr(stmp, ':')) == NULL)
175 if (!OSSL_PARAM_allocate_from_text(¶ms[params_n],
177 vtmp, strlen(vtmp), NULL))
180 params[params_n] = OSSL_PARAM_construct_end();
181 if (!EVP_MAC_CTX_set_params(ctx, params))
183 while (params_n-- > 0)
184 OPENSSL_free(params[params_n].data);
185 OPENSSL_free(params);
190 BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
191 ERR_print_errors(bio_err);
196 L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)>
200 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
202 Licensed under the Apache License 2.0 (the "License"). You may not use
203 this file except in compliance with the License. You can obtain a copy
204 in the file LICENSE in the source distribution or at
205 L<https://www.openssl.org/source/license.html>.