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() takes a control I<key>, I<value> and
30 value size I<value_n>, and given a parameter descriptor array
31 I<paramdefs>, it converts the value to something suitable for
32 L<OSSL_PARAM(3)> and stores that in the buffer I<buf>, and modifies
33 the parameter I<to> to match.
34 I<buf_n>, if not NULL, will be assigned the number of bytes used in
36 If I<buf> is NULL, only I<buf_n> will be modified, everything else is
37 left untouched, allowing a caller to find out how large the buffer
39 I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM>
41 If <found> is not NULL, it is set to 1 if the parameter can be located and
44 The caller must remember to free the data of I<to> when it's not
47 For parameters having the type B<OSSL_PARAM_INTEGER>,
48 B<OSSL_PARAM_UNSIGNED_INTEGER>, or B<OSSL_PARAM_OCTET_STRING>, both
49 functions will interpret the I<value> differently if the key starts
51 In that case, the value is decoded first, and the result will be used
56 OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error.
60 The parameter descriptor array comes from functions dedicated to
62 The following B<OSSL_PARAM> attributes are used:
74 All other attributes are ignored.
76 The I<data_size> attribute can be zero, meaning that the parameter it
77 describes expects arbitrary length data.
81 Code that looked like this:
83 int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
86 char *stmp, *vtmp = NULL;
88 stmp = OPENSSL_strdup(value);
91 vtmp = strchr(stmp, ':');
94 rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
102 for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
103 char *macopt = sk_OPENSSL_STRING_value(macopts, i);
105 if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
107 "MAC parameter error \"%s\"\n", macopt);
108 ERR_print_errors(bio_err);
113 Can be written like this instead:
116 OPENSSL_zalloc(sizeof(*params)
117 * (sk_OPENSSL_STRING_num(opts) + 1));
118 const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
120 char *opt = "<unknown>";
122 for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
124 char *stmp, *vtmp = NULL;
126 opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
127 if ((stmp = OPENSSL_strdup(opt)) == NULL
128 || (vtmp = strchr(stmp, ':')) == NULL)
132 if (!OSSL_PARAM_allocate_from_text(¶ms[params_n],
134 vtmp, strlen(vtmp), NULL))
137 params[params_n] = OSSL_PARAM_construct_end();
138 if (!EVP_MAC_CTX_set_params(ctx, params))
140 while (params_n-- > 0)
141 OPENSSL_free(params[params_n].data);
142 OPENSSL_free(params);
147 BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
148 ERR_print_errors(bio_err);
153 L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)>
157 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
159 Licensed under the Apache License 2.0 (the "License"). You may not use
160 this file except in compliance with the License. You can obtain a copy
161 in the file LICENSE in the source distribution or at
162 L<https://www.openssl.org/source/license.html>.