Rename OSSL_SERIALIZER / OSSL_DESERIALIZER to OSSL_ENCODE / OSSL_DECODE

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

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 361028fa00d7b2feb1ddb71e414cd65b3e89d613..044b7a5c4236352ad381389c534325de64b01e04 100644 (file)
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -87,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
@@ -95,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.
@@ -152,6 +159,9 @@ The parameter data is a pointer to a printable string.
 The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data>
 doesn't point directly at the data, but to a pointer that points to the data.
 
+If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is
+almost certainly the correct choice.
+
 This is used to indicate that constant data is or will be passed,
 and there is therefore no need to copy the data that is passed, just
 the pointer to it.
@@ -175,6 +185,9 @@ The difference between this and B<OSSL_PARAM_OCTET_STRING> is that
 I<data> doesn't point directly at the data, but to a pointer that
 points to the data.
 
+If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is
+almost certainly the correct choice.
+
 This is used to indicate that constant data is or will be passed, and
 there is therefore no need to copy the data that is passed, just the
 pointer to it.
@@ -233,8 +246,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
 
@@ -310,7 +333,7 @@ B<OSSL_PARAM> was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2020 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