]>
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, | |
15 | size_t value_n); | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
19 | With OpenSSL before version 3.0, parameters were passed down to or | |
20 | retrieved from algorithm implementations via control functions. | |
21 | Some of these control functions existed in variants that took string | |
22 | parameters, for example L<EVP_PKEY_CTX_ctrl_str(3)>. | |
23 | ||
24 | OpenSSL 3.0 introduces a new mechanism to do the same thing with an | |
25 | array of parameters that contain name, value, value type and value | |
26 | size (see L<OSSL_PARAM(3)> for more information). | |
27 | ||
99b9aa95 | 28 | OSSL_PARAM_allocate_from_text() takes a control I<key>, I<value> and |
246a1f3d RL |
29 | value size I<value_n>, and given a parameter descriptor array |
30 | I<paramdefs>, it converts the value to something suitable for | |
31 | L<OSSL_PARAM(3)> and stores that in the buffer I<buf>, and modifies | |
32 | the parameter I<to> to match. | |
33 | I<buf_n>, if not NULL, will be assigned the number of bytes used in | |
34 | I<buf>. | |
35 | If I<buf> is NULL, only I<buf_n> will be modified, everything else is | |
36 | left untouched, allowing a caller to find out how large the buffer | |
37 | should be. | |
38 | I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM> | |
39 | I<key>. | |
246a1f3d RL |
40 | The caller must remember to free the data of I<to> when it's not |
41 | useful any more. | |
42 | ||
43 | For parameters having the type B<OSSL_PARAM_INTEGER>, | |
44 | B<OSSL_PARAM_UNSIGNED_INTEGER>, or B<OSSL_PARAM_OCTET_STRING>, both | |
45 | functions will interpret the I<value> differently if the key starts | |
46 | with "hex". | |
47 | In that case, the value is decoded first, and the result will be used | |
48 | as parameter value. | |
49 | ||
50 | =head1 RETURN VALUES | |
51 | ||
99b9aa95 | 52 | OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error. |
246a1f3d RL |
53 | |
54 | =head1 NOTES | |
55 | ||
56 | The parameter descriptor array comes from functions dedicated to | |
57 | return them. | |
58 | The following B<OSSL_PARAM> attributes are used: | |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item I<key> | |
63 | ||
64 | =item I<data> | |
65 | ||
66 | =item I<data_size> | |
67 | ||
68 | =back | |
69 | ||
70 | All other attributes are ignored. | |
71 | ||
72 | The I<data_size> attribute can be zero, meaning that the parameter it | |
73 | describes expects arbitrary length data. | |
74 | ||
cda77422 | 75 | =head1 EXAMPLES |
246a1f3d RL |
76 | |
77 | Code that looked like this: | |
78 | ||
79 | int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value) | |
80 | { | |
81 | int rv; | |
82 | char *stmp, *vtmp = NULL; | |
697b0c51 | 83 | |
246a1f3d | 84 | stmp = OPENSSL_strdup(value); |
697b0c51 | 85 | if (stmp == NULL) |
246a1f3d RL |
86 | return -1; |
87 | vtmp = strchr(stmp, ':'); | |
697b0c51 RS |
88 | if (vtmp != NULL) |
89 | *vtmp++ = '\0'; | |
246a1f3d RL |
90 | rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp); |
91 | OPENSSL_free(stmp); | |
92 | return rv; | |
93 | } | |
94 | ||
95 | ... | |
96 | ||
97 | ||
246a1f3d | 98 | for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) { |
697b0c51 RS |
99 | char *macopt = sk_OPENSSL_STRING_value(macopts, i); |
100 | ||
246a1f3d RL |
101 | if (pkey_ctrl_string(mac_ctx, macopt) <= 0) { |
102 | BIO_printf(bio_err, | |
103 | "MAC parameter error \"%s\"\n", macopt); | |
104 | ERR_print_errors(bio_err); | |
105 | goto mac_end; | |
106 | } | |
107 | } | |
108 | ||
109 | Can be written like this instead: | |
110 | ||
111 | OSSL_PARAM *params = | |
697b0c51 | 112 | OPENSSL_zalloc(sizeof(*params) |
246a1f3d | 113 | * (sk_OPENSSL_STRING_num(opts) + 1)); |
41f7ecf3 | 114 | const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac); |
246a1f3d | 115 | size_t params_n; |
697b0c51 | 116 | char *opt = "<unknown>"; |
246a1f3d RL |
117 | |
118 | for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts); | |
119 | params_n++) { | |
246a1f3d RL |
120 | char *stmp, *vtmp = NULL; |
121 | ||
697b0c51 | 122 | opt = sk_OPENSSL_STRING_value(opts, (int)params_n); |
246a1f3d | 123 | if ((stmp = OPENSSL_strdup(opt)) == NULL |
697b0c51 RS |
124 | || (vtmp = strchr(stmp, ':')) == NULL) |
125 | goto err; | |
126 | ||
127 | *vtmp++ = '\0'; | |
128 | if (!OSSL_PARAM_allocate_from_text(¶ms[params_n], | |
129 | paramdefs, stmp, | |
130 | vtmp, strlen(vtmp))) | |
246a1f3d | 131 | goto err; |
246a1f3d RL |
132 | } |
133 | params[params_n] = OSSL_PARAM_construct_end(); | |
697b0c51 | 134 | if (!EVP_MAC_CTX_set_params(ctx, params)) |
246a1f3d | 135 | goto err; |
697b0c51 | 136 | while (params_n-- > 0) |
246a1f3d | 137 | OPENSSL_free(params[params_n].data); |
246a1f3d | 138 | OPENSSL_free(params); |
697b0c51 RS |
139 | /* ... */ |
140 | return; | |
141 | ||
142 | err: | |
143 | BIO_printf(bio_err, "MAC parameter error '%s'\n", opt); | |
144 | ERR_print_errors(bio_err); | |
145 | ||
246a1f3d RL |
146 | |
147 | =head1 SEE ALSO | |
148 | ||
1b0d1bf7 | 149 | L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)> |
246a1f3d RL |
150 | |
151 | =head1 COPYRIGHT | |
152 | ||
153 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
154 | ||
155 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
156 | this file except in compliance with the License. You can obtain a copy | |
157 | in the file LICENSE in the source distribution or at | |
158 | L<https://www.openssl.org/source/license.html>. | |
159 | ||
160 | =cut |