1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "OSSL_PARAM_BLD 3SSL"
.TH OSSL_PARAM_BLD 3SSL 2024-04-04 3.2.2-dev OpenSSL
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
\&\- functions to assist in the creation of OSSL_PARAM arrays
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/param_build.h>
\&
\& typedef struct OSSL_PARAM_BLD;
\&
\& OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
\& OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
\& void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
\&
\& int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
\&
\& int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
\& const BIGNUM *bn);
\& int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
\& const BIGNUM *bn, size_t sz);
\&
\& int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
\& const char *buf, size_t bsize);
\& int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
\& char *buf, size_t bsize);
\& int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
\& const void *buf, size_t bsize);
\& int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
\& void *buf, size_t bsize);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A collection of utility functions that simplify the creation of OSSL_PARAM
arrays. The \fR\f(BITYPE\fR\fB\fR names are as per \fBOSSL_PARAM_int\fR\|(3).
.PP
\&\fBOSSL_PARAM_BLD_new()\fR allocates and initialises a new OSSL_PARAM_BLD structure
so that values can be added.
Any existing values are cleared.
.PP
\&\fBOSSL_PARAM_BLD_free()\fR deallocates the memory allocates by \fBOSSL_PARAM_BLD_new()\fR.
.PP
\&\fBOSSL_PARAM_BLD_to_param()\fR converts a built up OSSL_PARAM_BLD structure
\&\fIbld\fR into an allocated OSSL_PARAM array.
The OSSL_PARAM array and all associated storage must be freed by calling
\&\fBOSSL_PARAM_free()\fR with the functions return value.
\&\fBOSSL_PARAM_BLD_free()\fR can safely be called any time after this function is.
.PP
\&\fBOSSL_PARAM_BLD_push_\fR\f(BITYPE\fR() are a series of functions which will create
OSSL_PARAM objects of the specified size and correct type for the \fIval\fR
argument.
\&\fIval\fR is stored by value and an expression or auto variable can be used.
.PP
When \fR\f(BITYPE\fR\fB\fR denotes an integer type, signed integer types will normally
get the OSSL_PARAM type \fBOSSL_PARAM_INTEGER\fR params.
When \fB\fR\f(BITYPE\fR\fB\fR denotes an unsigned integer type will get the OSSL_PARAM type
\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
.PP
\&\fBOSSL_PARAM_BLD_push_BN()\fR is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM \fIbn\fR.
When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes
\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR.
If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
The \fIbn\fR argument is stored by reference and the underlying BIGNUM object
must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
.PP
\&\fBOSSL_PARAM_BLD_push_BN_pad()\fR is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM \fIbn\fR.
The object will be padded to occupy exactly \fIsz\fR bytes, if insufficient space
is specified an error results.
When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes
\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR.
When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR.
If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
The \fIbn\fR argument is stored by reference and the underlying BIGNUM object
must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
.PP
\&\fBOSSL_PARAM_BLD_push_utf8_string()\fR is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by \fIbuf\fR.
The length of the string \fIbsize\fR should not include the terminating NUL byte.
If it is zero then it will be calculated.
The string that \fIbuf\fR points to is stored by reference and must remain in
scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
.PP
\&\fBOSSL_PARAM_BLD_push_octet_string()\fR is a function that will create an OSSL_PARAM
object that references the octet string specified by \fIbuf\fR and <bsize>.
The memory that \fIbuf\fR points to is stored by reference and must remain in
scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called.
.PP
\&\fBOSSL_PARAM_BLD_push_utf8_ptr()\fR is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by \fIbuf\fR.
The length of the string \fIbsize\fR should not include the terminating NUL byte.
If it is zero then it will be calculated.
The string \fIbuf\fR points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
.PP
\&\fBOSSL_PARAM_BLD_push_octet_ptr()\fR is a function that will create an OSSL_PARAM
object that references the octet string specified by \fIbuf\fR.
The memory \fIbuf\fR points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBOSSL_PARAM_BLD_new()\fR returns the allocated OSSL_PARAM_BLD structure, or NULL
on error.
.PP
\&\fBOSSL_PARAM_BLD_to_param()\fR returns the allocated OSSL_PARAM array, or NULL
on error.
.PP
All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
on error.
.SH NOTES
.IX Header "NOTES"
\&\fBOSSL_PARAM_BLD_push_BN()\fR and \fBOSSL_PARAM_BLD_push_BN_pad()\fR only
support nonnegative \fBBIGNUM\fRs. They return an error on negative
\&\fBBIGNUM\fRs.
To pass signed \fBBIGNUM\fRs, use \fBOSSL_PARAM_BLD_push_signed_BN()\fR.
.SH EXAMPLES
.IX Header "EXAMPLES"
Both examples creating an OSSL_PARAM array that contains an RSA key.
For both, the predefined key variables are:
.PP
.Vb 6
\& BIGNUM *n; /* modulus */
\& unsigned int e; /* public exponent */
\& BIGNUM *d; /* private exponent */
\& BIGNUM *p, *q; /* first two prime factors */
\& BIGNUM *dmp1, *dmq1; /* first two CRT exponents */
\& BIGNUM *iqmp; /* first CRT coefficient */
.Ve
.SS "Example 1"
.IX Subsection "Example 1"
This example shows how to create an OSSL_PARAM array that contains an RSA
private key.
.PP
.Vb 2
\& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
\& OSSL_PARAM *params = NULL;
\&
\& if (bld == NULL
\& || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
\& || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
\& || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor1", p)
\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor2", q)
\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent1", dmp1)
\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent2", dmq1)
\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-coefficient1", iqmp)
\& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
\& goto err;
\& OSSL_PARAM_BLD_free(bld);
\& /* Use params */
\& ...
\& OSSL_PARAM_free(params);
.Ve
.SS "Example 2"
.IX Subsection "Example 2"
This example shows how to create an OSSL_PARAM array that contains an RSA
public key.
.PP
.Vb 2
\& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
\& OSSL_PARAM *params = NULL;
\&
\& if (nld == NULL
\& || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
\& || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
\& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
\& goto err;
\& OSSL_PARAM_BLD_free(bld);
\& /* Use params */
\& ...
\& OSSL_PARAM_free(params);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBOSSL_PARAM_int\fR\|(3), \fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_free\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
The functions described here were all added in OpenSSL 3.0.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
