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@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16296)

1 files changed, 7 insertions, 6 deletions

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>.