From 3c49e4ff519abee92d9557eca8653ab82cd5787c Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Thu, 21 May 2020 15:57:35 +0100 Subject: [PATCH] Add documentation about Capabilities Document the OSSL_PROVIDER_get_capabilities() function as well as the provider side support for capabilities. Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/11914) --- doc/man3/OSSL_PROVIDER.pod | 22 +++++++++-- doc/man7/provider-base.pod | 78 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 4 deletions(-) diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod index d6f0af53c9..63633842fa 100644 --- a/doc/man3/OSSL_PROVIDER.pod +++ b/doc/man3/OSSL_PROVIDER.pod @@ -7,7 +7,8 @@ OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload, OSSL_PROVIDER_available, OSSL_PROVIDER_do_all, OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params, OSSL_PROVIDER_query_operation, OSSL_PROVIDER_get0_provider_ctx, -OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines +OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name, +OSSL_PROVIDER_get_capabilities - provider routines =head1 SYNOPSIS @@ -38,6 +39,12 @@ OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines const char *OSSL_PROVIDER_name(const OSSL_PROVIDER *prov); + int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov, + const char *capability, + OSSL_CALLBACK *cb, + void *arg); + + =head1 DESCRIPTION B is a type that holds internal information about @@ -104,15 +111,22 @@ have a short lifetime. OSSL_PROVIDER_name() returns the name of the given provider. +OSSL_PROVIDER_get_capabilities() provides information about the capabilities +supported by the provider specified in I with the capability name +I. For each capability of that name supported by the provider it +will call the callback I and supply a set of Bs describing the +capability. It will also pass back the argument I. For more details about +capabilities and what they can be used for please see +L. + =head1 RETURN VALUES -OSSL_PROVIDER_add() returns 1 on success, or 0 on error. +OSSL_PROVIDER_add(), OSSL_PROVIDER_unload(), OSSL_PROVIDER_get_params() and +OSSL_PROVIDER_get_capabilities() return 1 on success, or 0 on error. OSSL_PROVIDER_load() returns a pointer to a provider object on success, or B on error. -OSSL_PROVIDER_unload() returns 1 on success, or 0 on error. - OSSL_PROVIDER_available() returns 1 if the named provider is available, otherwise 0. diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index 081be53a0d..69183cf282 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -74,6 +74,8 @@ provider-base int operation_id, const int *no_store); const OSSL_ITEM *provider_get_reason_strings(void *provctx); + int provider_get_capabilities(void *provctx, const char *capability, + OSSL_CALLBACK *cb, void *arg); =head1 DESCRIPTION @@ -136,6 +138,7 @@ F): provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS + provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES =head2 Core functions @@ -229,6 +232,15 @@ provider_get_reason_strings() should return a constant B array that provides reason strings for reason codes the provider may use when reporting errors using core_put_error(). +The provider_get_capabilities() function should call the callback I passing +it a set of Bs and the caller supplied argument I. The +Bs should provide details about the capability with the name given +in the I argument relevant for the provider context I. If a +provider supports multiple capabilities with the given name then it may call the +callback multipe times (one for each capability). Capabilities can be useful for +describing the services that a provider can offer. For further details see the +L section below. It should return 1 on success or 0 on error. + None of these functions are mandatory, but a provider is fairly useless without at least provider_query_operation(), and provider_gettable_params() is fairly useless if not accompanied by @@ -332,6 +344,72 @@ pointing at the string "foo,bar" For more information on handling parameters, see L as L. +=head1 CAPABILITIES + +Capabilties describe some of the services that a provider can offer. +Applications can query the capabilities to discover those services. + +=head3 "TLS-GROUP" Capability + +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. + +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): + +=over 4 + +=item "tls-group-name" (B) + +The name of the group as given in the IANA TLS Supported Groups registry +L. + +=item "tls-group-name-internal" (B) + +The name of the group as known by the provider. This could be the same as the +"tls-group-name", but does not have to be. + +=item "tls-group-id" (B) + +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. +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 +B when libssl wishes to generate keys/parameters. + +=item "tls-group-sec-bits" (B) + +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-min-tls" (B) + +=item "tls-max-tls" (B) + +=item "tls-min-dtls" (B) + +=item "tls-max-dtls" (B) + +These parameters can be used to describe the minimum and maximum TLS and DTLS +versions supported by the group. The values equate to the on-the-wire encoding +of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and +TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum +or maximum. A -1 indicates that the group should not be used in that protocol. + +=back + =head1 EXAMPLES This is an example of a simple provider made available as a -- 2.25.1