wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Correct some OSSL_PARAM documentation

Browse source 
The documentation wasn't quite in sync with the implementation.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9408)
This commit is contained in:
Richard Levitte 2019-07-18 09:25:24 +02:00 committed by Pauli
parent 04edd688b3
commit a1c5cefaf4
2 changed files with 80 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
doc/internal/man3/ossl_param_bld_init.pod
View file

@ -2,15 +2,15 @@
=head1 NAME =head1 NAME
ossl_param_build_init, ossl_param_bld_init,
ossl_param_build_to_param, ossl_param_build_push_int, ossl_param_bld_to_param, ossl_param_bld_push_int,
ossl_param_build_push_uint, ossl_param_build_push_long, ossl_param_bld_push_uint, ossl_param_bld_push_long,
ossl_param_build_push_ulong, ossl_param_build_push_int32, ossl_param_bld_push_ulong, ossl_param_bld_push_int32,
ossl_param_build_push_uint32, ossl_param_build_push_int64, ossl_param_bld_push_uint32, ossl_param_bld_push_int64,
ossl_param_build_push_uint64, ossl_param_build_push_size_t, ossl_param_bld_push_uint64, ossl_param_bld_push_size_t,
ossl_param_build_push_double, ossl_param_build_push_BN, ossl_param_bld_push_double, ossl_param_bld_push_BN,
ossl_param_build_push_utf8_string, ossl_param_build_push_utf8_ptr, ossl_param_bld_push_utf8_string, ossl_param_bld_push_utf8_ptr,
ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr ossl_param_bld_push_octet_string, ossl_param_bld_push_octet_ptr
- functions to assist in the creation of OSSL_PARAM arrays - functions to assist in the creation of OSSL_PARAM arrays
=head1 SYNOPSIS =head1 SYNOPSIS
@ -22,25 +22,25 @@ ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr
#define OSSL_PARAM_BLD_MAX 10 #define OSSL_PARAM_BLD_MAX 10
typedef struct { ... } OSSL_PARAM_BLD; typedef struct { ... } OSSL_PARAM_BLD;
void ossl_param_build_init(OSSL_PARAM_BLD *bld); void ossl_param_bld_init(OSSL_PARAM_BLD *bld);
OSSL_PARAM *ossl_param_build_to_param(OSSL_PARAM_BLD *bld, void **secure); OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld, void **secure);
OSSL_PARAM *ossl_param_build_to_param_ex(OSSL_PARAM_BLD *bld, OSSL_PARAM *ossl_param_bld_to_param_ex(OSSL_PARAM_BLD *bld,
OSSL_PARAM *params, size_t param_n, OSSL_PARAM *params, size_t param_n,
void *data, size_t data_n, void *data, size_t data_n,
void *secure, size_t secure_n); void *secure, size_t secure_n);
int ossl_param_build_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val); int ossl_param_bld_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
int ossl_param_build_push_BN(OSSL_PARAM_BLD *bld, const char *key, int ossl_param_bld_push_BN(OSSL_PARAM_BLD *bld, const char *key,
const BIGNUM *bn); const BIGNUM *bn);
int ossl_param_build_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key, int ossl_param_bld_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
char *buf, size_t bsize); char *buf, size_t bsize);
int ossl_param_build_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key, int ossl_param_bld_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
char *buf, size_t bsize); char *buf, size_t bsize);
int ossl_param_build_push_octet_string(OSSL_PARAM_BLD *bld, const char *key, int ossl_param_bld_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
void *buf, size_t bsize); void *buf, size_t bsize);
int ossl_param_build_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key, int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
void *buf, size_t bsize); void *buf, size_t bsize);
@ -49,11 +49,11 @@ ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr
A collection of utility functions that simplify the creation of OSSL_PARAM 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)>. arrays. The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
ossl_param_build_init() initialises the OSSL_PARAM_BLD structure so that values ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
can be added. can be added.
Any existing values are cleared. Any existing values are cleared.
ossl_param_build_to_param() converts a built up OSSL_PARAM_BLD structure ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure
B<bld> into an allocated OSSL_PARAM array. B<bld> into an allocated OSSL_PARAM array.
The pointer referenced by the B<secure> argument is set to point to an The pointer referenced by the B<secure> argument is set to point to an
allocated block of secure memory if required and to NULL it not. allocated block of secure memory if required and to NULL it not.
@ -61,7 +61,7 @@ The OSSL_PARAM array and all associated storage can be freed by calling
OPENSSL_free() with the functions return value and OPENSSL_secure_free() OPENSSL_free() with the functions return value and OPENSSL_secure_free()
with the pointer referenced by B<secure>. with the pointer referenced by B<secure>.
ossl_param_build_to_param_ex() behaves like ossl_param_build_to_param(), except that ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that
no additional memory is allocated. no additional memory is allocated.
An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>. 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 The auxiliary storage for the parameters is a block of memory pointed to
@ -69,46 +69,46 @@ by B<data> of at least B<data_n> bytes in size.
If required, secure memory for private BIGNUMs should be pointed to by If required, secure memory for private BIGNUMs should be pointed to by
B<secure> of at least B<secure_n> bytes in size. B<secure> of at least B<secure_n> bytes in size.
ossl_param_build_push_TYPE() are a series of functions which will create 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> OSSL_PARAM objects of the specified size and correct type for the B<val>
argument. argument.
B<val> is stored by value and an expression or auto variable can be used. B<val> is stored by value and an expression or auto variable can be used.
ossl_param_build_push_BN() is a function that will create an OSSL_PARAM object ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM B<bn>. that holds the specified BIGNUM B<bn>.
If B<bn> is marked as being securely allocated, the secure flag is If B<bn> is marked as being securely allocated, the secure flag is
set in the OSSL_PARAM_BLD structure. set in the OSSL_PARAM_BLD structure.
The B<bn> argument is stored by reference and the underlying BIGNUM object The B<bn> argument is stored by reference and the underlying BIGNUM object
must exist until after ossl_param_build_to_param() has been called. must exist until after ossl_param_bld_to_param() has been called.
ossl_param_build_push_utf8_string() is a function that will create an OSSL_PARAM 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>. 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. 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 The string that B<buf> points to is stored by reference and must remain in
scope until after ossl_param_build_to_param() has been called. scope until after ossl_param_bld_to_param() has been called.
ossl_param_build_push_octet_string() is a function that will create an OSSL_PARAM 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>. 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 The memory that B<buf> points to is stored by reference and must remain in
scope until after ossl_param_build_to_param() has been called. scope until after ossl_param_bld_to_param() has been called.
ossl_param_build_push_utf8_ptr() is a function that will create an OSSL_PARAM 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>. 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. 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 The string B<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed. scope until the OSSL_PARAM array is freed.
ossl_param_build_push_octet_ptr() is a function that will create an OSSL_PARAM 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>. object that references the octet string specified by B<buf>.
The memory B<buf> points to is stored by reference and must remain in The memory B<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed. scope until the OSSL_PARAM array is freed.
=head1 RETURN VALUES =head1 RETURN VALUES
ossl_param_build_to_param() and ossl_param_bld_to_param_ex() return the ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the
allocated OSSL_PARAM array, or NULL on error. allocated OSSL_PARAM array, or NULL on error.
All of the ossl_param_build_push_TYPE functions return 1 on success and 0 All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
on error. on error.
=head1 NOTES =head1 NOTES
@ -139,13 +139,13 @@ private key.
OSSL_PARAM *params; OSSL_PARAM *params;
void *secure; void *secure;
ossl_param_build_init(&bld, &secure); ossl_param_bld_init(&bld, &secure);
if (!ossl_param_build_push_BN(&bld, "p", p) if (!ossl_param_bld_push_BN(&bld, "p", p)
|| !ossl_param_build_push_BN(&bld, "q", q) || !ossl_param_bld_push_BN(&bld, "q", q)
|| !ossl_param_build_push_uint(&bld, "e", e) || !ossl_param_bld_push_uint(&bld, "e", e)
|| !ossl_param_build_push_BN(&bld, "n", n) || !ossl_param_bld_push_BN(&bld, "n", n)
|| !ossl_param_build_push_BN(&bld, "d", d) || !ossl_param_bld_push_BN(&bld, "d", d)
|| (params = ossl_param_build_to_param(&bld)) == NULL) || (params = ossl_param_bld_to_param(&bld)) == NULL)
goto err; goto err;
/* Use params */ /* Use params */
... ...
@ -161,10 +161,10 @@ public key.
OSSL_PARAM *params; OSSL_PARAM *params;
void *secure; void *secure;
ossl_param_build_init(&bld, &secure); ossl_param_bld_init(&bld, &secure);
if (!ossl_param_build_push_BN(&bld, "n", n) if (!ossl_param_bld_push_BN(&bld, "n", n)
|| !ossl_param_build_push_BN(&bld, "d", d) || !ossl_param_bld_push_BN(&bld, "d", d)
|| (params = ossl_param_build_to_param(&bld)) == NULL) || (params = ossl_param_bld_to_param(&bld)) == NULL)
goto err; goto err;
/* Use params */ /* Use params */
... ...

