QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-04-28 18:54:36 +00:00
Code Issues Projects Releases Wiki Activity

Add documentation about Capabilities

Browse Source 
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)
This commit is contained in:
Matt Caswell 2020-05-21 15:57:35 +01:00
parent 381f3f3bbc
commit 3c49e4ff51
2 changed files with 96 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/man3/OSSL_PROVIDER.pod
View File

@ -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.

78
doc/man7/provider-base.pod
View File

@ -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