iaik.security.ssl

Class TrustedAuthorities

java.lang.Object

iaik.security.ssl.Extension

iaik.security.ssl.TrustedAuthorities

All Implemented Interfaces:

java.lang.Cloneable

public class TrustedAuthorities
extends Extension
implements java.lang.Cloneable

This class implements the TrustedAuthorities structure as used by the trusted_ca_keys TLS extension.

A TLS client may use the trusted_ca_keys extension to indicate to the server which ca keys he is willing to trust. This information maybe used by the server to select a proper certificate chain for authenticating itself to the client.
The trusted_ca_keys extension allows a client to send a list of trusted authorities within the extended ClientHello message. The server then may check if he has a certificate that has been issued by any of the trusted authorities received from the client. TLS specifies several types -- pre_agreed (no information), key_sha1_hash (SHA-1 hash of the public ca key), x509_name (DER encoded distinguished name of the CA), cert_sha1_hash (SHA-1 hash of the DER encoded CA certificate) -- that may be used for identifying a trusted ca (see RFC 4366):

   struct {
      TrustedAuthority trusted_authorities_list<0..2^16-1>;
   } TrustedAuthorities;

   struct {
      IdentifierType identifier_type;
      select (identifier_type) {
          case pre_agreed: struct {};
          case key_sha1_hash: SHA1Hash;
          case x509_name: DistinguishedName;
          case cert_sha1_hash: SHA1Hash;
      } identifier;
   } TrustedAuthority;

   enum {
      pre_agreed(0), key_sha1_hash(1), x509_name(2),
      cert_sha1_hash(3), (255)
   } IdentifierType;

   opaque DistinguishedName<1..2^16-1>;
 

On the client side, if you want to send a trusted_ca_keys extension to the server, you may let iSaSiLk calculate the trusted authorities or you may explicitly calculate and set them when creating a TrustedAuthorities object.
In the first case iSaSiLk will ask the inherent client ChainVerifier for a list of trusted ca certificates to calculate a corresponding list of TrustedAuthority elements. All these elements will all have the identifier type that you have specified when creating the TrustedAuthorities object:

 // identifier type 
 int identifierType = TrustedAuthority.ID_CERT_SHA1_HASH;
 // create TrustedAuthorities 
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities(identifierType);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 // extensions are only defined for TLS
 clientContext.setAllowedProtocolVersions(SSLContext.VERSION_TLS10, SSLContext.VERSION_TLS12); 
 ...
 clientContext.setExtensions(extensions);
 ...
 

When setting the TrustedAuthorities list of a trusted_ca_keys extension for an SSLClientContext, iSaSiLk asks the client chain verifier for the trusted CA certificates and calculates a TrustedAuthority of identifier type CERT_SHA1_HASH for each trusted CA certificate.

You also can use the empty default constructor to create a TrustedAuthorities object on the client side. In this case iSaSiLk will calculate and send a TrustedAuthority of identifier type CERT_SHA1_HASH for each trusted CA certificate.

On the client side, if you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a trusted_ca_keys extension.

On the server side you only have to tell the SSLServerContext configuration whether to support the trusted_ca_keys extension or not. The server only will send an empty TrustedAuthorities list in response to a trusted_ca_keys extension received from the client. Thus no trusted authorities are required when configuring the SSLServerContext to support the trusted_ca_keys extension:

 // create TrustedAuthorities
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 

If you set the critical flag of a server-side trusted_ca_keys extension to true, the handshake will be aborted if the client does not send a trusted_ca_keys extension within the extended ClientHello message.

Version:

File Revision 34

See Also:

TrustedAuthority, Extension, ExtensionList

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
TrustedAuthorities() Creates a new TrustedAuthorities object.
TrustedAuthorities(int identifierType) Creates a TrustedAuthorities object with the given identifier type.
TrustedAuthorities(int identifierType, java.security.cert.X509Certificate[] certificates) Creates a TrustedAuthorities object with the given identifier type for certificates of several trusted authorities.
TrustedAuthorities(TrustedAuthority[] authorities) Creates a TrustedAuthorities object with the given authorities.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this TrustedAuthorities object.
boolean	contains(TrustedAuthority trustedAuthority) Checks id this TrustedAuthorities object contains the given TrustedAuthority element.
TrustedAuthority[]	getTrustedAuthorities() Gets the trusted authorities included in this TrustedAuthorities list.
TrustedAuthority[]	getTrustedAuthorities(int identifierType) Gets all trusted authorities included in this TrustedAuthorities list that have the given identifier.
java.lang.String	toString() Gets a String representation of this TrustedAuthorities object.

Methods inherited from class iaik.security.ssl.Extension

getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final ExtensionType TYPE

The type (3) of the trusted_ca_keys extension.

Constructor Detail

TrustedAuthorities

public TrustedAuthorities()

Creates a new TrustedAuthorities object.
This constructor shall be used on the server side to enable trusted_ca_keys extension support for the SSLServerContext configuration:

 // create TrustedAuthorities
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 

If you set the critical flag of this extension to true, the handshake will be aborted if the client does not send a trusted_ca_keys extension within the extended ClientHello message.

