iaik.security.ssl
Class TrustedAuthority

java.lang.Object
  iaik.security.ssl.TrustedAuthority

All Implemented Interfaces:

java.lang.Cloneable

public class TrustedAuthority
extends java.lang.Object
implements java.lang.Cloneable

This class represents a TrustedAuthority as used by the TLS trusted_ca_keys extension (see RFC 4366).

A TrustedAuthority identifies some specific client-trusted ca key by identifier type and identifier:

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

TLS specifies the following four identifier types:

1. pre_agreed: does not provide any identification information about the CA root key
2. key_sha1_hash: the CA root key is identified by a SHA-1 hash of the public key. For DSA and ECDSA keys the hash is calculated from the subjectPublicKey field, for RSA keys the hash is calculated from the big-endian byte representation of the modulus (without leading 0-bytes) (see RFC 4366).
3. x509_name: the CA root key is identified by the DER encoded distinguished name of the CA
4. cert_sha1_hash: the CA root key is identified by the SHA-1 hash of the DER encoded CA certificate

When creating a TrustedAuthority object you have to specify the identifier type that shall be used for identifying the ca key. However, you may let iSaSiLk calculate the identifier from the ca certificate or you may calculate the identifier yourself and explicitly set it when creating the TrustedAuthority object:

  // the trusted ca certificate
  X509Ceritifcate caCert = ...;
  // create TrustedAuthority
  TrustedAuthority ta = new TrustedAuthority(TrustedAuthority.ID_CERT_SHA1_HASH, caCert);
 

respectively

 // the (already calculated) identifier
  byte[] identifier = ...;
  // create TrustedAuthority
  TrustedAuthority ta = new TrustedAuthority(TrustedAuthority.ID_CERT_SHA1_HASH, identifier);
 

After having created a TrustedAuthority for each of your trusted ca keys, include them into a TrustedAuthorities list to be sent to the server within a trusted_ca_keys extension:

 // 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);
 ...
 

However, generally you may prefer to do not use this TrustedAuthority class at all and only tell iSaSiLk which identifier shall be used for the trusted authorities included in a TrustedAuthorities list:

 // 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);
 ...
 

Field Summary

static int	ID_CERT_SHA1_HASH Identifier type CERT_SHA1_HASH (3).
static int	ID_KEY_SHA1_HASH Identifier type KEY_SHA1_HASH (1).
static int	ID_PRE_AGREED Identifier type PRE_AGREED (0).
static int	ID_X509_NAME Identifier type X509_NAME (2).

Constructor Summary

TrustedAuthority(int identifierType, byte[] identifier)
Creates a TrustedAuthority for given identifier type and identifier.

TrustedAuthority(int identifierType, java.security.cert.X509Certificate certificate)
Creates a TrustedAuthority for the given identifier type from the certificate of the trusted authority.

Method Summary

java.lang.Object	clone() Gets a clone of this TrustedAuthority.
boolean	equals(java.lang.Object obj) Checks if this TrustedAuthority is equal to the given object.
byte[]	getIdentifier() Gets the identifier of this TrustedAuthority.
int	getIdentifierType() Gets the identifier type of this TrustedAuthority.
java.lang.String	getIdentifierTypeAsString() Gets the identifier type of this TrustedAuthority as String.
int	hashCode() Gets a hash code of this ServerName.
boolean	identifies(java.security.cert.X509Certificate certificate) Checks if the given certificate is identified by this TrustedAuthority.
java.lang.String	toString() Gets a String representation of this TrustedAuthority.

Methods inherited from class java.lang.Object

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

Field Detail

ID_PRE_AGREED

public static final int ID_PRE_AGREED

Identifier type PRE_AGREED (0). If this identifier type is used no identification information about the CA root key is provided.

See Also:

Constant Field Values

ID_KEY_SHA1_HASH

public static final int ID_KEY_SHA1_HASH

Identifier type KEY_SHA1_HASH (1). If this identifier type is used the CA root key is identified by a SHA-1 hash of the public key. For DSA and ECDSA keys the hash is calculated from the subjectPublicKey field, for RSA keys the hash is calculated from the big-endian byte representation of the modulus (without leading 0-bytes) (see RFC 4366).

See Also:

Constant Field Values

ID_X509_NAME

public static final int ID_X509_NAME

Identifier type X509_NAME (2). If this identifier type is used the CA root key is identified by the DER encoded distinguished name of the CA.

See Also:

Constant Field Values

ID_CERT_SHA1_HASH

public static final int ID_CERT_SHA1_HASH

Identifier type CERT_SHA1_HASH (3). If this identifier type is used the CA root key is identified by the SHA-1 hash of the DER encoded CA certificate.

See Also:

Constant Field Values

Constructor Detail

TrustedAuthority

public TrustedAuthority(int identifierType,
                        byte[] identifier)

Creates a TrustedAuthority for given identifier type and identifier.

Parameters:

identifierType - the identifier type; PRE_AGREED (0), KEY_SHA1_HASH (1), KEY_X509_NAME (2), or CERT_SHA1_HASH (3)

identifier - the identifier; as byte array (will be not cloned!) (use a empty byte array for specifying an identifier of type PRE_AGREED) (the identifier byte array is not cloned or copied by this method)

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)), or if identifier is null (use a empty byte array for specifying an identifier of type PRE_AGREED), or of invalid length (not 20 bytes in case of trype KEY_SHA1_HASH or CERT_SHA1_HASH)

TrustedAuthority

public TrustedAuthority(int identifierType,
                        java.security.cert.X509Certificate certificate)
                 throws java.lang.Exception

Creates a TrustedAuthority for the given identifier type from the certificate of the trusted authority. This constructor uses SecurityProvider method SecurityProvider.calculateTrustedAuthorityIdentifier to calculate an identifier of requested type from the given certificate.

Parameters:

identifierType - the identifier type; PRE_AGREED (0), KEY_SHA1_HASH (1), KEY_X509_NAME (2), or CERT_SHA1_HASH (3)

certificate - the certificate of the trusted authority from which the identifier of the requested type has 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)), or if certificate is null

java.lang.Exception - if an error occurs when calculating the identifier from the certificate

Method Detail

getIdentifierType

public int getIdentifierType()

Gets the identifier type of this TrustedAuthority.

Returns:

the identifier type

getIdentifierTypeAsString

public java.lang.String getIdentifierTypeAsString()

Gets the identifier type of this TrustedAuthority as String.

Returns:

the identifier type as String

getIdentifier

public byte[] getIdentifier()

Gets the identifier of this TrustedAuthority.

Returns:

the identifier (not cloned!)

identifies

public boolean identifies(java.security.cert.X509Certificate certificate)
                   throws java.lang.Exception

Checks if the given certificate is identified by this TrustedAuthority.

Parameters:

certificate - the certificate to be checked

Returns:

true if this TrustedAuthority identifies the certificate, false if not

Throws:

java.lang.Exception - if the check cannot be performed because an identifier of the type cannot be calculated from the certificate

clone

public java.lang.Object clone()

Gets a clone of this TrustedAuthority.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this TrustedAuthority

hashCode

public int hashCode()

Gets a hash code of this ServerName.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code of this ServerName

equals

public boolean equals(java.lang.Object obj)

Checks if this TrustedAuthority is equal to the given object.

Overrides:

equals in class java.lang.Object

Returns:

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

toString

public java.lang.String toString()

Gets a String representation of this TrustedAuthority.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this TrustedAuthority