Define OSSL_CAPABILITY_TLS_GROUP_IS_KEM

Note that with this commit the optional parameter is introduced, but
libssl still ignores it.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13018)

1 files changed, 34 insertions, 7 deletions

diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index efec869e25..b92f117d86 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -364,15 +364,17 @@ Applications can query the capabilities to discover those services.
 
 The "TLS-GROUP" capability can be queried by libssl to discover the list of
 TLS groups that a provider can support. Each group supported can be used for
-key exchange during a TLS handshake. TLS clients can advertise the list of
-TLS groups they support in the supported_groups extension, and TLS servers can
-select a group from the offered list that they also support. In this way a
-provider can add to the list of groups that libssl already supports with
-additional ones.
+I<key exchange> (KEX) or I<key encapsulation method> (KEM) during a TLS
+handshake.
+TLS clients can advertise the list of TLS groups they support in the
+supported_groups extension, and TLS servers can select a group from the offered
+list that they also support. In this way a provider can add to the list of
+groups that libssl already supports with additional ones.
 
 Each TLS group that a provider supports should be described via the callback
 passed in through the provider_get_capabilities function. Each group should have
-the following details supplied (all are mandatory):
+the following details supplied (all are mandatory, except
+B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>):
 
 =over 4
 
@@ -393,7 +395,9 @@ The TLS group id value as given in the IANA TLS Supported Groups registry.
 =item "tls-group-alg" (B<OSSL_CAPABILITY_TLS_GROUP_ALG>) <utf8 string>
 
 The name of a Key Management algorithm that the provider offers and that should
-be used with this group. Keys created should be able to support key exchange.
+be used with this group. Keys created should be able to support I<key exchange>
+or I<key encapsulation method> (KEM), as implied by the optional
+B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM> flag.
 The algorithm must support key and parameter generation as well as the
 key/parameter generation parameter, B<OSSL_PKEY_PARAM_GROUP_NAME>. The group
 name given via "tls-group-name-internal" above will be passed via
@@ -405,6 +409,29 @@ The number of bits of security offered by keys in this group. The number of bits
 should be comparable with the ones given in table 2 and 3 of the NIST SP800-57
 document.
 
+=item "tls-group-is-kem" (B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>) <unsigned integer>
+
+Boolean flag to describe if the group should be used in I<key exchange> (KEX)
+mode (0, default) or in I<key encapsulation method> (KEM) mode (1).
+
+This parameter is optional: if not specified, KEX mode is assumed as the default
+mode for the group.
+
+In KEX mode, in a typical Diffie-Hellman fashion, both sides execute I<keygen>
+then I<derive> against the peer public key. To operate in KEX mode, the group
+implementation must support the provider functions as described in
+L<provider-keyexch(7)>.
+
+In KEM mode, the client executes I<keygen> and sends its public key, the server
+executes I<encapsulate> using the client's public key and sends back the
+resulting I<ciphertext>, finally the client executes I<decapsulate> to retrieve
+the same I<shared secret> generated by the server's I<encapsulate>. To operate
+in KEM mode, the group implementation must support the provider functions as
+described in L<provider-kem(7)>.
+
+Both in KEX and KEM mode, the resulting I<shared secret> is then used according
+to the protocol specification.
+
 =item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_TLS>) <integer>
 
 =item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_TLS>) <integer>