Small fixes and cleanups of provider API documentation

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14756)

12 files changed, 35 insertions, 27 deletions

diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod
index 108fbceceb..99207b4e65 100644
--- a/doc/man7/provider-asym_cipher.pod
+++ b/doc/man7/provider-asym_cipher.pod
@@ -60,7 +60,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these:
diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 29f5468c9f..7bead3a45d 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -101,7 +101,7 @@ of the provider initialization function.  See L<provider(7)/Provider>
 for a description of the initialization function.
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from a B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" core_gettable_params() has these:
diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod
index e1d2182fa5..87b7992d84 100644
--- a/doc/man7/provider-cipher.pod
+++ b/doc/man7/provider-cipher.pod
@@ -69,7 +69,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_cipher_newctx() has these:
diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod
index ce53c61de4..e92991afa8 100644
--- a/doc/man7/provider-digest.pod
+++ b/doc/man7/provider-digest.pod
@@ -61,7 +61,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_digest_newctx() has these:
diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod
index 2b0804b558..9032036a6e 100644
--- a/doc/man7/provider-encoder.pod
+++ b/doc/man7/provider-encoder.pod
@@ -16,13 +16,13 @@ provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions
 
  /* Encoder parameter accessor and descriptor */
  const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx);
- int encoder_get_params(OSSL_PARAM params[]);
+ int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]);
 
  /* Functions to construct / destruct / manipulate the encoder context */
  void *OSSL_FUNC_encoder_newctx(void *provctx);
  void OSSL_FUNC_encoder_freectx(void *ctx);
  int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
- const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx)
+ const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx);
 
  /* Functions to check selection support */
  int OSSL_FUNC_encoder_does_selection(void *provctx, int selection);
@@ -36,9 +36,9 @@ provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions
                               void *cbarg);
 
  /* Functions to import and free a temporary object to be encoded */
- void *encoder_import_object(void *ctx, int selection,
-                             const OSSL_PARAM params[]);
- void encoder_free_object(void *obj);
+ void *OSSL_FUNC_encoder_import_object(void *ctx, int selection,
+                                       const OSSL_PARAM params[]);
+ void OSSL_FUNC_encoder_free_object(void *obj);
 
 
 =head1 DESCRIPTION
@@ -50,7 +50,7 @@ The ENCODER operation is a generic method to encode a provider-native
 object (I<obj_raw>) or an object abstraction (I<object_abstract>, see
 L<provider-object(7)>) into an encoded form, and write the result to
 the given OSSL_CORE_BIO.  If the caller wants to get the encoded
-stream to memory, it should provide a L<BIO_s_membuf(3)>.
+stream to memory, it should provide a L<BIO_s_mem(3)> B<BIO>.
 
 The encoder doesn't need to know more about the B<OSSL_CORE_BIO>
 pointer than being able to pass it to the appropriate BIO upcalls (see
@@ -89,10 +89,10 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
-function pointer from a B<OSSL_DISPATCH> element named
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
+function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
-For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
+For example, the "function" OSSL_FUNC_encoder_encode() has these:
 
  typedef int
      (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out,
@@ -101,7 +101,7 @@ For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
                                    int selection,
                                    OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
  static ossl_inline OSSL_FUNC_encoder_encode_fn
-     OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf);
+     OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf);
 
 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
 macros in L<openssl-core_dispatch.h(7)>, as follows:
@@ -116,7 +116,7 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
 
  OSSL_FUNC_encoder_does_selection      OSSL_FUNC_ENCODER_DOES_SELECTION
 
- OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE_DATA
+ OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE
 
  OSSL_FUNC_encoder_import_object       OSSL_FUNC_ENCODER_IMPORT_OBJECT
  OSSL_FUNC_encoder_free_object         OSSL_FUNC_ENCODER_FREE_OBJECT
