From: Pauli <ppzgs1@gmail.com>
Date: Wed, 3 Mar 2021 01:26:51 +0000 (+1000)
Subject: doc: document the additional params argument to the various init() calls
X-Git-Tag: openssl-3.0.0-alpha14~307
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f187d4f9f8d69a9d6d9e35e41284bff28649ea13;p=thirdparty%2Fopenssl.git

doc: document the additional params argument to the various init() calls

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14383)
---

diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod
index 939dc76f76e..91c1c0f830e 100644
--- a/doc/man7/provider-asym_cipher.pod
+++ b/doc/man7/provider-asym_cipher.pod
@@ -23,13 +23,15 @@ provider-asym_cipher - The asym_cipher library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);
 
  /* Encryption */
- int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey);
+ int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey,
+                                        const OSSL_PARAM params[]);
  int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
                                    size_t outsize, const unsigned char *in,
                                    size_t inlen);
 
  /* Decryption */
- int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey);
+ int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey,
+                                        const OSSL_PARAM params[]);
  int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen,
                                    size_t outsize, const unsigned char *in,
                                    size_t inlen);
@@ -122,10 +124,11 @@ context in the I<ctx> parameter and return the duplicate copy.
 OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption
 given a provider side asymmetric cipher context in the I<ctx> parameter, and a
 pointer to a provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_asym_cipher_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
-
 OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself.
 A previously initialised asymmetric cipher context is passed in the I<ctx>
 parameter.
@@ -143,6 +146,8 @@ written to I<*outlen>.
 OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption
 given a provider side asymmetric cipher context in the I<ctx> parameter, and a
 pointer to a provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_asym_cipher_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod
index 133ee07d673..13ec95568c1 100644
--- a/doc/man7/provider-cipher.pod
+++ b/doc/man7/provider-cipher.pod
@@ -25,10 +25,10 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions
  /* Encryption/decryption */
  int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key,
                                    size_t keylen, const unsigned char *iv,
-                                   size_t ivlen);
+                                   size_t ivlen, const OSSL_PARAM params[]);
  int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
                                    size_t keylen, const unsigned char *iv,
-                                   size_t ivlen);
+                                   size_t ivlen, const OSSL_PARAM params[]);
  int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
                              size_t outsize, const unsigned char *in, size_t inl);
  int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
@@ -129,6 +129,8 @@ OSSL_FUNC_cipher_encrypt_init() initialises a cipher operation for encryption gi
 newly created provider side cipher context in the I<cctx> parameter.
 The key to be used is given in I<key> which is I<keylen> bytes long.
 The IV to be used is given in I<iv> which is I<ivlen> bytes long.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_cipher_set_ctx_params().
 
 OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init() except that it
 initialises the context for a decryption operation.
diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod
index 71658271606..8307428b16e 100644
--- a/doc/man7/provider-digest.pod
+++ b/doc/man7/provider-digest.pod
@@ -22,7 +22,7 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_digest_dupctx(void *dctx);
 
  /* Digest generation */
- int OSSL_FUNC_digest_init(void *dctx);
+ int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]);
  int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl);
  int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl,
                             size_t outsz);
@@ -115,6 +115,8 @@ I<dctx> parameter and return the duplicate copy.
 
 OSSL_FUNC_digest_init() initialises a digest operation given a newly created
 provider side digest context in the I<dctx> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_digest_set_ctx_params().
 
 OSSL_FUNC_digest_update() is called to supply data to be digested as part of a
 previously initialised digest operation.
diff --git a/doc/man7/provider-kem.pod b/doc/man7/provider-kem.pod
index 7903fb8ca49..7ed98ba05cc 100644
--- a/doc/man7/provider-kem.pod
+++ b/doc/man7/provider-kem.pod
@@ -23,7 +23,8 @@ provider-kem - The kem library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_kem_dupctx(void *ctx);
 
  /* Encapsulation */
- int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name);
+ int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name,
+                                    const OSSL_PARAM params[]);
  int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen,
                                unsigned char *secret, size_t *secretlen);
 
@@ -120,6 +121,8 @@ OSSL_FUNC_kem_encapsulate_init() initialises a context for an asymmetric
 encapsulation given a provider side asymmetric kem context in the I<ctx>
 parameter, a pointer to a provider key object in the I<provkey> parameter and
 the I<name> of the algorithm.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_kem_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod
index b353f760bde..577fc385108 100644
--- a/doc/man7/provider-keyexch.pod
+++ b/doc/man7/provider-keyexch.pod
@@ -23,7 +23,8 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_keyexch_dupctx(void *ctx);
 
  /* Shared secret derivation */
