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)

diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod
index 108fbceceb6f0aae20176d922212ed4ba97c067b..99207b4e652b613a8ec86c9d72d7ea755e2144ed 100644 (file)
--- 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 29f5468c9f7dda612cc3d9a29c2780d462d525ed..7bead3a45dd12ea2812cde973833f0b2e27150c5 100644 (file)
--- 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 e1d2182fa5af91ef4b83e1478eef94fe60ad84cf..87b7992d84c7003618076eb68e90ae29d0ab2ea0 100644 (file)
--- 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 ce53c61de4e971f758305df3a27c855ba64022df..e92991afa8a815780a7b2cf24531bb755289142a 100644 (file)
--- 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 2b0804b558bc6455e02ae31a89d9304c1a8edd1f..9032036a6ea938dc1fff586eb4b8b5bf174707d3 100644 (file)
--- 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 a13f3b108cec82ddcb48c71a34623039fbf4e67f..034f82a262a53a2115b4478d25638135be704010 100644 (file)
--- 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 3ed9ff11fc902ec53c1033bddbd968339ff35a0b..f7476e5e9d6159a848ed32b17a50ef0c8e2b5eb5 100644 (file)
--- 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 0fc36c5da6975e2ec6d77bc6dd09fd5c3d4cbe3c..ebfcd8515308f9a08b79d5dcef7ed2d2b389f3ba 100644 (file)
--- 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 ce24cc485f1f0e56f07f529e77f732db7509e57f..9a11b316c2b3df9178d17a6cd92a99f47de856bc 100644 (file)
--- 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 1f7810c16cf77e4ef709df025217f39d26d0a9fb..3d49e4f41226e9aad972c367a93b159137fd4175 100644 (file)
--- 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 fe8a68b77cae56970d640462e0cbb4606bd706ea..9cb3a620c339c0b8203ca78d71d4057b077b122c 100644 (file)
--- 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 0609b812c23a96a3df150195d7474d5890e4a3e1..32f4e467ac7e69ceb69d2e95b6c0100ac5663345 100644 (file)
--- 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:
 

diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h
index 214772bc7efd0f2d05e3ea088d19df53b340da9b..1cc2ebcc57d125a419a3613ec741f5ccbb6d9dfa 100644 (file)
--- a/include/openssl/core_dispatch.h
+++ b/include/openssl/core_dispatch.h
@@ -851,7 +851,7 @@ OSSL_CORE_MAKE_FUNC(int, decoder_does_selection,
                     (void *provctx, int selection))
 OSSL_CORE_MAKE_FUNC(int, decoder_decode,
                     (void *ctx, OSSL_CORE_BIO *in, int selection,
-                     OSSL_CALLBACK *metadata_cb, void *metadata_cbarg,
+                     OSSL_CALLBACK *data_cb, void *data_cbarg,
                      OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg))
 OSSL_CORE_MAKE_FUNC(int, decoder_export_object,
                     (void *ctx, const void *objref, size_t objref_sz,