[openssl] master update
tomas at openssl.org
tomas at openssl.org
Fri Aug 13 10:28:28 UTC 2021
The branch master has been updated
via 4ccad35756dfa9df657f3853810101fa9d6ca525 (commit)
from bd32bdb8b2a0f98d99b21e1b4d68dfaf1bd5584d (commit)
- Log -----------------------------------------------------------------
commit 4ccad35756dfa9df657f3853810101fa9d6ca525
Author: Tomas Mraz <tomas at openssl.org>
Date: Wed Aug 11 18:46:07 2021 +0200
Correct documentation errors in regards to UTF8 params
This fixes numerous bugs in documentation in regards to UTF8
params and their sizes. The returned size should always be without the
terminating NUL byte. On the other hand on the requestor side
the size of the buffer should include the NUL byte if it expects it
being included in the returned string.
Also make this clear in the EVP_PKEY_get_group_name() documentation
which uses utf8 string params under the hood.
Fixes #16287
Reviewed-by: Viktor Dukhovni <viktor at openssl.org>
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16296)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/EVP_PKEY_fromdata.pod | 2 +-
doc/man3/EVP_PKEY_get_group_name.pod | 4 ++--
doc/man3/EVP_PKEY_gettable_params.pod | 3 ++-
doc/man3/OSSL_PARAM.pod | 8 ++++----
doc/man3/OSSL_PARAM_BLD.pod | 6 ++++--
doc/man3/OSSL_PARAM_int.pod | 13 +++++++------
6 files changed, 20 insertions(+), 16 deletions(-)
diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index d24fb34a25..107ebf82a0 100644
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -161,7 +161,7 @@ TODO Write a set of cookbook documents and link to them.
0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
};
const OSSL_PARAM params[] = {
- OSSL_PARAM_utf8_string("group", "prime256v1"),
+ OSSL_PARAM_utf8_string("group", "prime256v1", 10),
OSSL_PARAM_BN("priv", priv, sizeof(priv)),
OSSL_PARAM_BN("pub", pub, sizeof(pub)),
OSSL_PARAM_END
diff --git a/doc/man3/EVP_PKEY_get_group_name.pod b/doc/man3/EVP_PKEY_get_group_name.pod
index 3ef19b8575..5844bf1abc 100644
--- a/doc/man3/EVP_PKEY_get_group_name.pod
+++ b/doc/man3/EVP_PKEY_get_group_name.pod
@@ -15,8 +15,8 @@ EVP_PKEY_get_group_name - get group name of a key
EVP_PKEY_get_group_name() fills in the group name of the I<pkey> into
I<gname>, up to at most I<gname_sz> bytes including the ending NUL byte
-and assigns I<*gname_len> the actual size of the name, if I<pkey>'s key type
-supports it.
+and assigns I<*gname_len> the actual length of the name not including
+the NUL byte, if I<pkey>'s key type supports it.
I<gname> as well as I<gname_len> may individually be NULL, and won't be
filled in or assigned in that case.
diff --git a/doc/man3/EVP_PKEY_gettable_params.pod b/doc/man3/EVP_PKEY_gettable_params.pod
index da3d99d0bf..27240b0d3b 100644
--- a/doc/man3/EVP_PKEY_gettable_params.pod
+++ b/doc/man3/EVP_PKEY_gettable_params.pod
@@ -49,7 +49,8 @@ is allocated by the method.
EVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value int a buffer
I<str> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
-I<*out_sz> is the returned size of the string if it is not NULL.
+If I<out_sz> is not NULL the I<*out_sz> is set to the length of the string
+not including the terminating NUL byte.
EVP_PKEY_get_octet_string_param() copy a I<pkey>'s octet string value into a buffer
I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 98d75c9fa2..f335d6f2c8 100644
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -306,11 +306,11 @@ This example is for setting parameters on some object:
#include <openssl/core.h>
const char *foo = "some string";
- size_t foo_l = strlen(foo) + 1;
+ size_t foo_l = strlen(foo);
const char bar[] = "some other string";
OSSL_PARAM set[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
- { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
+ { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar) - 1, 0 },
{ NULL, 0, NULL, 0, 0 }
};
@@ -338,10 +338,10 @@ could fill in the parameters like this:
for (i = 0; params[i].key != NULL; i++) {
if (strcmp(params[i].key, "foo") == 0) {
*(char **)params[i].data = "foo value";
- params[i].return_size = 10; /* size of "foo value" */
+ params[i].return_size = 9; /* length of "foo value" string */
} else if (strcmp(params[i].key, "bar") == 0) {
memcpy(params[i].data, "bar value", 10);
- params[i].return_size = 10; /* size of "bar value" */
+ params[i].return_size = 9; /* length of "bar value" string */
}
/* Ignore stuff we don't know */
}
diff --git a/doc/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod
index fdc9ec3081..d07eff6f27 100644
--- a/doc/man3/OSSL_PARAM_BLD.pod
+++ b/doc/man3/OSSL_PARAM_BLD.pod
@@ -91,7 +91,8 @@ 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 I<buf>.
-If the length of the string, I<bsize>, is zero then it will be calculated.
+The length of the string I<bsize> should not include the terminating NUL byte.
+If it is zero then it will be calculated.
The string that I<buf> points to is stored by reference and must remain in
scope until after OSSL_PARAM_BLD_to_param() has been called.
@@ -102,7 +103,8 @@ 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 I<buf>.
-If the length of the string, I<bsize>, is zero then it will be calculated.
+The length of the string I<bsize> should not include the terminating NUL byte.
+If it is zero then it will be calculated.
The string I<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index 4f482ee610..8dbe830e95 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -200,7 +200,7 @@ OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
string B<OSSL_PARAM> structure.
A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
-OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF string
+OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string
pointer B<OSSL_PARAM> structure.
A parameter with name I<key>, storage pointer I<*buf> and size I<bsize>
is created.
@@ -241,17 +241,18 @@ will be assigned the size the parameter's I<data> buffer should have.
OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
pointed to by I<p>.
The string is stored into I<*val> with a size limit of I<max_len>,
-which must be large enough to accomodate a terminating NUL byte,
-otherwise this function will fail.
-If I<*val> is NULL, memory is allocated for the string and I<max_len>
-is ignored.
+which must be large enough to accomodate the string. A terminating NUL byte
+is added only if the buffer is longer than the string length otherwise the
+string will not be NUL terminated.
+If I<*val> is NULL, memory is allocated for the string (including the
+terminating NUL byte) and I<max_len> is ignored.
If memory is allocated by this function, it must be freed by the caller.
OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
by I<p> to the value referenced by I<val>.
If the parameter's I<data> field is NULL, then only its I<return_size> field
will be assigned the minimum size the parameter's I<data> buffer should have
-to accomodate the string, including a terminating NUL byte.
+to accomodate the string, not including a terminating NUL byte.
OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
pointed to by I<p>.
More information about the openssl-commits
mailing list