Fix intermittent sslapitest early data related failures

[openssl.git] / doc / man3 / OSSL_PARAM.pod

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index a2392a9609c647235439c1d2d9c38b7f2070d292..1e5bf06cf767a7a339cd309a36d54f04fab1cc53 100644 (file)
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -40,11 +40,11 @@ suitable form for the internal structure of the object.
 
 =item * Request parameters of some object
 
-The caller (the I<requestor>) sets up the B<OSSL_PARAM> array and
+The caller (the I<requester>) sets up the B<OSSL_PARAM> array and
 calls some function (the I<responder>) that has intimate knowledge
 about the object, which can take the internal data of the object and
 copy (possibly convert) that to the memory prepared by the
-I<requestor> and pointed at with the B<OSSL_PARAM> I<data>.
+I<requester> and pointed at with the B<OSSL_PARAM> I<data>.
 
 =item * Request parameter descriptors
 
@@ -64,6 +64,19 @@ Normally, the order of the an B<OSSL_PARAM> array is not relevant.
 However, if the I<responder> can handle multiple elements with the
 same key, those elements must be handled in the order they are in.
 
+An B<OSSL_PARAM> array must have a terminating element, where I<key>
+is NULL.  The usual full terminating template is:
+
+    { NULL, 0, NULL, 0, 0 }
+
+This can also be specified using L<OSSL_PARAM_END(3)>.
+
+=head2 Functional support
+
+Libcrypto offers a limited set of helper functions to handle
+B<OSSL_PARAM> items and arrays, please see L<OSSL_PARAM_get_int(3)>.
+Developers are free to extend or replace those as they see fit.
+
 =head2 B<OSSL_PARAM> fields
 
 =over 4
@@ -72,6 +85,9 @@ same key, those elements must be handled in the order they are in.
 
 The identity of the parameter in the form of a string.
 
+In an B<OSSL_PARAM> array, an item with this field set to NULL is
+considered a terminating item.
+
 =item I<data_type>
 
 The I<data_type> is a value that describes the type and organization of
@@ -87,8 +103,15 @@ 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 accommodate 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
+This can be used by the I<requester> to figure out dynamically exactly
 how much buffer space is needed to store the parameter data.
 In this case, I<data_size> is ignored.
 
@@ -244,6 +267,14 @@ B<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
 
 =item *
 
+If I<data> for a B<OSSL_PARAM_OCTET_STRING> or a
+B<OSSL_PARAM_UTF8_STRING> is NULL, the I<responder> should
+set I<return_size> to the size of the item to be returned
+and return success. Later the responder will be called again
+with I<data> pointing at the place for the value to be put.
+
+=item *
+
 If a I<responder> finds that some data sizes are too small for the
 requested data, it must set I<return_size> for each such
 B<OSSL_PARAM> item to the minimum required size, and eventually return
@@ -283,12 +314,12 @@ 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 },
-        { NULL, 0, NULL, 0, NULL }
+        { "foo", OSSL_PARAM_UTF8_PTR, &foo, foo_l, 0 },
+        { "bar", OSSL_PARAM_UTF8_STRING, (void *)&bar, sizeof(bar) - 1, 0 },
+        { NULL, 0, NULL, 0, 0 }
     };
 
 =head3 Example 2
@@ -300,9 +331,9 @@ This example is for requesting parameters on some object:
     char bar[1024];
     size_t bar_l;
     OSSL_PARAM request[] = {
-        { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
+        { "foo", OSSL_PARAM_UTF8_PTR, &foo, 0 /*irrelevant*/, 0 },
         { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
-        { NULL, 0, NULL, 0, NULL }
+        { NULL, 0, NULL, 0, 0 }
     };
 
 A I<responder> that receives this array (as I<params> in this example)
@@ -315,17 +346,17 @@ 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 */
     }
 
 =head1 SEE ALSO
 
-L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>
+L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>
 
 =head1 HISTORY
 
@@ -333,7 +364,7 @@ B<OSSL_PARAM> was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy