Add KEM (Key encapsulation mechanism) support to providers

SP800-56Br2 requires support for the RSA primitives for RSASVE generate and recover.
As these are simple KEM operations another operation type has been added that can support future extensions.

Added public functions EVP_PKEY_encapsulate_init(), EVP_PKEY_encapsulate(), EVP_PKEY_decapsulate_init() and EVP_PKEY_decapsulate()
Added EVP_KEM_* functions.
Added OSSL_FUNC_kem_* dispatch functions

Added EVP_PKEY_CTX_set_kem_op() so that different types of KEM can be added in the future. This value must currently be set to
"RSASVE" after EVP_PKEY_encapsulate_init() & EVP_PKEY_decapsulate_init() as there is no default value.
This allows the existing RSA key types, keymanagers, and encoders to be used with the encapsulation operations.

The design of the public API's resulted from contributions from @romen & @levitte.

Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12750)

5 files changed, 74 insertions, 1 deletions

diff --git a/include/crypto/evp.h b/include/crypto/evp.h
index 4912760230..7016606757 100644
--- a/include/crypto/evp.h
+++ b/include/crypto/evp.h
@@ -50,6 +50,10 @@ struct evp_pkey_ctx_st {
             EVP_ASYM_CIPHER *cipher;
             void *ciphprovctx;
         } ciph;
+        struct {
+            EVP_KEM *kem;
+            void *kemprovctx;
+        } encap;
     } op;
 
     /*
@@ -665,6 +669,10 @@ struct evp_pkey_st {
     ((ctx)->operation == EVP_PKEY_OP_PARAMGEN \
      || (ctx)->operation == EVP_PKEY_OP_KEYGEN)
 
+#define EVP_PKEY_CTX_IS_KEM_OP(ctx) \
+    ((ctx)->operation == EVP_PKEY_OP_ENCAPSULATE \
+     || (ctx)->operation == EVP_PKEY_OP_DECAPSULATE)
+
 void openssl_add_all_ciphers_int(void);
 void openssl_add_all_digests_int(void);
 void evp_cleanup_int(void);
diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h
index ad1df714ea..5c6a4f4848 100644
--- a/include/openssl/core_dispatch.h
+++ b/include/openssl/core_dispatch.h
@@ -193,6 +193,7 @@ OSSL_CORE_MAKE_FUNC(int, provider_self_test, (void *provctx))
 # define OSSL_OP_KEYEXCH                            11
 # define OSSL_OP_SIGNATURE                          12
 # define OSSL_OP_ASYM_CIPHER                        13
+# define OSSL_OP_KEM                                14
 /* New section for non-EVP operations */
 # define OSSL_OP_ENCODER                            20
 # define OSSL_OP_DECODER                            21
@@ -717,6 +718,37 @@ OSSL_CORE_MAKE_FUNC(int, asym_cipher_set_ctx_params,
 OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, asym_cipher_settable_ctx_params,
                     (void *provctx))
 
