mirror of https://github.com/openssl/openssl.git
189 lines
6.9 KiB
Plaintext
189 lines
6.9 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
ossl_param_bld_init, ossl_param_bld_to_param, ossl_param_bld_to_param_ex,
|
|
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_double,
|
|
ossl_param_bld_push_BN, 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
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=for comment generic
|
|
|
|
#include "internal/params_build.h"
|
|
|
|
#define OSSL_PARAM_BLD_MAX 10
|
|
typedef struct { ... } OSSL_PARAM_BLD;
|
|
|
|
void ossl_param_bld_init(OSSL_PARAM_BLD *bld);
|
|
OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld);
|
|
OSSL_PARAM *ossl_param_bld_to_param_ex(OSSL_PARAM_BLD *bld,
|
|
OSSL_PARAM *params, size_t param_n,
|
|
void *data, size_t data_n,
|
|
void *secure, size_t secure_n);
|
|
void ossl_param_bld_free(OSSL_PARAM *params);
|
|
|
|
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_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
|
|
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,
|
|
void *buf, size_t bsize);
|
|
int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
|
|
void *buf, size_t bsize);
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
A collection of utility functions that simplify the creation of OSSL_PARAM
|
|
arrays. The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
|
|
|
|
ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
|
|
can be added.
|
|
Any existing values are cleared.
|
|
|
|
ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure
|
|
B<bld> into an allocated OSSL_PARAM array.
|
|
The OSSL_PARAM array and all associated storage must be freed by calling
|
|
ossl_param_bld_free() with the functions return value.
|
|
|
|
ossl_param_bld_free() deallocates the memory allocated by
|
|
ossl_param_bld_to_param().
|
|
|
|
ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that
|
|
no additional memory is allocated.
|
|
An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>.
|
|
The auxiliary storage for the parameters is a block of memory pointed to
|
|
by B<data> of at least B<data_n> bytes in size.
|
|
If required, secure memory for private BIGNUMs should be pointed to by
|
|
B<secure> of at least B<secure_n> bytes in size.
|
|
|
|
ossl_param_bld_push_TYPE() are a series of functions which will create
|
|
OSSL_PARAM objects of the specified size and correct type for the B<val>
|
|
argument.
|
|
B<val> is stored by value and an expression or auto variable can be used.
|
|
|
|
ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
|
|
that holds the specified BIGNUM B<bn>.
|
|
If B<bn> is marked as being securely allocated, it's OSSL_PARAM representation
|
|
will also be securely allocated.
|
|
The B<bn> argument is stored by reference and the underlying BIGNUM object
|
|
must exist until after ossl_param_bld_to_param() has been called.
|
|
|
|
ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM
|
|
object that references the UTF8 string specified by B<buf>.
|
|
If the length of the string, B<bsize>, is zero then it will be calculated.
|
|
The string that B<buf> points to is stored by reference and must remain in
|
|
scope until after ossl_param_bld_to_param() has been called.
|
|
|
|
ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM
|
|
object that references the octet string specified by B<buf> and <bsize>.
|
|
The memory that B<buf> points to is stored by reference and must remain in
|
|
scope until after ossl_param_bld_to_param() has been called.
|
|
|
|
ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM
|
|
object that references the UTF8 string specified by B<buf>.
|
|
If the length of the string, B<bsize>, is zero then it will be calculated.
|
|
The string B<buf> points to is stored by reference and must remain in
|
|
scope until the OSSL_PARAM array is freed.
|
|
|
|
ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM
|
|
object that references the octet string specified by B<buf>.
|
|
The memory B<buf> points to is stored by reference and must remain in
|
|
scope until the OSSL_PARAM array is freed.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the
|
|
allocated OSSL_PARAM array, or NULL on error.
|
|
|
|
All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
|
|
on error.
|
|
|
|
=head1 NOTES
|
|
|
|
The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters
|
|
that can be added.
|
|
Exceeding this will result in the push functions returning errors.
|
|
|
|
The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to
|
|
change between versions.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Both examples creating an OSSL_PARAM array that contains an RSA key.
|
|
For both, the predefined key variables are:
|
|
|
|
BIGNUM *p, *q; /* both prime */
|
|
BIGNUM *n; /* = p * q */
|
|
unsigned int e; /* exponent, usually 65537 */
|
|
BIGNUM *d; /* e^-1 */
|
|
|
|
=head2 Example 1
|
|
|
|
This example shows how to create an OSSL_PARAM array that contains an RSA
|
|
private key.
|
|
|
|
OSSL_PARAM_BLD bld;
|
|
OSSL_PARAM *params;
|
|
|
|
ossl_param_bld_init(&bld, &secure);
|
|
if (!ossl_param_bld_push_BN(&bld, "p", p)
|
|
|| !ossl_param_bld_push_BN(&bld, "q", q)
|
|
|| !ossl_param_bld_push_uint(&bld, "e", e)
|
|
|| !ossl_param_bld_push_BN(&bld, "n", n)
|
|
|| !ossl_param_bld_push_BN(&bld, "d", d)
|
|
|| (params = ossl_param_bld_to_param(&bld)) == NULL)
|
|
goto err;
|
|
/* Use params */
|
|
...
|
|
ossl_param_bld_free(params);
|
|
|
|
=head2 Example 2
|
|
|
|
This example shows how to create an OSSL_PARAM array that contains an RSA
|
|
public key.
|
|
|
|
OSSL_PARAM_BLD bld;
|
|
OSSL_PARAM *params;
|
|
|
|
ossl_param_bld_init(&bld, &secure);
|
|
if (!ossl_param_bld_push_BN(&bld, "n", n)
|
|
|| !ossl_param_bld_push_BN(&bld, "d", d)
|
|
|| (params = ossl_param_bld_to_param(&bld)) == NULL)
|
|
goto err;
|
|
/* Use params */
|
|
...
|
|
ossl_param_bld_free(params);
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<OSSL_PARAM_int>, L<OSSL_PARAM>
|
|
|
|
=head1 HISTORY
|
|
|
|
The functions described here were all added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
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
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|