Make it possible to easily specify a libctx for EVP_DigestSign*

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

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index d0725e063e811b393a9d2f982dd38f8ecef21b67..cd7d41006bffe20511a19185b4f6078f97f6816c 100644 (file)
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -60,6 +60,10 @@ I<responder>.
 
 =back
 
+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.
+
 =head2 B<OSSL_PARAM> fields
 
 =over 4
@@ -83,6 +87,11 @@ 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.
 
+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
+how much buffer space is needed to store the parameter data.
+In this case, I<data_size> is ignored.
+
 When the B<OSSL_PARAM> is used as a parameter descriptor, I<data>
 should be ignored.
 If I<data_size> is zero, it means that an arbitrary data size is
@@ -91,10 +100,12 @@ accepted, otherwise it specifies the maximum size allowed.
 =item I<return_size>
 
 When an array of B<OSSL_PARAM> is used to request data, the
-I<responder> must set this field to indicate the actual size of the
-parameter data.
-In case the I<data_size> is too small for the data, the I<responder>
-must still set this field to indicate the minimum data size required.
+I<responder> must set this field to indicate size of the parameter
+data, including padding as the case may be.
+In case the I<data_size> is an unsuitable size for the data, the
+I<responder> must still set this field to indicate the minimum data
+size required.
+(further notes on this in L</NOTES> below).
 
 When the B<OSSL_PARAM> is used as a parameter descriptor,
 I<return_size> should be ignored.
@@ -229,8 +240,18 @@ B<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
 
 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 required size, and eventually return an
-error.
+B<OSSL_PARAM> item to the minimum required size, and eventually return
+an error.
+
+=item *
+
+For the integer type parameters (B<OSSL_PARAM_UNSIGNED_INTEGER> and
+B<OSSL_PARAM_INTEGER>), a I<responder> may choose to return an error
+if the I<data_size> isn't a suitable size (even if I<data_size> is
+bigger than needed).  If the I<responder> finds the size suitable, it
+must fill all I<data_size> bytes and ensure correct padding for the
+native endianness, and set I<return_size> to the same value as
+I<data_size>.
 
 =back