[openssl] master update

[Richard Levitte]

The branch master has been updated
       via  c589c1495bdabd02a33546f9e7b849fd912130d1 (commit)
      from  2d840893e78253bcce428603fdbcda159bdebe08 (commit)


- Log -----------------------------------------------------------------
commit c589c1495bdabd02a33546f9e7b849fd912130d1
Author: Richard Levitte <levitte at openssl.org>
Date:   Mon Nov 23 03:03:28 2020 +0100

    DOC: Add note on how to terminate an OSSL_PARAM array
    
    The examples are also updated to have correct terminators.
    
    doc/man3/OSSL_PARAM.pod is deliberately written with no help from the
    constructor macros described in OSSL_PARAM_int.pod.  Therefore, use of
    OSSL_PARAM_END isn't shown directly here, only leaving a link to its
    man-page to indicate that there is that option.
    
    Fixes #11280
    
    Reviewed-by: Paul Dale <paul.dale at oracle.com>
    (Merged from https://github.com/openssl/openssl/pull/13478)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_PARAM.pod | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 044b7a5c42..fdf376a206 100644
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -64,6 +64,13 @@ 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 B<OSSL_PARAM> fields
 
 =over 4
@@ -72,6 +79,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
@@ -288,7 +298,7 @@ This example is for setting parameters on some object:
     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 }
+        { NULL, 0, NULL, 0, 0 }
     };
 
 =head3 Example 2
@@ -302,7 +312,7 @@ This example is for requesting parameters on some object:
     OSSL_PARAM request[] = {
         { "foo", OSSL_PARAM_UTF8_STRING_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)