+/* Asymmetric Key encapsulation */
+# define OSSL_FUNC_KEM_NEWCTX                  1
+# define OSSL_FUNC_KEM_ENCAPSULATE_INIT        2
+# define OSSL_FUNC_KEM_ENCAPSULATE             3
+# define OSSL_FUNC_KEM_DECAPSULATE_INIT        4
+# define OSSL_FUNC_KEM_DECAPSULATE             5
+# define OSSL_FUNC_KEM_FREECTX                 6
+# define OSSL_FUNC_KEM_DUPCTX                  7
+# define OSSL_FUNC_KEM_GET_CTX_PARAMS          8
+# define OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS     9
+# define OSSL_FUNC_KEM_SET_CTX_PARAMS         10
+# define OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS    11
+
+OSSL_CORE_MAKE_FUNC(void *, kem_newctx, (void *provctx))
+OSSL_CORE_MAKE_FUNC(int, kem_encapsulate_init, (void *ctx, void *provkey))
+OSSL_CORE_MAKE_FUNC(int, kem_encapsulate, (void *ctx,
+                                           unsigned char *out, size_t *outlen,
+                                           unsigned char *secret,
+                                           size_t *secretlen))
+OSSL_CORE_MAKE_FUNC(int, kem_decapsulate_init, (void *ctx, void *provkey))
+OSSL_CORE_MAKE_FUNC(int, kem_decapsulate, (void *ctx,
+                                           unsigned char *out, size_t *outlen,
+                                           const unsigned char *in, size_t inlen))
+OSSL_CORE_MAKE_FUNC(void, kem_freectx, (void *ctx))
+OSSL_CORE_MAKE_FUNC(void *, kem_dupctx, (void *ctx))
+OSSL_CORE_MAKE_FUNC(int, kem_get_ctx_params, (void *ctx, OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, kem_gettable_ctx_params, (void *provctx))
+OSSL_CORE_MAKE_FUNC(int, kem_set_ctx_params,
+                    (void *ctx, const OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, kem_settable_ctx_params, (void *provctx))
+
 /* Encoders and decoders */
 # define OSSL_FUNC_ENCODER_NEWCTX                      1
 # define OSSL_FUNC_ENCODER_FREECTX                     2
diff --git a/include/openssl/core_names.h b/include/openssl/core_names.h
index 9a6cc2c03d..0fc2868d5b 100644
--- a/include/openssl/core_names.h
+++ b/include/openssl/core_names.h
@@ -475,9 +475,15 @@ extern "C" {
 #define OSSL_PKEY_PARAM_RSA_TEST_Q2  "q2"
 #define OSSL_SIGNATURE_PARAM_KAT "kat"
 
+/* KEM parameters */
+#define OSSL_KEM_PARAM_OPERATION            "operation"
+
+/* OSSL_KEM_PARAM_OPERATION values */
+#define OSSL_KEM_PARAM_OPERATION_RSASVE     "RSASVE"
+
 /* Capabilities */
 
-/* TLS-GROUP Capbility */
+/* TLS-GROUP Capability */
 #define OSSL_CAPABILITY_TLS_GROUP_NAME              "tls-group-name"
 #define OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL     "tls-group-name-internal"
 #define OSSL_CAPABILITY_TLS_GROUP_ID                "tls-group-id"
diff --git a/include/openssl/evp.h b/include/openssl/evp.h
index ff97198542..d3892982e7 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -1496,6 +1496,8 @@ int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, const void *id, int len);
 int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
 int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);
 
+int EVP_PKEY_CTX_set_kem_op(EVP_PKEY_CTX *ctx, const char *op);
+
 const char *EVP_PKEY_get0_first_alg_name(const EVP_PKEY *key);
 
 # define EVP_PKEY_OP_UNDEFINED           0
@@ -1511,6 +1513,8 @@ const char *EVP_PKEY_get0_first_alg_name(const EVP_PKEY *key);
 # define EVP_PKEY_OP_ENCRYPT             (1<<10)
 # define EVP_PKEY_OP_DECRYPT             (1<<11)
 # define EVP_PKEY_OP_DERIVE              (1<<12)
+# define EVP_PKEY_OP_ENCAPSULATE         (1<<13)
+# define EVP_PKEY_OP_DECAPSULATE         (1<<14)
 
 # define EVP_PKEY_OP_TYPE_SIG    \
         (EVP_PKEY_OP_SIGN | EVP_PKEY_OP_VERIFY | EVP_PKEY_OP_VERIFYRECOVER \
@@ -1689,6 +1693,18 @@ void EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,
                                   void (*fn)(const char *name, void *data),
                                   void *data);
 
+void EVP_KEM_free(EVP_KEM *wrap);
+int EVP_KEM_up_ref(EVP_KEM *wrap);
+OSSL_PROVIDER *EVP_KEM_provider(const EVP_KEM *wrap);
+EVP_KEM *EVP_KEM_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+                       const char *properties);
+int EVP_KEM_is_a(const EVP_KEM *wrap, const char *name);
+int EVP_KEM_number(const EVP_KEM *wrap);
+void EVP_KEM_do_all_provided(OPENSSL_CTX *libctx,
+                             void (*fn)(EVP_KEM *wrap, void *arg), void *arg);
+void EVP_KEM_names_do_all(const EVP_KEM *wrap,
+                          void (*fn)(const char *name, void *data), void *data);
+
 int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
                   unsigned char *sig, size_t *siglen,
@@ -1714,6 +1730,15 @@ int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
 int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
 
+int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx);
+int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx,
+                         unsigned char *wrappedkey, size_t *wrappedkeylen,
+                         unsigned char *genkey, size_t *genkeylen);
+int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx);
+int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx,
+                         unsigned char *unwrapped, size_t *unwrappedlen,
+                         const unsigned char *wrapped, size_t wrappedlen);
+
 typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
 
 int EVP_PKEY_param_fromdata_init(EVP_PKEY_CTX *ctx);
diff --git a/include/openssl/types.h b/include/openssl/types.h
index cd0c51e8bf..ee024cef29 100644
--- a/include/openssl/types.h
+++ b/include/openssl/types.h
@@ -123,6 +123,8 @@ typedef struct evp_signature_st EVP_SIGNATURE;
 
 typedef struct evp_asym_cipher_st EVP_ASYM_CIPHER;
 
+typedef struct evp_kem_st EVP_KEM;
+
 typedef struct evp_Encode_Ctx_st EVP_ENCODE_CTX;
 
 typedef struct hmac_ctx_st HMAC_CTX;