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)

diff --git a/crypto/encode_decode/encoder_local.h b/crypto/encode_decode/encoder_local.h
index be4cba378357655a24517b15f8315d74cebd1d3f..2ff1853b9ffa0283e904fb3ac3267b052e9dd332 100644 (file)
--- a/crypto/encode_decode/encoder_local.h
+++ b/crypto/encode_decode/encoder_local.h
@@ -33,6 +33,7 @@ struct ossl_encoder_st {
     OSSL_FUNC_encoder_gettable_params_fn *gettable_params;
     OSSL_FUNC_encoder_set_ctx_params_fn *set_ctx_params;
     OSSL_FUNC_encoder_settable_ctx_params_fn *settable_ctx_params;
+    OSSL_FUNC_encoder_does_selection_fn *does_selection;
     OSSL_FUNC_encoder_encode_fn *encode;
     OSSL_FUNC_encoder_import_object_fn *import_object;
     OSSL_FUNC_encoder_free_object_fn *free_object;

diff --git a/crypto/encode_decode/encoder_meth.c b/crypto/encode_decode/encoder_meth.c
index adff759bd429a939f38ff7896de1490d14c107ff..99c4a119d3b3929f8dd120ff64f8059e059316b4 100644 (file)
--- a/crypto/encode_decode/encoder_meth.c
+++ b/crypto/encode_decode/encoder_meth.c
@@ -200,6 +200,11 @@ static void *encoder_from_dispatch(int id, const OSSL_ALGORITHM *algodef,
                 encoder->settable_ctx_params =
                     OSSL_FUNC_encoder_settable_ctx_params(fns);
             break;
+        case OSSL_FUNC_ENCODER_DOES_SELECTION:
+            if (encoder->does_selection == NULL)
+                encoder->does_selection =
+                    OSSL_FUNC_encoder_does_selection(fns);
+            break;
         case OSSL_FUNC_ENCODER_ENCODE:
             if (encoder->encode == NULL)
                 encoder->encode = OSSL_FUNC_encoder_encode(fns);

diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod
index 92a8b2d3ec97c66d404005c238fd2f77ae3af89c..2fcbd6499a4c1a6fb9c5456d024d151970a386bc 100644 (file)
--- 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

diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h
index cc8e6712ede113737beb618b6306551f00edaa91..d4d581df5786b02f0b111dcebfe0d0e371e94beb 100644 (file)
--- a/include/openssl/core_dispatch.h
+++ b/include/openssl/core_dispatch.h
@@ -756,7 +756,8 @@ OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, kem_settable_ctx_params, (void *provctx)
 # define OSSL_FUNC_ENCODER_GETTABLE_PARAMS             4
 # define OSSL_FUNC_ENCODER_SET_CTX_PARAMS              5
 # define OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS         6
-# define OSSL_FUNC_ENCODER_ENCODE                     10
+# define OSSL_FUNC_ENCODER_DOES_SELECTION             10
+# define OSSL_FUNC_ENCODER_ENCODE                     11
 # define OSSL_FUNC_ENCODER_IMPORT_OBJECT              20
 # define OSSL_FUNC_ENCODER_FREE_OBJECT                21
 OSSL_CORE_MAKE_FUNC(void *, encoder_newctx, (void *provctx))
@@ -769,10 +770,8 @@ OSSL_CORE_MAKE_FUNC(int, encoder_set_ctx_params,
 OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, encoder_settable_ctx_params,
                     (void *provctx))
 
-/*
- * TODO(3.0) investigate if this should be two functions, one that takes a
- * raw object and one that takes an object abstraction.
- */
+OSSL_CORE_MAKE_FUNC(int, encoder_does_selection,
+                    (void *provctx, int selection))
 OSSL_CORE_MAKE_FUNC(int, encoder_encode,
                     (void *ctx, OSSL_CORE_BIO *out,
                      const void *obj_raw, const OSSL_PARAM obj_abstract[],