OSSL_PARAM: Correct the assumptions on the UTF8 string length

When the string "ABCDEFGH" is passed, what's considered its data, this?

    { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H' }

or this?

    { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', '\0' }

If it's passed as a pass phrase, should the terminating NUL byte be
considered part of the pass phrase, or not?

Our treatment of OSSL_PARAMs with the data type OSSL_PARAM_UTF8_STRING
set the length of the string to include the terminating NUL byte,
which is quite confusing.  What should the recipient of such a string
believe?

Instead of perpetuating this confusion, we change the assumption to
set the OSSL_PARAM to the length of the string, not including the
terminating NUL byte, thereby giving it the same value as a strlen()
call would give.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14168)

1 files changed, 7 insertions, 0 deletions

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index fdf376a206..99f4e2ce62 100644
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -97,6 +97,13 @@ setting parameters) or shall (when requesting parameters) be stored,
 and I<data_size> is its size in bytes.
 The organization of the data depends on the parameter type and flag.
 
+The I<data_size> needs special attention with the parameter type
+B<OSSL_PARAM_UTF8_STRING> in relation to C strings.  When setting
+parameters, the size should be set to the length of the string, not
+counting the terminating NUL byte.  When requesting parameters, the
+size should be set to the size of the buffer to be populated, which
+should accomodate enough space for a terminating NUL byte.
+
 When I<requesting parameters>, it's acceptable for I<data> to be NULL.
 This can be used by the I<requestor> to figure out dynamically exactly
 how much buffer space is needed to store the parameter data.