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 a872de3b77e9c40dc9b763f9caa95a85a65e48be..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
 
@@ -71,6 +71,12 @@ is NULL.  The usual full terminating template is:
 
 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
@@ -102,10 +108,10 @@ 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.
+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.
 
@@ -261,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
@@ -300,11 +314,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 },
+        { "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 }
     };
 
@@ -317,7 +331,7 @@ 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, 0 }
     };
@@ -332,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
 
@@ -350,7 +364,7 @@ B<OSSL_PARAM> was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019-2021 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