c16491e702ed5e0a6a4089dba5ca4a5f6c96b352
[openssl.git] / doc / man3 / OSSL_PARAM_allocate_from_text.pod
1 =pod
2
3 =head1 NAME
4
5 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_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
28 OSSL_PARAM_allocate_from_text() takes a control I<key>, I<value> and
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>.
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
52 OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error.
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
75 =head1 EXAMPLES
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;
83
84       stmp = OPENSSL_strdup(value);
85       if (stmp == NULL)
86           return -1;
87       vtmp = strchr(stmp, ':');
88       if (vtmp != NULL)
89           *vtmp++ = '\0';
90       rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
91       OPENSSL_free(stmp);
92       return rv;
93   }
94
95   ...
96
97
98   for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
99       char *macopt = sk_OPENSSL_STRING_value(macopts, i);
100
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 =
112       OPENSSL_zalloc(sizeof(*params)
113                      * (sk_OPENSSL_STRING_num(opts) + 1));
114   const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
115   size_t params_n;
116   char *opt = "<unknown>";
117
118   for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
119        params_n++) {
120       char *stmp, *vtmp = NULL;
121
122       opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
123       if ((stmp = OPENSSL_strdup(opt)) == NULL
124               || (vtmp = strchr(stmp, ':')) == NULL)
125           goto err;
126
127       *vtmp++ = '\0';
128       if (!OSSL_PARAM_allocate_from_text(&params[params_n],
129                                          paramdefs, stmp,
130                                          vtmp, strlen(vtmp)))
131           goto err;
132   }
133   params[params_n] = OSSL_PARAM_construct_end();
134   if (!EVP_MAC_CTX_set_params(ctx, params))
135       goto err;
136   while (params_n-- > 0)
137       OPENSSL_free(params[params_n].data);
138   OPENSSL_free(params);
139   /* ... */
140   return;
141
142  err:
143   BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
144   ERR_print_errors(bio_err);
145
146
147 =head1 SEE ALSO
148
149 L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)>
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