mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Describe OSSL_PARAM as a parameter descriptor

Browse Source 
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)
This commit is contained in:
Richard Levitte 2019-07-11 12:18:42 +02:00
parent b8441adb59
commit 3efe19145c
2 changed files with 25 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/man3/OSSL_PARAM.pod
View File

@ -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:>

4
doc/man7/openssl-core.h.pod
View File

@ -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)>