From a1c5cefaf47ad9992c77960e8899d8979901507a Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 18 Jul 2019 09:25:24 +0200 Subject: [PATCH] Correct some OSSL_PARAM documentation The documentation wasn't quite in sync with the implementation. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/9408) --- doc/internal/man3/ossl_param_bld_init.pod | 86 +++++++++++------------ doc/man3/OSSL_PARAM_int.pod | 63 ++++++++++------- 2 files changed, 80 insertions(+), 69 deletions(-) diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod index ca206c7628..a65aa8bd83 100644 --- a/doc/internal/man3/ossl_param_bld_init.pod +++ b/doc/internal/man3/ossl_param_bld_init.pod @@ -2,15 +2,15 @@ =head1 NAME -ossl_param_build_init, -ossl_param_build_to_param, ossl_param_build_push_int, -ossl_param_build_push_uint, ossl_param_build_push_long, -ossl_param_build_push_ulong, ossl_param_build_push_int32, -ossl_param_build_push_uint32, ossl_param_build_push_int64, -ossl_param_build_push_uint64, ossl_param_build_push_size_t, -ossl_param_build_push_double, ossl_param_build_push_BN, -ossl_param_build_push_utf8_string, ossl_param_build_push_utf8_ptr, -ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr +ossl_param_bld_init, +ossl_param_bld_to_param, 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 @@ -22,25 +22,25 @@ ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr #define OSSL_PARAM_BLD_MAX 10 typedef struct { ... } OSSL_PARAM_BLD; - void ossl_param_build_init(OSSL_PARAM_BLD *bld); - OSSL_PARAM *ossl_param_build_to_param(OSSL_PARAM_BLD *bld, void **secure); - OSSL_PARAM *ossl_param_build_to_param_ex(OSSL_PARAM_BLD *bld, + void ossl_param_bld_init(OSSL_PARAM_BLD *bld); + OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld, void **secure); + 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); - 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); - 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); - 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); - 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); - 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); @@ -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 arrays. The B names are as per L. -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. 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 into an allocated OSSL_PARAM array. The pointer referenced by the B argument is set to point to an 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() with the pointer referenced by B. -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. An OSSL_PARAM array of at least B elements is passed in as B. The auxiliary storage for the parameters is a block of memory pointed to @@ -69,46 +69,46 @@ by B of at least B bytes in size. If required, secure memory for private BIGNUMs should be pointed to by B of at least B 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 argument. B 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. If B is marked as being securely allocated, the secure flag is set in the OSSL_PARAM_BLD structure. The B 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. If the length of the string, B, is zero then it will be calculated. The string that B 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 and . The memory that B 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. If the length of the string, B, is zero then it will be calculated. The string B points to is stored by reference and must remain in 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. The memory B points to is stored by reference and must remain in scope until the OSSL_PARAM array is freed. =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. -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. =head1 NOTES @@ -139,13 +139,13 @@ private key. OSSL_PARAM *params; void *secure; - ossl_param_build_init(&bld, &secure); - if (!ossl_param_build_push_BN(&bld, "p", p) - || !ossl_param_build_push_BN(&bld, "q", q) - || !ossl_param_build_push_uint(&bld, "e", e) - || !ossl_param_build_push_BN(&bld, "n", n) - || !ossl_param_build_push_BN(&bld, "d", d) - || (params = ossl_param_build_to_param(&bld)) == NULL) + 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 */ ... @@ -161,10 +161,10 @@ public key. OSSL_PARAM *params; void *secure; - ossl_param_build_init(&bld, &secure); - if (!ossl_param_build_push_BN(&bld, "n", n) - || !ossl_param_build_push_BN(&bld, "d", d) - || (params = ossl_param_build_to_param(&bld)) == NULL) + 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 */ ... diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index 0640bcf0ca..b73d2b16c2 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -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_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_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double, -OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, -OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, -OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint, -OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, -OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN, -OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, -OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, -OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const, +OSSL_PARAM_END, +OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, +OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, +OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, +OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32, +OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong, +OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string, +OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string, +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_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_ulong, OSSL_PARAM_set_double, OSSL_PARAM_set_int, -OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long, -OSSL_PARAM_set_size_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, -OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN, -OSSL_PARAM_set_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string, -OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string, -OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr, +OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string, +OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr, +OSSL_PARAM_get_octet_ptr, +OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, +OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, +OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64, +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 helpers @@ -34,15 +36,23 @@ OSSL_PARAM_set_octet_ptr #include + /* + * 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_BN(key, address, size) #define OSSL_PARAM_utf8_string(key, address, size) #define OSSL_PARAM_octet_string(key, address, size) #define OSSL_PARAM_utf8_ptr(key, address, size) #define OSSL_PARAM_octet_ptr(key, address, size) - #define OSSL_PARAM_BN(key, address, size) #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, size_t bsize); 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 char *key); - int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val); - int OSSL_PARAM_set_TYPE(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, TYPE val); - int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val); - int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val); + int OSSL_PARAM_get_BN(const OSSL_PARAM *p, 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, size_t max_len); @@ -73,12 +83,13 @@ OSSL_PARAM_set_octet_ptr 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_get_utf8_ptr(const OSSL_PARAM *p, char **val); - int OSSL_PARAM_set_utf8_ptr(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, 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); - 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