63
doc/man3/OSSL_PARAM_int.pod
View file

@ -6,25 +6,27 @@ OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32,
OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double, OSSL_PARAM_END,
OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint, OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32,
OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong,
OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string,
OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string,
OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const, OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end,
OSSL_PARAM_locate, OSSL_PARAM_locate_const,
OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64,
OSSL_PARAM_get_ulong, OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string,
OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr,
OSSL_PARAM_set_size_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_get_octet_ptr,
OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
OSSL_PARAM_set_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64,
OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, OSSL_PARAM_set_utf8_string,
OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr,
OSSL_PARAM_set_octet_ptr OSSL_PARAM_set_octet_ptr
- OSSL_PARAM helpers - OSSL_PARAM helpers
@ -34,15 +36,23 @@ OSSL_PARAM_set_octet_ptr
#include <openssl/params.h> #include <openssl/params.h>
/*
* TYPE in function names is one of:
* double, int, int32, int64, long, size_t, uint, uint32, uint64, ulong
* Corresponding TYPE in function arguments is one of:
* double, int, int32_t, int64_t, long, size_t, unsigned int, uint32_t,
* uint64_t, unsigned long
*/
#define OSSL_PARAM_TYPE(key, address) #define OSSL_PARAM_TYPE(key, address)
#define OSSL_PARAM_BN(key, address, size)
#define OSSL_PARAM_utf8_string(key, address, size) #define OSSL_PARAM_utf8_string(key, address, size)
#define OSSL_PARAM_octet_string(key, address, size) #define OSSL_PARAM_octet_string(key, address, size)
#define OSSL_PARAM_utf8_ptr(key, address, size) #define OSSL_PARAM_utf8_ptr(key, address, size)
#define OSSL_PARAM_octet_ptr(key, address, size) #define OSSL_PARAM_octet_ptr(key, address, size)
#define OSSL_PARAM_BN(key, address, size)
#define OSSL_PARAM_END #define OSSL_PARAM_END
OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret); OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize); size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
@ -59,11 +69,11 @@ OSSL_PARAM_set_octet_ptr
const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
const char *key); const char *key);
int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val); int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, const char *key, TYPE val); int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val); int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val); int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
size_t max_len); size_t max_len);
@ -73,12 +83,13 @@ OSSL_PARAM_set_octet_ptr
size_t max_len, size_t *used_len); size_t max_len, size_t *used_len);
int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len); int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val); int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, char *val); int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val, int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
size_t *used_len); size_t *used_len);
int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len); int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
size_t used_len);
=head1 DESCRIPTION =head1 DESCRIPTION