Fix doc example code to follow coding style
[openssl.git] / doc / man3 / OSSL_PARAM_construct_from_text.pod
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
93       stmp = OPENSSL_strdup(value);
94       if (stmp == NULL)
95           return -1;
96       vtmp = strchr(stmp, ':');
97       if (vtmp != NULL)
98           *vtmp++ = '\0';
99       rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
100       OPENSSL_free(stmp);
101       return rv;
102   }
103
104   ...
105
106
107   for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
108       char *macopt = sk_OPENSSL_STRING_value(macopts, i);
109
110       if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
111           BIO_printf(bio_err,
112                      "MAC parameter error \"%s\"\n", macopt);
113           ERR_print_errors(bio_err);
114           goto mac_end;
115       }
116   }
117
118 Can be written like this instead:
119
120   OSSL_PARAM *params =
121       OPENSSL_zalloc(sizeof(*params)
122                      * (sk_OPENSSL_STRING_num(opts) + 1));
123   const OSSL_PARAM *paramdefs = EVP_MAC_CTX_set_param_types(mac);
124   size_t params_n;
125   char *opt = "<unknown>";
126
127   for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
128        params_n++) {
129       char *stmp, *vtmp = NULL;
130
131       opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
132       if ((stmp = OPENSSL_strdup(opt)) == NULL
133               || (vtmp = strchr(stmp, ':')) == NULL)
134           goto err;
135
136       *vtmp++ = '\0';
137       if (!OSSL_PARAM_allocate_from_text(&params[params_n],
138                                          paramdefs, stmp,
139                                          vtmp, strlen(vtmp)))
140           goto err;
141   }
142   params[params_n] = OSSL_PARAM_construct_end();
143   if (!EVP_MAC_CTX_set_params(ctx, params))
144       goto err;
145   while (params_n-- > 0)
146       OPENSSL_free(params[params_n].data);
147   OPENSSL_free(params);
148   /* ... */
149   return;
150
151  err:
152   BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
153   ERR_print_errors(bio_err);
154
155
156 =head1 SEE ALSO
157
158 L<OSSL_PARAM(3)>, L<OSSL_PARAM_TYPE(3)>
159
160 =head1 COPYRIGHT
161
162 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
163
164 Licensed under the Apache License 2.0 (the "License").  You may not use
165 this file except in compliance with the License.  You can obtain a copy
166 in the file LICENSE in the source distribution or at
167 L<https://www.openssl.org/source/license.html>.
168
169 =cut