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)

3 files changed, 19 insertions, 10 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.
diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index d637d94f8a..25b87014b7 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -184,8 +184,7 @@ size I<rsize> is created.
 OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
 string OSSL_PARAM structure.
 A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
-If I<bsize> is zero, the string length is determined using strlen(3) + 1 for the
-null termination byte.
+If I<bsize> is zero, the string length is determined using strlen(3).
 Generally pass zero for I<bsize> instead of calling strlen(3) yourself.
 
 OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
@@ -232,15 +231,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 either stored into I<*val> with a length limit of I<max_len> or,
-in the case when I<*val> is NULL, memory is allocated for the string and
-I<max_len> is ignored.
+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.
 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 size the parameter's I<data> buffer should have.
+will be assigned the minimum size the parameter's I<data> buffer should have
+to accomodate the string, including a terminating NUL byte.
 
 OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
 pointed to by I<p>.
@@ -334,11 +336,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";
     const OSSL_PARAM set[] = {
         OSSL_PARAM_utf8_ptr("foo", &foo, foo_l),
-        OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
+        OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1),
         OSSL_PARAM_END
     };
 
@@ -366,7 +368,7 @@ could fill in the parameters like this:
     if ((p = OSSL_PARAM_locate(params, "foo")) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, "foo value");
     if ((p = OSSL_PARAM_locate(params, "bar")) != NULL)
-        OSSL_PARAM_set_utf8_ptr(p, "bar value");
+        OSSL_PARAM_set_utf8_string(p, "bar value");
     if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, "cookie value");
 
diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod
index f0e113c6c8..a2ff902cce 100644
--- a/doc/man7/EVP_KDF-SSHKDF.pod
+++ b/doc/man7/EVP_KDF-SSHKDF.pod
@@ -124,7 +124,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                           session_id, (size_t)32);
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE,
-                                         type, sizeof(type));
+                                         type, sizeof(type) - 1);
  *p = OSSL_PARAM_construct_end();
  if (EVP_KDF_CTX_set_params(kctx, params) <= 0)
      /* Error */