[openssl] master update
Dr. Paul Dale
pauli at openssl.org
Thu Jul 18 23:38:39 UTC 2019
The branch master has been updated
via a1c5cefaf47ad9992c77960e8899d8979901507a (commit)
from 04edd688b3727835f9b2c7cca7e4c963bf3ed2ba (commit)
- Log -----------------------------------------------------------------
commit a1c5cefaf47ad9992c77960e8899d8979901507a
Author: Richard Levitte <levitte at openssl.org>
Date: Thu Jul 18 09:25:24 2019 +0200
Correct some OSSL_PARAM documentation
The documentation wasn't quite in sync with the implementation.
Reviewed-by: Paul Dale <paul.dale at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9408)
-----------------------------------------------------------------------
Summary of changes:
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 ca206c7..a65aa8b 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<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.
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.
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.
@@ -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<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.
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
@@ -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
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>
argument.
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>.
If B<bn> is marked as being securely allocated, the secure flag is
set in the OSSL_PARAM_BLD structure.
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>.
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_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>.
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>.
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_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>.
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_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 0640bcf..b73d2b1 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 <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_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
More information about the openssl-commits
mailing list