1OSSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)OpenSSLOSSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)
2
3
4

NAME

6       OSSL_PARAM_allocate_from_text - OSSL_PARAM construction utilities
7

SYNOPSIS

9        #include <openssl/params.h>
10
11        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

DESCRIPTION

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
23       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
27       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
34       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
38       If found is not NULL, *found is set to 1 if key could be located in
39       paramdefs, and to 0 otherwise.
40
41   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
47       When an item in paramdefs has been found, value is converted depending
48       on that item's data_type, as follows:
49
50       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
55           If value starts with "0x", it is assumed to contain value_n
56           hexadecimal characters.
57
58           If key started with "hex", value is assumed to contain value_n
59           hexadecimal characters without the "0x" prefix.
60
61           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
65       OSSL_PARAM_UTF8_STRING
66           If key started with "hex", OSSL_PARAM_allocate_from_text()
67           considers that an error.
68
69           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
73       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
80           If key didn't start with "hex", value_n bytes from value are copied
81           to the to->data storage.
82

RETURN VALUES

84       OSSL_PARAM_allocate_from_text() returns 1 if key was found in paramdefs
85       and there was no other failure, otherwise 0.
86

NOTES

88       The parameter descriptor array comes from functions dedicated to return
89       them.  The following OSSL_PARAM(3) attributes are used:
90
91       key
92       data_type
93       data_size
94
95       All other attributes are ignored.
96
97       The data_size attribute can be zero, meaning that the parameter it
98       describes expects arbitrary length data.
99

EXAMPLES

101       Code that looked like this:
102
103         int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
104         {
105             int rv;
106             char *stmp, *vtmp = NULL;
107
108             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
119         ...
120
121
122         for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
123             char *macopt = sk_OPENSSL_STRING_value(macopts, i);
124
125             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
133       Can be written like this instead:
134
135         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
142         for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
143              params_n++) {
144             char *stmp, *vtmp = NULL;
145
146             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
151             *vtmp++ = '\0';
152             if (!OSSL_PARAM_allocate_from_text(&params[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
166        err:
167         BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
168         ERR_print_errors(bio_err);
169

SEE ALSO

171       OSSL_PARAM(3), OSSL_PARAM_int(3)
172
174       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
175
176       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>.
180
181
182
1833.1.1                             2023-08-3O1SSL_PARAM_ALLOCATE_FROM_TEXT(3ossl)
Impressum