From f59612fed8def965c61cdb002fa20f61943f50a0 Mon Sep 17 00:00:00 2001 From: Pauli Date: Wed, 3 Mar 2021 11:32:39 +1000 Subject: [PATCH] doc: note that get_params and set_params calls should return true if the param array is null Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/14383) --- doc/man7/provider-asym_cipher.pod | 3 +++ doc/man7/provider-cipher.pod | 2 ++ doc/man7/provider-digest.pod | 2 ++ doc/man7/provider-encoder.pod | 1 + doc/man7/provider-kdf.pod | 2 ++ doc/man7/provider-kem.pod | 3 +++ doc/man7/provider-keyexch.pod | 2 ++ doc/man7/provider-mac.pod | 2 ++ doc/man7/provider-rand.pod | 2 ++ doc/man7/provider-signature.pod | 6 ++++++ doc/man7/provider-storemgmt.pod | 1 + 11 files changed, 26 insertions(+) diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index 91c1c0f830..108fbceceb 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -173,9 +173,12 @@ functions. OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated with the given provider side asymmetric cipher context I and stores them in I. +Passing NULL for I should return true. + OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated with the given provider side asymmetric cipher context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. Parameters currently recognised by built-in asymmetric cipher algorithms are as follows. diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index 13ec95568c..de5be060a1 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -186,9 +186,11 @@ and stores them in I. OSSL_FUNC_cipher_set_ctx_params() sets cipher operation parameters for the provider side cipher context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_cipher_get_ctx_params() gets cipher operation details details from the given provider side cipher context I and stores them in I. +Passing NULL for I should return true. OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), and OSSL_FUNC_cipher_settable_ctx_params() all return constant B diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 8307428b16..ce53c61de4 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -152,9 +152,11 @@ and stores them in I. OSSL_FUNC_digest_set_ctx_params() sets digest operation parameters for the provider side digest context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from the given provider side digest context I and stores them in I. +Passing NULL for I should return true. OSSL_FUNC_digest_gettable_params() returns a constant B array containing descriptors of the parameters that OSSL_FUNC_digest_get_params() diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod index 2fcbd6499a..5e34b7a394 100644 --- a/doc/man7/provider-encoder.pod +++ b/doc/man7/provider-encoder.pod @@ -197,6 +197,7 @@ OSSL_FUNC_encoder_newctx(). OSSL_FUNC_encoder_set_ctx_params() sets context data according to parameters from I that it recognises. Unrecognised parameters should be ignored. +Passing NULL for I should return true. OSSL_FUNC_encoder_settable_ctx_params() returns a constant B array describing the parameters that OSSL_FUNC_encoder_set_ctx_params() diff --git a/doc/man7/provider-kdf.pod b/doc/man7/provider-kdf.pod index 0b13537e8d..fb9e30a843 100644 --- a/doc/man7/provider-kdf.pod +++ b/doc/man7/provider-kdf.pod @@ -127,9 +127,11 @@ provider algorithm and stores them in I. OSSL_FUNC_kdf_set_ctx_params() sets KDF parameters associated with the given provider side KDF context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_kdf_get_ctx_params() retrieves gettable parameter values associated with the given provider side KDF context I and stores them in I. +Passing NULL for I should return true. OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params(), and OSSL_FUNC_kdf_settable_ctx_params() all return constant B diff --git a/doc/man7/provider-kem.pod b/doc/man7/provider-kem.pod index 7ed98ba05c..3ed9ff11fc 100644 --- a/doc/man7/provider-kem.pod +++ b/doc/man7/provider-kem.pod @@ -171,9 +171,12 @@ functions. OSSL_FUNC_kem_get_ctx_params() gets asymmetric kem parameters associated with the given provider side asymmetric kem context I and stores them in I. +Passing NULL for I should return true. + OSSL_FUNC_kem_set_ctx_params() sets the asymmetric kem parameters associated with the given provider side asymmetric kem context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. No parameters are currently recognised by built-in asymmetric kem algorithms. diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 577fc38510..0fc36c5da6 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -139,10 +139,12 @@ OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters associated with given provider side key exchange context I to I, see L. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters associated with the given provider side key exchange context I into I, see L. +Passing NULL for I should return true. OSSL_FUNC_keyexch_settable_ctx_params() yields a constant B array that describes the settable parameters, i.e. parameters that can be used with diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod index 8b4ce93613..82bbdb9aa2 100644 --- a/doc/man7/provider-mac.pod +++ b/doc/man7/provider-mac.pod @@ -137,10 +137,12 @@ provider algorithm and stores them in I. OSSL_FUNC_mac_set_ctx_params() sets mac parameters associated with the given provider side mac context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_mac_get_ctx_params() gets details of currently set parameter values associated with the given provider side mac context I and stores them in I. +Passing NULL for I should return true. OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params(), and OSSL_FUNC_mac_settable_ctx_params() all return constant B diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod index 157f6227e9..be81237610 100644 --- a/doc/man7/provider-rand.pod +++ b/doc/man7/provider-rand.pod @@ -160,10 +160,12 @@ provider algorithm and stores them in I. OSSL_FUNC_rand_set_ctx_params() sets rand parameters associated with the given provider side rand context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. OSSL_FUNC_rand_get_ctx_params() gets details of currently set parameter values associated with the given provider side rand context I and stores them in I. +Passing NULL for I should return true. OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params(), and OSSL_FUNC_rand_settable_ctx_params() all return constant B diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 44bfa706c4..fe8a68b77c 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -332,9 +332,12 @@ the OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params( OSSL_FUNC_signature_get_ctx_params() gets signature parameters associated with the given provider side signature context I and stored them in I. +Passing NULL for I should return true. + OSSL_FUNC_signature_set_ctx_params() sets the signature parameters associated with the given provider side signature context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. Common parameters currently recognised by built-in signature algorithms are as follows. @@ -391,9 +394,12 @@ functions. OSSL_FUNC_signature_get_md_ctx_params() gets digest parameters associated with the given provider side digest signature context I and stores them in I. +Passing NULL for I should return true. + OSSL_FUNC_signature_set_ms_ctx_params() sets the digest parameters associated with the given provider side digest signature context I to I. Any parameter settings are additional to any that were previously set. +Passing NULL for I should return true. Parameters currently recognised by built-in signature algorithms are the same as those for built-in digest algorithms. See diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod index 2e5bddc5ec..8b4c7dbe71 100644 --- a/doc/man7/provider-storemgmt.pod +++ b/doc/man7/provider-storemgmt.pod @@ -89,6 +89,7 @@ OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what kind of data to expect, search criteria, and so on. More on those below, in L. Whether unrecognised parameters are an error or simply ignored is at the implementation's discretion. +Passing NULL for I should return true. OSSL_FUNC_store_load() loads the next object from the URI opened by OSSL_FUNC_store_open(), creates an object abstraction for it (see -- 2.34.1