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