@@ -127,14 +127,14 @@ The name of an implementation should match the type of object it handles.
 For example, an implementation that encodes an RSA key should be named "RSA".
 Likewise, an implementation that further encodes DER should be named "DER".
 
-Properties can be use to further specify details about an implementation:
+Properties can be used to further specify details about an implementation:
 
 =over 4
 
 =item output
 
 This property is used to specify what type of output implementation
-produces.  Currently known output types are:
+produces.  OpenSSL providers recognize the following output types:
 
 =over 4
 
@@ -152,6 +152,14 @@ An implementation with that output type outputs PEM formatted data.
 
 An implementation with that output type outputs DER formatted data.
 
+=item msblob
+
+An implementation with that output type outputs MSBLOB formatted data.
+
+=item pvk
+
+An implementation with that output type outputs PVK formatted data.
+
 =back
 
 =item structure
@@ -224,7 +232,7 @@ OSSL_FUNC_encoder_import_object().
 
 =head2 Encoding functions
 
-OSSL_FUNC_encoder_encode() should take an provider-native object (in
+OSSL_FUNC_encoder_encode() should take a provider-native object (in
 I<obj_raw>) or an object abstraction (in I<obj_abstract>), and should output
 the object in encoded form to the B<OSSL_CORE_BIO>.  The I<selection> bits,
 if relevant, should determine in greater detail what will be output.
@@ -328,7 +336,7 @@ OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on
 failure.
 
 OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
-parameters was invalid or caused an error, for which 0 is returned.
+parameter was invalid or caused an error, for which 0 is returned.
 
 OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
 constant B<OSSL_PARAM> elements.
@@ -336,7 +344,7 @@ constant B<OSSL_PARAM> elements.
 OSSL_FUNC_encoder_does_selection() returns 1 if the encoder implementation
 supports any of the I<selection> bits, otherwise 0.
 
-OSSL_FUNC_encoder_encode() return 1 on success, or 0 on failure.
+OSSL_FUNC_encoder_encode() returns 1 on success, or 0 on failure.
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/provider-kdf.pod b/doc/man7/provider-kdf.pod
index a13f3b108c..034f82a262 100644
--- a/doc/man7/provider-kdf.pod
+++ b/doc/man7/provider-kdf.pod
@@ -53,7 +53,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_kdf_newctx() has these:
diff --git a/doc/man7/provider-kem.pod b/doc/man7/provider-kem.pod
index 3ed9ff11fc..f7476e5e9d 100644
--- a/doc/man7/provider-kem.pod
+++ b/doc/man7/provider-kem.pod
@@ -56,7 +56,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_kem_newctx() has these:
diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod
index 0fc36c5da6..ebfcd85153 100644
--- a/doc/man7/provider-keyexch.pod
+++ b/doc/man7/provider-keyexch.pod
@@ -54,7 +54,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_keyexch_newctx() has these:
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index ce24cc485f..9a11b316c2 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -78,7 +78,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from a B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_keymgmt_new() has these:
diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 1f7810c16c..3d49e4f412 100644
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -54,7 +54,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_mac_newctx() has these:
diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index fe8a68b77c..9cb3a620c3 100644
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -99,7 +99,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition
-named B<OSSL_{name}_fn>, and a helper function to retrieve the
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
 function pointer from an B<OSSL_DISPATCH> element named
 B<OSSL_FUNC_{name}>.
 For example, the "function" OSSL_FUNC_signature_newctx() has these:
diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod
index 0609b812c2..32f4e467ac 100644
--- a/doc/man7/provider-storemgmt.pod
+++ b/doc/man7/provider-storemgmt.pod
@@ -50,7 +50,7 @@ provider_query_operation() function
 (see L<provider-base(7)/Provider Functions>).
 
 All these "functions" have a corresponding function type definition named
-B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer
+B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the function pointer
 from a B<OSSL_DISPATCH> element named B<OSSL_get_{name}>.
 For example, the "function" OSSL_FUNC_store_load() has these: