diff options
author | Matt Caswell <matt@openssl.org> | 2020-05-21 15:57:35 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2020-06-19 10:19:31 +0100 |
commit | 3c49e4ff519abee92d9557eca8653ab82cd5787c (patch) | |
tree | 72e4dad1cca4bfd19f2b26cc4422c66307357497 /doc | |
parent | 381f3f3bbc930abb98ddc6ddff847f2d55e73a0c (diff) |
Add documentation about Capabilities
Document the OSSL_PROVIDER_get_capabilities() function as well as the
provider side support for capabilities.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11914)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OSSL_PROVIDER.pod | 22 | ||||
-rw-r--r-- | 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<OSSL_PROVIDER> 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<prov> with the capability name +I<capability>. For each capability of that name supported by the provider it +will call the callback I<cb> and supply a set of B<OSSL_PARAM>s describing the +capability. It will also pass back the argument I<arg>. For more details about +capabilities and what they can be used for please see +L<provider-base(7)/CAPABILTIIES>. + =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<NULL> 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<libcrypto>): 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<OSSL_ITEM> 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<cb> passing +it a set of B<OSSL_PARAM>s and the caller supplied argument I<arg>. The +B<OSSL_PARAM>s should provide details about the capability with the name given +in the I<capability> argument relevant for the provider context I<provctx>. 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</CAPABILITIES> 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<OSSL_PARAM(3)> as L<OSSL_PARAM_int(3)>. +=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<OSSL_CAPABILITY_TLS_GROUP_NAME>) <utf8 string> + +The name of the group as given in the IANA TLS Supported Groups registry +L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>. + +=item "tls-group-name-internal" (B<OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL>) <utf8 string> + +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<OSSL_CAPABILITY_TLS_GROUP_ID>) <unsigned integer> + +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. +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 +B<OSSL_PKEY_PARAM_GROUP_NAME> when libssl wishes to generate keys/parameters. + +=item "tls-group-sec-bits" (B<OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS>) <unsigned integer> + +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<OSSL_CAPABILITY_TLS_GROUP_MIN_TLS>) <integer> + +=item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_TLS>) <integer> + +=item "tls-min-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS>) <integer> + +=item "tls-max-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS>) <integer> + +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 |