first cut at sigalg loading

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

1 files changed, 123 insertions, 0 deletions

diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 30b460cb29..c7e15254cd 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -607,6 +607,129 @@ or maximum. A -1 indicates that the group should not be used in that protocol.
 
 =back
 
+=head3 "TLS-SIGALG" Capability
+
+The "TLS-SIGALG" capability can be queried by libssl to discover the list of
+TLS signature algorithms that a provider can support. Each signature supported
+can be used for client- or server-authentication in addition to the built-in
+signature algorithms.
+TLS1.3 clients can advertise the list of TLS signature algorithms they support
+in the signature_algorithms extension, and TLS servers can select an algorithm
+from the offered list that they also support. In this way a provider can add
+to the list of signature algorithms that libssl already supports with
+additional ones.
+
+Each TLS signature algorithm that a provider supports should be described via
+the callback passed in through the provider_get_capabilities function. Each
+algorithm can have the following details supplied:
+
+=over 4
+
+=item "iana-name" (B<OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME>) <UTF8 string>
+
+The name of the signature algorithm as given in the IANA TLS Signature Scheme
+registry as "Description":
+L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme>.
+This value must be supplied.
+
+=item "iana-code-point" (B<OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT>) <unsigned integer>
+
+The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry.
+This value must be supplied.
+
+=item "sigalg-name" (B<OSSL_CAPABILITY_TLS_SIGALG_NAME>) <UTF8 string>
+
+A name for the full (possibly composite hash-and-signature) signature
+algorithm.
+The provider may, but is not obligated to, provide a signature implementation
+with this name; if it doesn't, this is assumed to be a composite of a pure
+signature algorithm and a hash algorithm, which must be given with the
+parameters "sig-name" and "hash-name".
+This value must be supplied.
+
+=item "sigalg-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_OID>) <UTF8 string>
+
+The OID of the "sigalg-name" algorithm in canonical numeric text form. If
+this parameter is given, OBJ_create() will be used to create an OBJ and
+a NID for this OID, using the "sigalg-name" parameter for its (short) name.
+Otherwise, it's assumed to already exist in the object database, possibly
+done by the provider with the core_obj_create() upcall.
+This value is optional.
+
+=item "sig-name" (B<OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME>) <UTF8 string>
+
+The name of the pure signature algorithm that is part of a composite
+"sigalg-name". If "sigalg-name" is implemented by the provider, this
+parameter is redundant and must not be given.
+This value is optional.
+
+=item "sig-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_SIG_OID>) <UTF8 string>
+
+The OID of the "sig-name" algorithm in canonical numeric text form. If
+this parameter is given, OBJ_create() will be used to create an OBJ and
+a NID for this OID, using the "sig-name" parameter for its (short) name.
+Otherwise, it is assumed to already exist in the object database. This
+can be done by the provider using the core_obj_create() upcall.
+This value is optional.
+
+=item "hash-name" (B<OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME>) <UTF8 string>
+
+The name of the hash algorithm that is part of a composite "sigalg-name".
+If "sigalg-name" is implemented by the provider, this parameter is redundant
+and must not be given.
+This value is optional.
+
+=item "hash-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_HASH_OID>) <UTF8 string>
+
+The OID of the "hash-name" algorithm in canonical numeric text form. If
+this parameter is given, OBJ_create() will be used to create an OBJ and
+a NID for this OID, using the "hash-name" parameter for its (short) name.
+Otherwise, it's assumed to already exist in the object database, possibly
+done by the provider with the core_obj_create() upcall.
+This value is optional.
+
+=item "key-type" (B<OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE>) <UTF8 string>
+
+The key type of the public key of applicable certificates. If this parameter
+isn't present, it's assumed to be the same as "sig-name" if that's present,
+otherwise "sigalg-name".
+This value is optional.
+
+=item "key-type-oid" (B<OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID>) <UTF8 string>
+
+The OID of the "key-type" in canonical numeric text form. If
+this parameter is given, OBJ_create() will be used to create an OBJ and
+a NID for this OID, using the "key-type" parameter for its (short) name.
+Otherwise, it's assumed to already exist in the object database, possibly
+done by the provider with the core_obj_create() upcall.
+This value is optional.
+
+=item "sec-bits" (B<OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS>) <unsigned integer>
+
+The number of bits of security offered by keys of this algorithm. The number
+of bits should be comparable with the ones given in table 2 and 3 of the NIST
+SP800-57 document. This number is used to determine the security strength of
+the algorithm if no digest algorithm has been registered that otherwise
+defines the security strength. If the signature algorithm implements its own
+digest internally, this value needs to be set to properly reflect the overall
+security strength.
+This value must be supplied.
+
+=item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS>) <integer>
+
+=item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS>) <integer>
+
+These parameters can be used to describe the minimum and maximum TLS
+versions supported by the signature algorithm. 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 signature
+algorithm should not be used in that protocol.
+Presently values representing anything other than TLS1.3 mean that the
+complete algorithm is ignored.
+
+=back
+
 =head1 NOTES
 
 The core_obj_create() and core_obj_add_sigid() functions were not thread safe