From 3efe19145ceaf27d27c45384269fa37aa4f4b57f Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Thu, 11 Jul 2019 12:18:42 +0200
Subject: [PATCH] Describe OSSL_PARAM as a parameter descriptor

This affects doc/man3/OSSL_PARAM.pod and doc/man7/openssl-core.h.pod

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9346)
---
 doc/man3/OSSL_PARAM.pod     | 28 +++++++++++++++++++++++-----
 doc/man7/openssl-core.h.pod |  4 ++--
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 0f6358cf7b..61ff378e46 100644
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -27,27 +27,37 @@ A typical usage example could be an application that wants to set some
 parameters for an object, or wants to find out some parameters of an
 object.
 
-Arrays of this type can be used for two purposes:
+Arrays of this type can be used for the following purposes:
 
 =over 4
 
-=item *
+=item * Setting parameters for some object
 
-Setting parameters for some object.
 The caller sets up the C<OSSL_PARAM> array and calls some function
 (the I<setter>) that has intimate knowledge about the object that can
 take the data from the C<OSSL_PARAM> array and assign them in a
 suitable form for the internal structure of the object.
 
-=item *
+=item * Request parameters of some object
 
-Request parameters of some object.
 The caller (the I<requestor>) sets up the C<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 C<OSSL_PARAM> C<data>.
 
+=item * Request parameter descriptors
+
+The caller gets an array of constant C<OSSL_PARAM>, which describe
+available parameters and some of their properties; name, data type and
+expected data size.
+For a detailed description of each field for this use, see the field
+descriptions below.
+
+The caller may then use the information from this descriptor array to
+build up its own C<OSSL_PARAM> array to pass down to a I<setter> or
+I<responder>.
+
 =back
 
 =head2 C<OSSL_PARAM> fields
@@ -78,6 +88,11 @@ setting parameters) or shall (when requesting parameters) be stored,
 and C<data_size> is its size in bytes.
 The organization of the data depends on the parameter type and flag.
 
+When the C<OSSL_PARAM> is used as a parameter descriptor, C<data>
+should be ignored.
+If C<data_size> is zero, it means that an arbitrary data size is
+accepted, otherwise it specifies the maximum size allowed.
+
 =item C<return_size>
 
 When an array of C<OSSL_PARAM> is used to request data, the
@@ -86,6 +101,9 @@ parameter data.
 In case the C<data_size> is too small for the data, the I<responder>
 must still set this field to indicate the minimum data size required.
 
+When the C<OSSL_PARAM> is used as a parameter descriptor,
+C<return_size> should be ignored.
+
 =back
 
 B<NOTE:>
diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
index 7fd4dfb24e..737293d701 100644
--- a/doc/man7/openssl-core.h.pod
+++ b/doc/man7/openssl-core.h.pod
@@ -69,8 +69,8 @@ It's normally passed in arrays, where the array is terminated with an
 element where all fields are zero (for non-pointers) or C<NULL> (for
 pointers).
 
-These arrays can be used both to set parameters for some object, and
-to request parameters.
+These arrays can be used to set parameters for some object, to request
+parameters, and to describe parameters.
 
 C<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
 
-- 
2.34.1