ENCODER: Add support for OSSL_FUNC_encoder_does_selection()

OSSL_FUNC_encoder_does_selection() is a dispatchable encoder implementation
function that should return 1 if the given |selection| is supported by an
encoder implementation and 0 if not.  This can be used by libcrypto
functionality to figure out if an encoder implementation should be
considered or not.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13167)

1 files changed, 12 insertions, 3 deletions

diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod
index 92a8b2d3ec..2fcbd6499a 100644
--- a/doc/man7/provider-encoder.pod
+++ b/doc/man7/provider-encoder.pod
@@ -24,6 +24,9 @@ provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions
  int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
  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);
+
  /* Functions to encode object data */
  int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out,
                               const void *obj_raw,
@@ -111,6 +114,8 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
  OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
  OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS
 
+ OSSL_FUNC_encoder_does_selection      OSSL_FUNC_ENCODER_DOES_SELECTION
+
  OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE_DATA
 
  OSSL_FUNC_encoder_import_object       OSSL_FUNC_ENCODER_IMPORT_OBJECT
@@ -171,13 +176,16 @@ be encoded, with a set of bits I<selection> that are passed in an B<int>.
 This set of bits depend entirely on what kind of provider-side object is
 passed.  For example, those bits are assumed to be the same as those used
 with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when
-the object is an asymmetric key.
+the object is an asymmetric keypair.
 
 ENCODER implementations are free to regard the I<selection> as a set of
 hints, but must do so with care.  In the end, the output must make sense,
 and if there's a corresponding decoder, the resulting decoded object must
 match the original object that was encoded.
 
+OSSL_FUNC_encoder_does_selection() should tell if a particular implementation
+supports any of the combinations given by I<selection>.
+
 =head2 Context functions
 
 OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of
@@ -215,8 +223,6 @@ OSSL_FUNC_encoder_import_object().
 
 =head2 Encoding functions
 
-=for comment There will be a "Decoding functions" title as well
-
 OSSL_FUNC_encoder_encode() should take an 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,
@@ -321,6 +327,9 @@ parameters 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.
 
+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.
 
 =head1 SEE ALSO