- int OSSL_FUNC_keyexch_init(void *ctx, void *provkey);
+ int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
+                            const OSSL_PARAM params[]);
  int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
  int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
                               size_t outlen);
@@ -107,7 +108,10 @@ the I<ctx> parameter and return the duplicate copy.
 
 OSSL_FUNC_keyexch_init() initialises a key exchange operation given a provider side key
 exchange context in the I<ctx> parameter, and a pointer to a provider key object
-in the I<provkey> parameter. The key object should have been previously
+in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_keyexch_set_params().
+The key object should have been previously
 generated, loaded or imported into the provider using the key management
 (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
 
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index aba7e3a8841..fa901b27427 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -222,8 +222,9 @@ more elaborate context based key object constructor.
 
 OSSL_FUNC_keymgmt_gen_init() should create the key object generation context
 and initialize it with I<selections>, which will determine what kind
-of contents the key object to be generated should get.  The I<params>, if
-not NULL, should be set on the generation context.
+of contents the key object to be generated should get.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_keymgmt_set_params().
 
 OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context
 I<genctx>.  The I<template> is assumed to be a key object constructed
diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index 0d17d58367c..44bfa706c4d 100644
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -23,24 +23,28 @@ provider-signature - The signature library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_signature_dupctx(void *ctx);
 
  /* Signing */
- int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey);
+ int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey,
+                                   const OSSL_PARAM params[]);
  int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
                               size_t sigsize, const unsigned char *tbs, size_t tbslen);
 
  /* Verifying */
- int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey);
+ int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey,
+                                     const OSSL_PARAM params[]);
  int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
                                 const unsigned char *tbs, size_t tbslen);
 
  /* Verify Recover */
- int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey);
+ int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey,
+                                             const OSSL_PARAM params[]);
  int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
                                         size_t *routlen, size_t routsize,
                                         const unsigned char *sig, size_t siglen);
 
  /* Digest Sign */
  int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
-                                          const char *props, void *provkey);
+                                          const char *props, void *provkey,
+                                          const OSSL_PARAM params[]);
  int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
                                      size_t datalen);
  int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
@@ -52,7 +56,8 @@ provider-signature - The signature library E<lt>-E<gt> provider functions
 
  /* Digest Verify */
  int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
-                                            const char *props, void *provkey);
+                                            const char *props, void *provkey,
+                                            const OSSL_PARAM params[]);
  int OSSL_FUNC_signature_digest_verify_update(void *ctx,
                                               const unsigned char *data,
                                               size_t datalen);
@@ -192,6 +197,8 @@ the I<ctx> parameter and return the duplicate copy.
 OSSL_FUNC_signature_sign_init() initialises a context for signing given a provider side
 signature context in the I<ctx> parameter, and a pointer to a provider key object
 in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_signature_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
@@ -212,6 +219,8 @@ I<*siglen>.
 OSSL_FUNC_signature_verify_init() initialises a context for verifying a signature given
 a provider side signature context in the I<ctx> parameter, and a pointer to a
 provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_signature_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
@@ -228,6 +237,8 @@ long.
 OSSL_FUNC_signature_verify_recover_init() initialises a context for recovering the
 signed data given a provider side signature context in the I<ctx> parameter, and
 a pointer to a provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_signature_set_ctx_params().
 The key object should have been previously generated, loaded or imported into
 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
 provider-keymgmt(7)>.
@@ -246,7 +257,11 @@ the I<routlen> parameter.
 
 OSSL_FUNC_signature_digeset_sign_init() initialises a context for signing given a
 provider side signature context in the I<ctx> parameter, and a pointer to a
-provider key object in the I<provkey> parameter. The key object should have been
+provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+using OSSL_FUNC_signature_set_ctx_params() and
+OSSL_FUNC_signature_set_ctx_md_params().
+The key object should have been
 previously generated, loaded or imported into the provider using the
 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
 The name of the digest to be used will be in the I<mdname> parameter. There may
@@ -281,7 +296,11 @@ length of the signature should be written to I<*siglen>.
 
 OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a
 provider side verification context in the I<ctx> parameter, and a pointer to a
-provider key object in the I<provkey> parameter. The key object should have been
+provider key object in the I<provkey> parameter.
+The I<params>, if not NULL, should be set on the context in a manner similar to
+OSSL_FUNC_signature_set_ctx_params() and
+OSSL_FUNC_signature_set_ctx_md_params().
+The key object should have been
 previously generated, loaded or imported into the provider using the
 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
 The name of the digest to be used will be in the I<mdname> parameter. There may