From d618ac6fd7e24a99122b04cd23b84130b2537d87 Mon Sep 17 00:00:00 2001 From: Pauli Date: Mon, 22 Feb 2021 12:07:15 +1000 Subject: [PATCH] doc: note changes to digest gettable/settable provider calls Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/14240) --- doc/man3/EVP_DigestInit.pod | 41 ++++++++++++++++++++++++------------ doc/man7/provider-digest.pod | 22 +++++++++++++------ 2 files changed, 43 insertions(+), 20 deletions(-) diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index c4cecad3a7..ac527e407e 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -180,18 +180,29 @@ See L below for more information. Sets the list of I into a MD context I. See L below for more information. -=item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), -EVP_MD_settable_ctx_params(), EVP_MD_CTX_gettable_params(), -EVP_MD_CTX_settable_params() +=item EVP_MD_gettable_params() -Get a B array that describes the retrievable and settable -parameters. EVP_MD_gettable_params() returns parameters that can be used with -EVP_MD_get_params(). EVP_MD_gettable_ctx_params() and -EVP_MD_CTX_gettable_params() return parameters that can be used with -EVP_MD_CTX_get_params(). EVP_MD_settable_ctx_params() and -EVP_MD_CTX_settable_params() return parameters that can be used with -EVP_MD_CTX_set_params(). -See L for the use of B as parameter descriptor. +Get a constant B array that describes the retrievable parameters +that can be used with EVP_MD_get_params(). See L for the +use of B as a parameter descriptor. + +=item EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params() + +Get a constant B array that describes the retrievable parameters +that can be used with EVP_MD_CTX_get_params(). EVP_MD_gettable_ctx_params() +returns the parameters that can be retrieved from the algorithm, whereas +EVP_MD_CTX_gettable_params() returns the parameters that can be retrieved +in the context's current state. See L for the use of +B as a parameter descriptor. + +=item EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() + +Get a constant B array that describes the settable parameters +that can be used with EVP_MD_CTX_set_params(). EVP_MD_settable_ctx_params() +returns the parameters that can be set from the algorithm, whereas +EVP_MD_CTX_settable_params() returns the parameters that can be set in the +context's current state. See L for the use of B +as a parameter descriptor. =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() @@ -658,8 +669,12 @@ The EVP_dss1() function was removed in OpenSSL 1.1.0. The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1. -The EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_CTX_set_params() -and EVP_MD_CTX_get_params() functions were added in OpenSSL 3.0. +The EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), +EVP_MD_get_params(), EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(), +EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), +EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and +EVP_MD_CTX_gettable_params() functions were added in OpenSSL 3.0. + The EVP_MD_CTX_update_fn() and EVP_MD_CTX_set_update_fn() were deprecated in OpenSSL 3.0. diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 1c09ee3c40..4f90cf8b62 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -33,8 +33,10 @@ provider-digest - The digest library E-E provider functions const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx); /* Digest operation parameter descriptors */ - const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *provctx); - const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *provctx); + const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx, + void *provctx); + const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx, + void *provctx); /* Digest parameters */ int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]); @@ -152,11 +154,17 @@ Any parameter settings are additional to any that were previously set. OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from the given provider side digest context I and stores them in I. -OSSL_FUNC_digest_gettable_params(), OSSL_FUNC_digest_gettable_ctx_params(), and -OSSL_FUNC_digest_settable_ctx_params() all return constant B arrays -as descriptors of the parameters that OSSL_FUNC_digest_get_params(), -OSSL_FUNC_digest_get_ctx_params(), and OSSL_FUNC_digest_set_ctx_params() can handle, -respectively. +OSSL_FUNC_digest_gettable_params() returns a constant B array +containing descriptors of the parameters that OSSL_FUNC_digest_get_params() +can handle. + +OSSL_FUNC_digest_gettable_ctx_params() and +OSSL_FUNC_digest_settable_ctx_params() both return constant +B arrays as descriptors of the parameters that +OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() +can handle, respectively. The array is based on the current state of +the provider side context if I is not NULL and on the provider +side algorithm I otherwise. Parameters currently recognised by built-in digests with this function are as follows. Not all parameters are relevant to, or are understood