]>
Commit | Line | Data |
---|---|---|
246a1f3d RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
99b9aa95 | 5 | OSSL_PARAM_allocate_from_text |
246a1f3d RL |
6 | - OSSL_PARAM construction utilities |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/params.h> | |
11 | ||
246a1f3d RL |
12 | int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to, |
13 | const OSSL_PARAM *paramdefs, | |
14 | const char *key, const char *value, | |
2ee0dfa6 P |
15 | size_t value_n, |
16 | int *found); | |
246a1f3d RL |
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 | ||
99b9aa95 | 29 | OSSL_PARAM_allocate_from_text() takes a control I<key>, I<value> and |
246a1f3d RL |
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 | |
35 | I<buf>. | |
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 | |
38 | should be. | |
39 | I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM> | |
40 | I<key>. | |
2ee0dfa6 P |
41 | If <found> is not NULL, it is set to 1 if the parameter can be located and |
42 | to 0 otherwise. | |
43 | ||
246a1f3d RL |
44 | The caller must remember to free the data of I<to> when it's not |
45 | useful any more. | |
46 | ||
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 | |
50 | with "hex". | |
51 | In that case, the value is decoded first, and the result will be used | |
52 | as parameter value. | |
53 | ||
54 | =head1 RETURN VALUES | |
55 | ||
99b9aa95 | 56 | OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error. |
246a1f3d RL |
57 | |
58 | =head1 NOTES | |
59 | ||
60 | The parameter descriptor array comes from functions dedicated to | |
61 | return them. | |
62 | The following B<OSSL_PARAM> attributes are used: | |
63 | ||
64 | =over 4 | |
65 | ||
66 | =item I<key> | |
67 | ||
68 | =item I<data> | |
69 | ||
70 | =item I<data_size> | |
71 | ||
72 | =back | |
73 | ||
74 | All other attributes are ignored. | |
75 | ||
76 | The I<data_size> attribute can be zero, meaning that the parameter it | |
77 | describes expects arbitrary length data. | |
78 | ||
cda77422 | 79 | =head1 EXAMPLES |
246a1f3d RL |
80 | |
81 | Code that looked like this: | |
82 | ||
83 | int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value) | |
84 | { | |
85 | int rv; | |
86 | char *stmp, *vtmp = NULL; | |
697b0c51 | 87 | |
246a1f3d | 88 | stmp = OPENSSL_strdup(value); |
697b0c51 | 89 | if (stmp == NULL) |
246a1f3d RL |
90 | return -1; |
91 | vtmp = strchr(stmp, ':'); | |
697b0c51 RS |
92 | if (vtmp != NULL) |
93 | *vtmp++ = '\0'; | |
246a1f3d RL |
94 | rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp); |
95 | OPENSSL_free(stmp); | |
96 | return rv; | |
97 | } | |
98 | ||
99 | ... | |
100 | ||
101 | ||
246a1f3d | 102 | for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) { |
697b0c51 RS |
103 | char *macopt = sk_OPENSSL_STRING_value(macopts, i); |
104 | ||
246a1f3d RL |
105 | if (pkey_ctrl_string(mac_ctx, macopt) <= 0) { |
106 | BIO_printf(bio_err, | |
107 | "MAC parameter error \"%s\"\n", macopt); | |
108 | ERR_print_errors(bio_err); | |
109 | goto mac_end; | |
110 | } | |
111 | } | |
112 | ||
113 | Can be written like this instead: | |
114 | ||
115 | OSSL_PARAM *params = | |
697b0c51 | 116 | OPENSSL_zalloc(sizeof(*params) |
246a1f3d | 117 | * (sk_OPENSSL_STRING_num(opts) + 1)); |
41f7ecf3 | 118 | const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac); |
246a1f3d | 119 | size_t params_n; |
697b0c51 | 120 | char *opt = "<unknown>"; |
246a1f3d RL |
121 | |
122 | for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts); | |
123 | params_n++) { | |
246a1f3d RL |
124 | char *stmp, *vtmp = NULL; |
125 | ||
697b0c51 | 126 | opt = sk_OPENSSL_STRING_value(opts, (int)params_n); |
246a1f3d | 127 | if ((stmp = OPENSSL_strdup(opt)) == NULL |
697b0c51 RS |
128 | || (vtmp = strchr(stmp, ':')) == NULL) |
129 | goto err; | |
130 | ||
131 | *vtmp++ = '\0'; | |
132 | if (!OSSL_PARAM_allocate_from_text(¶ms[params_n], | |
133 | paramdefs, stmp, | |
2ee0dfa6 | 134 | vtmp, strlen(vtmp), NULL)) |
246a1f3d | 135 | goto err; |
246a1f3d RL |
136 | } |
137 | params[params_n] = OSSL_PARAM_construct_end(); | |
697b0c51 | 138 | if (!EVP_MAC_CTX_set_params(ctx, params)) |
246a1f3d | 139 | goto err; |
697b0c51 | 140 | while (params_n-- > 0) |
246a1f3d | 141 | OPENSSL_free(params[params_n].data); |
246a1f3d | 142 | OPENSSL_free(params); |
697b0c51 RS |
143 | /* ... */ |
144 | return; | |
145 | ||
146 | err: | |
147 | BIO_printf(bio_err, "MAC parameter error '%s'\n", opt); | |
148 | ERR_print_errors(bio_err); | |
149 | ||
246a1f3d RL |
150 | |
151 | =head1 SEE ALSO | |
152 | ||
1b0d1bf7 | 153 | L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)> |
246a1f3d RL |
154 | |
155 | =head1 COPYRIGHT | |
156 | ||
157 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
158 | ||
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>. | |
163 | ||
164 | =cut |