iaik.security.ssl

Class SignatureAlgorithms

java.lang.Object

iaik.security.ssl.Extension

iaik.security.ssl.SignatureAlgorithms

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

SignatureAlgorithmsCert

public class SignatureAlgorithms
extends Extension
implements java.lang.Cloneable

This class implements the TLS 1.2 / TLS 1.3 signature_algorithms extension as specified by RFC 5246 and RFC 8446.

A TLS client may send a SignatureAlgorithms extension with the ClientHello extension list to tell the server which signature algorithms the client can process to, e.g., verify the server certificates or, e.g., sign the CertificateVerify message.
In TLS 1.2 (RFC 5246) the extension is defined to contain a list of SignatureAndHashAlgorithm elements specifying the supported signature algorithms as pairs of hash and signature algorithm ids:

    enum {
        none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5),
        sha512(6), (255)
    } HashAlgorithm;

     enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) }
       SignatureAlgorithm;

     struct {
          HashAlgorithm hash;
          SignatureAlgorithm signature;
    } SignatureAndHashAlgorithm;

    SignatureAndHashAlgorithm
      supported_signature_algorithms<2..2^16-2>;
 

The following SignatureAndHash algorithms are supported by iSaSiLk:

• SHA256withRSA (id: 0x0401)
• SHA256withECDSA (id: 0x0403)
• SHA256withDSA (id: 0x0402)
• SHA512withRSA (id: 0x0601)
• SHA512withECDSA (id: 0x0603)
• SHA512withDSA (id: 0x0602)
• SHA384withRSA (id: 0x0501)
• SHA384withECDSA (id: 0x0503)
• SHA384withDSA (id: 0x0502)
• SHA224withRSA (id: 0x0301)
• SHA224withECDSA (id: 0x0303)
• SHA224withDSA (id: 0x0302)
• SHA1withRSA (id: 0x0201)
• SHA1withECDSA (id: 0x0203)
• SHA1withDSA (id: 0x0202)
• MD5withRSA (id: 0x0101)
• ED25519 (id: 0x0807)
• ED448 (id: 0x0808)
• SignatureAndHashAlgorithm.SHA256withRSAPSS_RSAE (id: 0x0804)
• SignatureAndHashAlgorithm.SHA384withRSAPSS_RSAE (id: 0x0805)
• SignatureAndHashAlgorithm.SHA512withRSAPSS_RSAE (id: 0x0806)
• SignatureAndHashAlgorithm.SHA256withRSAPSS_PSS (id: 0x0809)
• SignatureAndHashAlgorithm.SHA384withRSAPSS_PSS (id: 0x080a)
• SignatureAndHashAlgorithm.SHA512withRSAPSS_PSS (id: 0x080b)

TLS 1.3 (RFC 8446) replaces the SignatureAndHashAlgorithm type and its hash-signature-algorithm pair ids by the SignatureScheme type identifying each signature scheme by an simple id without any further hash/signature algorithm interpretation:

    enum {
         // RSASSA-PKCS1-v1_5 algorithms 
         rsa_pkcs1_sha256(0x0401),
         rsa_pkcs1_sha384(0x0501),
         rsa_pkcs1_sha512(0x0601),

         // ECDSA algorithms 
         ecdsa_secp256r1_sha256(0x0403),
         ecdsa_secp384r1_sha384(0x0503),
         ecdsa_secp521r1_sha512(0x0603),

         // RSASSA-PSS algorithms with public key OID rsaEncryption 
         rsa_pss_rsae_sha256(0x0804),
         rsa_pss_rsae_sha384(0x0805),
         rsa_pss_rsae_sha512(0x0806),

         // EdDSA algorithms 
         ed25519(0x0807),
         ed448(0x0808),

         // RSASSA-PSS algorithms with public key OID RSASSA-PSS 
         rsa_pss_pss_sha256(0x0809),
         rsa_pss_pss_sha384(0x080a),
         rsa_pss_pss_sha512(0x080b),

         // Legacy algorithms 
         rsa_pkcs1_sha1(0x0201),
         ecdsa_sha1(0x0203),

         // Reserved Code Points 
         private_use(0xFE00..0xFFFF),
         (0xFFFF)
         
    } SignatureScheme;

    struct {
        SignatureScheme supported_signature_algorithms<2..2^16-2>;
    } SignatureSchemeList;
 

For backwards compatibility TLS 1.3 signature scheme ids are equal to the TLS 1.2 signature-and-hash-algorithm ids for equivalent algorithms. For instance, the TLS 1.2 SignatureAndHashAlgorithm SHA256withRSA has the same id as the TLS 1.3 signature scheme rsa_pkcs1_sha256.

The following TLS 1.3 SignatureSchemes are supported by iSaSiLk:

• ed25519 (id: 0x0807)
• ed448 (id: 0x0808)
• ecdsa_secp256r1_sha256 (id: 0x0403)
• ecdsa_secp384r1_sha384 (id: 0x0503)
• ecdsa_secp521r1_sha512 (id: 0x0603)
• rsa_pkcs1_sha256 (id: 0x0401)
• rsa_pkcs1_sha384 (id: 0x0501)
• rsa_pkcs1_sha512 (id: 0x0601)
• rsa_pss_rsae_sha256 (id: 0x0804)
• rsa_pss_rsae_sha384 (id: 0x0805)
• rsa_pss_rsae_sha512 (id: 0x0806)
• rsa_pss_pss_sha256 (id: 0x0809)
• rsa_pss_pss_sha384 (id: 0x080a)
• rsa_pss_pss_sha512 (id: 0x080b)
• rsa_pkcs1_sha1 (id: 0x0201) (TLS 1.2 legacy)
• ecdsa_sha1 (id: 0x0203) (TLS 1.2 legacy)

The following signature schemes are supported for compatibility reasons with TLS 1.2 but are not enabled for TLS 1.3 anymore (and do not belong to the default algorithm set):

• SHA256withDSA (id: 0x0402)
• SHA512withDSA (id: 0x0602)
• SHA384withDSA (id: 0x0502)
• SHA224withRSA (id: 0x0301)
• SHA224withECDSA (id: 0x0303)
• SHA224withDSA (id: 0x0302)
• SHA1withDSA (id: 0x0202)
• MD5withRSA (id: 0x0101)

Note that the TLS 1.3 has deprecated all TLS 1.2 DSA based signature algorithms and all signature algorithms that use SHA-224 as hash algorithm. rsa_pkcs1_sha1 and ecdsa_sha1 are only maintained for interoperability reasons to existing applications using RSA/SHA-1 or ECDSA/SHA-1 certificates. They shall not be for signed TLS handshake messages anymore.
Furthermore the SignatureScheme usage differs somewhat from that of TLS 1.2 SignatureAndHashAlgorithm. Whereas TLS 1.2 ECDSA* signature algorithms may be used with any elliptic curve, TLS 1.3 ecdsa* signature schemes maybe used with the the specific elliptic curve they are explicitly specified for: ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha256 for the NIST curves secp256r1, secp384r1 and secp521r1, respectively.

In TLS 1.2 only clients can send a signature_algorithms extension, TLS servers MUST not send such an extension. In TLS 1.3 TLS servers also may send the signature_algorithms extension within the CertificateRequest message.

For compatibility reasons iSaSiLk can be used with both types, TLS 1.2 SignatureAndHashAlgorithm and TLS 1.3 SignatureScheme. In general the signature_algorithms extension is managed automatically by iSaSiLk; thus an application usually does not have to take any care about it. If TLS 1.2/1.3 is enabled by an iSaSiLk client/server, iSaSiLk automatically includes a default list containing the following signature algorithms / schemes in the following order:

• ecdsa_secp256r1_sha256 (SHA256withECDSA) (id: 0x0403)
• ed25519 (ED25519) (id: 0x0807)
• rsa_pss_rsae_sha256 (SignatureAndHashAlgorithm.SHA256withRSAPSS_RSAE) (id: 0x0804)
• rsa_pkcs1_sha256 (SHA256withRSA) (id: 0x0401)
• ecdsa_secp384r1_sha384 (SHA384withECDSA) (id: 0x0503)
• rsa_pss_rsae_sha384 (SignatureAndHashAlgorithm.SHA384withRSAPSS_RSAE) (id: 0x0805)
• rsa_pkcs1_sha384 (SHA384withRSA) (id: 0x0501)
• ecdsa_secp521r1_sha512 (SHA512withECDSA) (id: 0x0603)
• rsa_pss_rsae_sha512 (SignatureAndHashAlgorithm.SHA512withRSAPSS_RSAE) (id: 0x0806)
• rsa_pkcs1_sha512 (SHA512withRSA) (id: 0x0601)
• rsa_pkcs1_sha1 (SHA1withRSA) (id: 0x0201), legacy
• ecdsa_sha1 (SHA1withECDSA) (id: 0x0203), legacy

If any of these algorithms is not supported by the cryptographic capabilities of the installed SecurityProvider is is removed from the list.

An application only has to deal with the signature_algorithms extension if it wants to explicitly limit the list of supported algorithms to be sent to the server. If you, for instance, only want to use the SHA512withRSA, SHA512withECDSA algorithms you may create a SignatureAlgorithms extension with these two SignatureAndHashAlgorithms or SignatureScheme elements:

 SignatureAndHashAlgorithm[] algorithms = {
   SignatureAndHashAlgorithm.SHA256withRSA,
   SignatureAndHashAlgorithm.SHA256withECDSA
 };
 SignatureAlgorithms signatureAlgorithms = 
   new SignatureAlgorithms(new SignatureAndHashAlgorithmList(algorithms));
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(signatureAlgorithms);
 ...
 // set extensions for the SSLContext configuration:
 SSLContext context = ...;
 // SignatureAlgorithms only meaningful since TLS 1.2
 context.setAllowedProtocolVersions(SSLContext.VERSION_TLS12, SSLContext.VERSION_TLS13); 
 ...
 context.setExtensions(extensions);
 ...
 

respectively (when using SignatureScheme):

 SignatureScheme[] signatureSchemes = {
   SignatureScheme.rsa_pkcs1_sha256,
   SignatureScheme.ecsa_secp256r1_sha256
 };
 SignatureAlgorithms signatureAlgorithms = 
   new SignatureAlgorithms(new SignatureSchemeList(signatureSchemes));
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(signatureAlgorithms);
 ...
 // set extensions for the SSLContext configuration:
 SSLContext context = ...;
 // SignatureAlgorithms only meaningful since TLS 1.2
 context.setAllowedProtocolVersions(SSLContext.VERSION_TLS12, SSLContext.VERSION_TLS13); 
 ...
 context.setExtensions(extensions);
 ...
 

In TLS 1.2, although a server is not allowed to send a signature_algorithms extension iSaSiLk allows to add a SignatureAlgorithms extension to the extension list of an iSaSiLk server. The extension is ignored from the list sent to the client, and only will be used if you want to limit the signature algorithms used by the server (e.g. for signing the ServerKeyExchange message, or suggesting supported signature algorithms for the client CertificateVerify when sending the CertificateRequest message).

Signature algorithms / schemes by this class are those suggested to the peer within the signature_algorithms extension or, e.g. the CeritficateVerify message. They must not contain all algorithms that are supported. By default iSaSiLk checks received signatures if have being signed with a suggested signature algorithm. If you want to accept not only suggested signature algorithms but all signature algorithms you may mark this extension as not critical. By default, both client-side and server-side SignatureAlgorithms extensions are considered as critical.

Version:

File Revision 40

See Also:

Extension, SignatureScheme, SignatureSchemeList, SignatureAndHashAlgorithm, SignatureAndHashAlgorithmList

Field Summary

Fields

Modifier and Type	Field and Description
static ExtensionType	TYPE The type (13) of the signature_algorithms extension.

Constructor Summary

Constructors

Constructor and Description
SignatureAlgorithms() Default constructor.
SignatureAlgorithms(SignatureAndHashAlgorithmList supportedAlgorithms) Creates a SignatureAlgorithms extension from the given list of supported signature algorithms.
SignatureAlgorithms(SignatureSchemeList supportedSignatureSchems) Creates a SignatureAlgorithms extension from the given list of supported signature schemes.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this SignatureAlgorithms extension.
java.lang.Object	clone(int version) Returns a clone of this SignatureAlgorithms extension for the given protocol version.
boolean	equals(java.lang.Object obj) Checks if this SignatureAlgorithms extension is equal to the given object.
SignatureAndHashAlgorithmList	getSupportedAlgorithms() Gets the supported signature algorithms included in this signature algorithms extension.
SignatureSchemeList	getSupportedSignatureSchemes() Gets the supported signature schemes included in this signature algorithms extension.
int	hashCode() Gets a hash code of this SignatureAlgorithms extension.
void	setIgnorePeerPreferenceOrder(boolean ignore) Whether to ignore the preference order of the algorithm list sent by the peer when selecting an signature algorithm for the current session.
java.lang.String	toString() Gets a String representation of this SignatureAlgorithms extension.

Methods inherited from class iaik.security.ssl.Extension

getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final ExtensionType TYPE

The type (13) of the signature_algorithms extension.

Constructor Detail

SignatureAlgorithms

public SignatureAlgorithms()

Default constructor. Creates a new SignatureAlgorithms extension with the default algorithm set.

SignatureAlgorithms

public SignatureAlgorithms(SignatureAndHashAlgorithmList supportedAlgorithms)

Creates a SignatureAlgorithms extension from the given list of supported signature algorithms.
This constructor may be used to specify the supported signature algorithms, e.g.:

 SignatureAndHashAlgorithm[] algorithms = {
   SignatureAndHashAlgorithm.SHA256withRSA,
   SignatureAndHashAlgorithm.SHA256withECDSA
 };
 SignatureAlgorithms signatureAlgorithms = 
   new SignatureAlgorithms(new SignatureAndHashAlgorithmList(algorithms));
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(signatureAlgorithms);
 ...
 // set extensions for the SSLContext configuration:
 SSLContext context = ...;
 // SignatureAlgorithms only meaningful since TLS 1.2
 context.setAllowedProtocolVersions(SSLContext.VERSION_TLS12, SSLContext.VERSION_TLS13); 
 ...
 context.setExtensions(extensions);
 ...
 

Parameters:

supportedAlgorithms - the supported signature algorithms to be used

Throws:

java.lang.IllegalArgumentException - if the given algorithm list is null or empty

See Also:

(TLS 1.3 interoperability; TLS 1.3 uses the term "SignatureSchemeList")

SignatureAlgorithms

public SignatureAlgorithms(SignatureSchemeList supportedSignatureSchems)

Creates a SignatureAlgorithms extension from the given list of supported signature schemes.
This constructor maybe used to specify the supported signature schemes, e.g.:

 SignatureScheme[] signatureSchemes = {
   SignatureScheme.rsa_pkcs1_sha256,
   SignatureScheme.ecdsa_secp256r1_sha256
 };
 SignatureAlgorithms signatureAlgorithms = 
   new SignatureAlgorithms(new SignatureSchemeList(signatureSchemes));
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(signatureAlgorithms);
 ...
 // set extensions for the SSLContext configuration:
 SSLContext context = ...;
 // SignatureAlgorithms only meaningful since TLS 1.2
 context.setAllowedProtocolVersions(SSLContext.VERSION_TLS12, SSLContext.VERSION_TLS13); 
 ...
 context.setExtensions(extensions);
 ...
 

Parameters:

supportedSignatureSchems - the supported signature algorithms to be used

Throws:

java.lang.IllegalArgumentException - if the given algorithm list is null or empty

See Also:

(TLS 1.2 interoperability; TLS 1.2 uses the term "SignatureAndHashAlgorithmList")

Method Detail

getSupportedAlgorithms

public SignatureAndHashAlgorithmList getSupportedAlgorithms()

Gets the supported signature algorithms included in this signature algorithms extension.

If no signature algorithms are included in this extension the default set is returned.

Returns:

the supported signature algorithms as list of SignatureAndHashAlgorithm

See Also:

(TLS 1.3 interoperability; TLS 1.3 uses the term "SignatureScheme")

getSupportedSignatureSchemes

public SignatureSchemeList getSupportedSignatureSchemes()

Gets the supported signature schemes included in this signature algorithms extension.

If no signature schemes are included in this extension the default set is returned.

Returns:

the supported signature schemes as list of SignatureScheme

See Also:

(TLS 1.2 interoperability; TLS 1.2 uses the term "SignatureAndHashAlgorithm")

setIgnorePeerPreferenceOrder

public void setIgnorePeerPreferenceOrder(boolean ignore)

Whether to ignore the preference order of the algorithm list sent by the peer when selecting an signature algorithm for the current session. By default the algorithm is selected according to the preference order sent by the peer.

Parameters:

ignore - whether to ignore the peer algorithm list preference order when selecting the signature algorithm for the current session

hashCode

public int hashCode()

Gets a hash code of this SignatureAlgorithms extension.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code of this SignatureAlgorithms extension

equals

public boolean equals(java.lang.Object obj)

Checks if this SignatureAlgorithms extension is equal to the given object.

Two SignatureAlgorithms extensions are treated as equal if they contain the same signature algorithm / scheme objects (same number and same order). The critical value is not checked by this method.

Overrides:

equals in class java.lang.Object

Returns:

true if this SignatureAlgorithms extension is equal to the given object, false if it is not equal to it

clone

public java.lang.Object clone()

Returns a clone of this SignatureAlgorithms extension.

Overrides:

clone in class Extension

Returns:

a clone of this SignatureAlgorithms extension

clone

public java.lang.Object clone(int version)

Returns a clone of this SignatureAlgorithms extension for the given protocol version.

Parameters:

version - the protocol version

Returns:

a clone of this SignatureAlgorithms extension for the given protocol version

toString

public java.lang.String toString()

Gets a String representation of this SignatureAlgorithms extension.

Specified by:

toString in class Extension

Returns:

a String representation of the SignatureAlgorithms extension