If the client has sent a trusted_ca_keys extension, the server will respond with an empty trusted_ca_keys extension.

If this constructor is used on the client side iSaSiLk tries to calculate and send a list of trusted authorities of type CERT_SHA1_HASH from the trusted ca keys that have been configured for the iSaSiLk client.

TrustedAuthorities

public TrustedAuthorities(int identifierType)

Creates a TrustedAuthorities object with the given identifier type.
This constructor may be used on the client side to let iSaSiLk calculate and send a list of trusted authorities of the given identifier type from the given ca certificates. This constructor may be used on the client side to let iSaSiLk calculate and send a list of trusted authorities of the given identifier type from the trusted ca keys that have been configured for the iSaSiLk client. To, for instance, calculate and send trusted authorities of identifier type CERT_SHA1_HASH specifiy TrustedAuthority.ID_CERT_SHA1_HASH when creating the Trustedauthorities object:

 // create TrustedAuthorities
 int identifierType = TrustedAuthority.ID_CERT_SHA1_HASH; 
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities(identifierType);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 

When now sending a trusted_ca_keys extension to the server, iSaSiLk asks the client chain verifier for the trusted CA certificates and calculates a TrustedAuthority of identifier type CERT_SHA1_HASH for each trusted CA certificate. (Note that the same identifier type (CERT_SHA1_HASH) will be used when you create a TrustedAuthorities object with the empty default constructor on the client side). If the client chain verifier does not contain trusted ca certificates, no trusted_ca_keys extension will be sent at all.

If you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a trusted_ca_keys extension.

Parameters:

identifierType - the identifier type of the trusted authorities to be calculated

Throws:

java.lang.IllegalArgumentException - if identifierType is invalid (not PRE_AGREED (0), KEY_SHA1_HASH (1), KEY_X509_NAME (2), or CERT_SHA1_HASH (3))

TrustedAuthorities

public TrustedAuthorities(int identifierType,
                          java.security.cert.X509Certificate[] certificates)
                   throws java.lang.Exception

Creates a TrustedAuthorities object with the given identifier type for certificates of several trusted authorities.
This constructor may be used on the client side to let iSaSiLk calculate and send a list of trusted authorities of the given identifier type from the given ca certificates. The trusted ca certificates maybe got from the trusted ca keys that have been configured for the iSaSiLk client, e.g.:

 // get trusted certs from ChainVerifier
 ChainVerifier chainVerifier = ...;
 X509Certificate trustedCerts = chainVerifier.getTrustedCertificatesArray();
 // create TrustedAuthorities
 int identifierType = TrustedAuthority.ID_CERT_SHA1_HASH; 
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities(identifierType, trustedCerts);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 

Now iSaSiLk tries to calculate a TrustedAuthority of identifier type CERT_SHA1_HASH for each of the given trusted CA certificate.

If you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a trusted_ca_keys extension.

Parameters:

identifierType - the identifier type of the trusted authorities to be calculated

certificates - the trusted certificates from which the trusted authorities of the requested type shall be calculated

Throws:

java.lang.IllegalArgumentException - if identifierType is invalid (not PRE_AGREED (0), KEY_SHA1_HASH (1), KEY_X509_NAME (2), or CERT_SHA1_HASH (3))

java.lang.Exception - if an error occurs when calculating the TrustedAuthority for any of the given certificates

TrustedAuthorities

public TrustedAuthorities(TrustedAuthority[] authorities)

Creates a TrustedAuthorities object with the given authorities.
This constructor shall be used on the client side to specify the trusted authorities that shall be sent to the server within an extended ClientHello message, e.g.:

 // create TrustedAuthorities
 TrustedAuthority[] authorities = ...; 
 TrustedAuthorities trustedAuthorities = new TrustedAuthorities(authorities);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(trustedAuthorities);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 

If you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a trusted_ca_keys extension.

Parameters:

authorities - the trusted authorities to be sent to the server (the authorities array is not cloned or copied by this method)

Method Detail

getTrustedAuthorities

public TrustedAuthority[] getTrustedAuthorities()

Gets the trusted authorities included in this TrustedAuthorities list.

Returns:

the trusted authority list as array of TrustedAuthority objects; maybe null or empty if no trusted authorities are included in the list (the returned array is not cloned or copied by this method)

getTrustedAuthorities

public TrustedAuthority[] getTrustedAuthorities(int identifierType)

Gets all trusted authorities included in this TrustedAuthorities list that have the given identifier.

Returns:

all trusted authorities with the given identifier or null if there are no trusted authorities with this identifier

contains

public boolean contains(TrustedAuthority trustedAuthority)

Checks id this TrustedAuthorities object contains the given TrustedAuthority element.

Parameters:

trustedAuthority - the trusted authority to be asked for

Returns:

true if the given trusted authority is included, false if it is not inlcluded

clone

public java.lang.Object clone()

Returns a clone of this TrustedAuthorities object.

Overrides:

clone in class Extension

Returns:

a clone of this TrustedAuthorities

toString

public java.lang.String toString()

Gets a String representation of this TrustedAuthorities object.

Specified by:

toString in class Extension

Returns:

a String representation of the TrustedAuthorities object