TrustedAuthority (iSaSiLk 6.1 API Documentation)

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:

pre_agreed: does not provide any identification information about the CA root key
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).
x509_name: the CA root key is identified by the DER encoded distinguished name of the CA
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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Class TrustedAuthority

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ID_PRE_AGREED

ID_KEY_SHA1_HASH

ID_X509_NAME

ID_CERT_SHA1_HASH

Constructor Detail

TrustedAuthority

TrustedAuthority

Method Detail

getIdentifierType

getIdentifierTypeAsString

getIdentifier

identifies

clone

hashCode

equals

toString