changes to match the updated context gettable/settable calls for ciphers

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14240)

2 files changed, 44 insertions, 15 deletions

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 7cc9cebb51..63b416289b 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -48,8 +48,10 @@ EVP_CIPHER_CTX_name,
 EVP_CIPHER_CTX_nid,
 EVP_CIPHER_CTX_get_params,
 EVP_CIPHER_gettable_ctx_params,
+EVP_CIPHER_CTX_gettable_params,
 EVP_CIPHER_CTX_set_params,
 EVP_CIPHER_settable_ctx_params,
+EVP_CIPHER_CTX_settable_params,
 EVP_CIPHER_CTX_block_size,
 EVP_CIPHER_CTX_key_length,
 EVP_CIPHER_CTX_iv_length,
@@ -147,6 +149,8 @@ EVP_CIPHER_do_all_provided
  const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);
  const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher);
  const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher);
+ const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx);
+ const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx);
  int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
  int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
  int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
@@ -302,12 +306,28 @@ context B<ctx>.
 EVP_CIPHER_CTX_get_params() retrieves the requested list of operation
 B<params> from CIPHER context B<ctx>.
 
-EVP_CIPHER_gettable_params(), EVP_CIPHER_gettable_ctx_params(), and
-EVP_CIPHER_settable_ctx_params() get a constant B<OSSL_PARAM> array
-that describes the retrievable and settable parameters, i.e. parameters
-that can be used with EVP_CIPHER_get_params(), EVP_CIPHER_CTX_get_params()
-and EVP_CIPHER_CTX_set_params(), respectively.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+EVP_CIPHER_gettable_params() returns an B<OSSL_PARAM> array that describes
+the retrievable and settable parameters.  EVP_CIPHER_gettable_params()
+returns parameters that can be used with EVP_CIPHER_get_params().  See
+L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
+
+EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()
+return constant B<OSSL_PARAM> arrays that describe the retrievable
+parameters that can be used with EVP_CIPHER_CTX_get_params().
+EVP_CIPHER_gettable_ctx_params() returns the parameters that can be
+retrieved from the algorithm, whereas EVP_CIPHER_CTX_gettable_params()
+returns the parameters that can be retrieved in the context's current
+state.  See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter
+descriptor.
+
+EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()
+return constant B<OSSL_PARAM> arrays that describe the settable
+parameters that can be used with EVP_CIPHER_CTX_set_params().
+EVP_CIPHER_settable_ctx_params() returns the parameters that can be
+retrieved from the algorithm, whereas EVP_CIPHER_CTX_settable_params()
+returns the parameters that can be retrieved in the context's current
+state.  See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter
+descriptor.
 
 EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
 length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
@@ -884,8 +904,11 @@ disappeared.  EVP_CIPHER_CTX_init() remains as an alias for
 EVP_CIPHER_CTX_reset().
 
 The EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
-EVP_CIPHER_CTX_set_params() and EVP_CIPHER_CTX_get_params() functions
-were added in 3.0.
+EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(),
+EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(),
+EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(),
+EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params()
+functions were added in 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod
index 34a5ec0a7f..133ee07d67 100644
--- a/doc/man7/provider-cipher.pod
+++ b/doc/man7/provider-cipher.pod
@@ -40,8 +40,10 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions
  const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx);
 
  /* Cipher operation parameter descriptors */
- const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *provctx);
- const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *provctx);
+ const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx,
+                                                        void *provctx);
+ const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx,
+                                                        void *provctx);
 
  /* Cipher parameters */
  int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]);
@@ -186,11 +188,15 @@ Any parameter settings are additional to any that were previously set.
 OSSL_FUNC_cipher_get_ctx_params() gets cipher operation details details from
 the given provider side cipher context I<cctx> and stores them in I<params>.
 
-OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), and
-OSSL_FUNC_cipher_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
-as descriptors of the parameters that OSSL_FUNC_cipher_get_params(),
-OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params() can handle,
-respectively.
+OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(),
+and OSSL_FUNC_cipher_settable_ctx_params() all return constant B<OSSL_PARAM>
+arrays as descriptors of the parameters that OSSL_FUNC_cipher_get_params(),
+OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params()
+can handle, respectively.  OSSL_FUNC_cipher_gettable_ctx_params() and
+OSSL_FUNC_cipher_settable_ctx_params() will return the parameters associated
+with the provider side context I<cctx> in its current state if it is
+not NULL.  Otherwise, they return the parameters associated with the
+provider side algorithm I<provctx>.
 
 Parameters currently recognised by built-in ciphers are as follows. Not all
 parameters are relevant to, or are understood by all ciphers: