From c1a74f59ac799087c511d641cb086722817b805b Mon Sep 17 00:00:00 2001 From: Nicola Tuveri Date: Mon, 28 Sep 2020 02:16:29 +0300 Subject: 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 (Merged from https://github.com/openssl/openssl/pull/13018) --- doc/man7/provider-base.pod | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) (limited to 'doc') 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 (KEX) or I (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): =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) 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 +or I (KEM), as implied by the optional +B flag. The algorithm must support key and parameter generation as well as the key/parameter generation parameter, B. 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) + +Boolean flag to describe if the group should be used in I (KEX) +mode (0, default) or in I (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 +then I against the peer public key. To operate in KEX mode, the group +implementation must support the provider functions as described in +L. + +In KEM mode, the client executes I and sends its public key, the server +executes I using the client's public key and sends back the +resulting I, finally the client executes I to retrieve +the same I generated by the server's I. To operate +in KEM mode, the group implementation must support the provider functions as +described in L. + +Both in KEX and KEM mode, the resulting I is then used according +to the protocol specification. + =item "tls-min-tls" (B) =item "tls-max-tls" (B) -- cgit v1.2.1