iaik.security.ssl

Class KeyAndCertURL

java.lang.Object

iaik.security.ssl.KeyAndCert

iaik.security.ssl.KeyAndCertURL

All Implemented Interfaces:

java.lang.Cloneable

public class KeyAndCertURL
extends KeyAndCert

This class represents client credentials to be used when a client_certificate_url extension has been negotiated.

Instead of sending its certificate(s) to the server a constrained client may send a list of URLs from where the server can get the client certificate(s) (see RFC 4366):

 enum {
   individual_certs(0), pkipath(1), (255)
 } CertChainType;

 enum {
   false(0), true(1)
 } Boolean;

 struct {
    CertChainType type;
    URLAndOptionalHash url_and_hash_list<1..2^16-1>;
 } CertificateURL;

 struct {
    opaque url<1..2^16-1>;
    Boolean hash_present;
    select (hash_present) {
       case false: struct {};
       case true: SHA1Hash;
    } hash;
 } URLAndOptionalHash;

 opaque SHA1Hash[20];
 

To tell iSaSiLk which client certificate url(s) shall be sent to server use KeyAndCertURL objects instead of common KeyAndCert objects when configuring the client credentials of your SSLClientContext. When creating a KeyAndCertURL object you have to specify the following information:

1. The type of the client certificate of this KeyAndCert object; either CERTTYPE_RSA_SIGN (1), CERTTYPE_DSS_SIGN (2), CERTTYPE_RSA_FIXED_DH (3), or CERTTYPE_DSS_FIXED_DH (4). This information is requited to check if this KeyAndCertURL is appropriate for the certificate types the server may sent within its CertificateRequest message.
2. The private key of the client
3. The certificate chain type telling the server if the URLAndOptionalHash list included in this KeyAndCertURL object separatly refers to each certificate of the client certificate chain (cert chain type CHT_INDIVIDUAL_CERTS (0)), or if it refers to a location from where the whole client certificate chain can be downloaded as pki path (DER encoded SEQUENCE of Certificate) containing the client certificate at index [n-1] (cert chain type CHT_PKI_PATH (1)).
4. A list of URLAndOptionalHash objects containing url(s) that point to location(s) from where the client certificate(s) can be obtained. Depending on the specified cert chain type, the URLAndOptionalHash either may separatly refer each client certificate or may refer to a pki path containing the client certificates. Each URLAndOptionalHash} object may also contain a SHA-1 hash calculated over the DER encoded (individual) certificate or over the DER encoded pki path.

The follwing example assumes that the client ceritificate chain consits of three certificates. The root ca certificate shall not be referenced by the URLAndOptionalHash list since the server may have got it by other means (and use it as trust anchor). Thus two certificates (the client certificate and the intermediate ca certificate) are referred by the URLAndOptionalHash list. We assume that the client certificate is an RSA certificate and that the hash field is present in each URLAndOptionalHash object to allow the server to verify that the certificate(s) downloaded from the referenced (urls) actually correspond to those referred by the client:

  // URLAndOptionalHash for client certificate
  String clientCertUrl = ...;
  URLAndOptionalHash clientUrlAndHash = new URLAndOptionalHash(clientCertUrl);
  // SHA-1 hash of client certificate
  byte[] clientCertHash = ...;
  clientUrlAndHash.setHash(clientCertHash);
  // URLAndOptionalHash for intemediate ca certificate
  String caCertUrl = ...;
  URLAndOptionalHash caUrlAndHash = new URLAndOptionalHash(caCertUrl);
  // SHA-1 hash of intermediate ca certificate
  byte[] caCertHash = ...;
  caUrlAndHash.setHash(caCertHash);
  // create URLAndOptionalHash list:
  URLAndOptionalHash[] urlAndOptionalHashList = 
     { clientUrlAndHash, caUrlAndHash };
  // create client credentials (certificate type is RSA_SIGN)
  int certType = SSLContext.CERTTYPE_RSA_SIGN;
  // the private key of the client:
  PrivateKey privateKey ...;
  // the two certificates of the client chain are referred individually:
  int certChainType = KeyAndCertURL.CHT_INDIVIDUAL_CERTS;
  // create KeyAndCertURL
  KeyAndCertURL keyAndCertUrl = new KeyAndCertURL(certType,
                                                  privateKey,
                                                  certChainType,
                                                  urlAndOptionalHashList);   
    
  // set as client credentials
  SSLClientContext context = ...;
  ...
  context.addClientCredentials(keyAndCertUrl);     
  ...
  

Now, if the iSaSiLk client has been configured (and the server agrees) to use a client_certificate_url extension, the URLAndOptionalHash list of the client credentials added above are sent to server within a CertificateURL handshake message to tell him form where to get the client ceritificates.

If you want to refer to a pki path instead of listing each certificate by a separate url, use the CHT_PKI_PATH option when creating the KeyAndCertURL object:

  // URLAndOptionalHash referring a pki path containing the client certificates
  String clientPkiPathUrl = ...;
  URLAndOptionalHash clientPkiPathUrlAndHash = new URLAndOptionalHash(clientPkiPathUrl);
  // set optional hash value calculated from the DER encoded pki path
  byte[] clientPkiPathHash = ...;
  clientPkiPathUrlAndHash.setHash(clientPkiPathHash);
  // create URLAndOptionalHash list containing one element:
  URLAndOptionalHash[] urlAndOptionalHashList = { clientPkiPathUrlAndHash };
  // create client credentials (certificate type is RSA_SIGN)
  int certType = SSLContext.CERTTYPE_RSA_SIGN;
  // the private key of the client:
  PrivateKey privateKey ...;
  // the two certificates of the client chain are referred by a pki path:
  int certChainType = KeyAndCertURL.CHT_PKI_PATH;
  // create KeyAndCertURL
  KeyAndCertURL keyAndCertUrl = new KeyAndCertURL(certType,
                                                  privateKey,
                                                  certChainType,
                                                  urlAndOptionalHashList);   
    
  // set as client credentials
  SSLClientContext context = ...;
  ...
  context.addClientCredentials(keyAndCertUrl);     
  ...
  

Note that -- when using client certificate urls -- it is not possible to consider accepted authorities that may be sent by the server within the CertificateRequest message -- except you hold the certificates on the client side, too, and use the #KeyAndCertURL(X509Certificate[] chain, PrivateKey privateKey, int certChainType, String[] urls, boolean includeHash) constructor for creating your client credentials; however the intended usage of client certificate urls is for constrained clients which do not want to store their certificates.

See Also:

ClientCertificateURL, URLAndOptionalHash

Field Summary

Fields

Modifier and Type	Field and Description
static int	CHT_INDIVIDUAL_CERTS Certificate chain type individual_certs.
static int	CHT_PKI_PATH Certificate chain type pkiPath (1).

Constructor Summary

Constructors

Constructor and Description
KeyAndCertURL(int certType, java.security.PrivateKey privateKey, int certChainType, URLAndOptionalHash[] urlAndOptionalHashList) Creates a KeyAndCertList for given certificate type, URLAndOptionalHash list and private key.
KeyAndCertURL(java.security.cert.X509Certificate[] chain, java.security.PrivateKey privateKey, int certChainType, java.lang.String[] urls, boolean includeHash) Creates a KeyAndCertList for given certificate chain, url list and private key.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Gets a clone of this object.
boolean	equals(java.lang.Object obj) Tests if the given object is equal to this KeyAndCertURL.
int	getCertChainType() Gets the certificate chain type.
URLAndOptionalHash[]	getURLAndOptionalHashList() Gets the URLAndOptionalHashList contained in this KeyAndCertURL.
int	hashCode() Gets a hashcode for this object.
java.lang.String	toString() Gets a string representation of this object.

Methods inherited from class iaik.security.ssl.KeyAndCert

getCertificateChain, getCertificateStatus, getCertificateType, getPrivateKey, getTLSServerNames, isTrustedBy, setTLSServerNames, setTrustedAuthorities

Methods inherited from class java.lang.Object

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

Field Detail

CHT_INDIVIDUAL_CERTS

public static final int CHT_INDIVIDUAL_CERTS

Certificate chain type individual_certs. Has to be set if a list of client certificate urls is used, if of them pointing to a location from where to download a DER encoded client certificate.

See Also:

Constant Field Values

CHT_PKI_PATH

public static final int CHT_PKI_PATH

Certificate chain type pkiPath (1). Has to be set if one single client certificate url is used to point to a location from where to download the client certificate(s) as PkiPath (ASN.1 SEQUENCE of Certificate).

See Also:

Constant Field Values

Constructor Detail

KeyAndCertURL

public KeyAndCertURL(int certType,
                     java.security.PrivateKey privateKey,
                     int certChainType,
                     URLAndOptionalHash[] urlAndOptionalHashList)

Creates a KeyAndCertList for given certificate type, URLAndOptionalHash list and private key. The certificate type is required to check if this KeyAndCert is appopriate for the certificate type(s) that maybe sent by the server within a CertificateRequest message.
The URLAndOptionalHash tells the server from where it can get the client certificate(s). Depending on the certificate chain type, the client cert(s) can be downloaded as individual certs (each client certificate separatly as DER encoded X.509 certificate) or as pki path (the whole client certificate chain as DER encoded SEQUENCE of Certificate containing the client certificate at index [n-1]; the top-level certificate maybe not included in the chain).

Parameters:

certType - the type of the client certificate of this KeyAndCert object; either CERTTYPE_RSA_SIGN (1), CERTTYPE_DSS_SIGN (2), CERTTYPE_RSA_FIXED_DH (3), CERTTYPE_DSS_FIXED_DH (4), CERTTYPE_ECDSA_SIGN (64), CERTTYPE_RSA_FIXED_ECDH (65), or CERTTYPE_ECDSA_FIXED_ECDH (66)

privateKey - the private key of the client

certChainType - the cert chain type, either CHT_INDIVIDUAL_CERTS (0) (when each of the given URLAndOptionalHash objects refers to a single DER encoded certificate of the client cert chain), or CHT_PKI_PATH (1) (when the URLAndOptionalHash list contains only one element that points to a location from where the client certificate chain can be downloaded as DER encoded pki path)

urlAndOptionalHashList - an array of URLAndOptionalHash objects pointing to location(s) from where the client certificate(s) can be obtained; the array may contain only one element to refer to a pki path or may contain as many elements as necessary for separatly referring each certificate of the client certificate chain. (the urlAndOPtionalHashList array is not cloned or copied by this method)

Throws:

java.lang.NullPointerException - if the private key is null or the given URLAndOptionalHash list is empty

java.lang.IllegalArgumentException - if the given cert type is invalid (not between CERTTYPE_RSA_SIGN and (CERTTYPE_ECDSA_FIXED_ECDH, or the given certChainType is invalid (not (0) CHT_INDIVIDUAL_CERTS (0) or (1) CHT_PKI_PATH (1)

KeyAndCertURL

public KeyAndCertURL(java.security.cert.X509Certificate[] chain,
                     java.security.PrivateKey privateKey,
                     int certChainType,
                     java.lang.String[] urls,
                     boolean includeHash)
              throws java.lang.Exception

Creates a KeyAndCertList for given certificate chain, url list and private key.
This constructor only is provided for convenience to allow to create an KeyAndCertList object if you have access to the certificate chain. However, the client_certificate_url extension is intended for constrained clients who want to avoid to store their certificate(s) (and therefore only send the certificate urls to the server so that he can get it from there). Thus, generally this constructor may not be used in practice (except for if you, for instance, have no problem to store the certificate(s) but want to save transmission bandwidth).

Parameters:

chain - the certificate chain of the client with the client end entity certificate at index 0

privateKey - the private key of the client

certChainType - the cert chain type, either CHT_INDIVIDUAL_CERTS (0) (when each of the given urls refers to a single DER encoded certificate of the client cert chain), or CHT_PKI_PATH (1) (when the url list contains only one element that points to a location from where the client certificate chain can be downloaded as DER encoded pki path)

urls - an array of Strings representing urls that point to location(s) from where the client certificate(s) can be obtained; the array may contain only one element to refer to a pki path or may contain as many elements as necessary for separately referring each certificate of the client certificate chain

includeHash - whether to calculate and include a SHA-1 hash into each of the URLAndOptionalHash objects to be calculated for this KeyAndCertURL object

Throws:

java.lang.NullPointerException - if the private key is null or the given chain/url lists are empty

java.lang.IllegalArgumentException - if the given cert type is invalid (not between CERTTYPE_RSA_SIGN (1) and (CERTTYPE_DSS_FIXED_DH (4), or the given certChainType is invalid (not (0) CHT_INDIVIDUAL_CERTS (0) or (1) CHT_PKI_PATH (1)

java.lang.Exception - if an error occurs while calculating the URLAndOptionalHash list

Method Detail

getCertChainType

public int getCertChainType()

Gets the certificate chain type.

Returns:

the cert chain type; either CT_INDIVIDUAL_CERTS (0), or CT_PKI_PATH (1)

getURLAndOptionalHashList

public URLAndOptionalHash[] getURLAndOptionalHashList()

Gets the URLAndOptionalHashList contained in this KeyAndCertURL.

Returns:

the URLAndOptionalHashList (the returned array is not cloned or copied by this method)

hashCode

public int hashCode()

Gets a hashcode for this object.

Overrides:

hashCode in class KeyAndCert

Returns:

the hashcode

equals

public boolean equals(java.lang.Object obj)

Tests if the given object is equal to this KeyAndCertURL.

Overrides:

equals in class KeyAndCert

Parameters:

obj - the object to be compared with this KeyAndCertURL

Returns:

true if the two objects are equal, false if they are not equal

clone

public java.lang.Object clone()

Gets a clone of this object.

Overrides:

clone in class KeyAndCert

Returns:

the cloned object

toString

public java.lang.String toString()

Gets a string representation of this object.

Overrides:

toString in class KeyAndCert

Returns:

a String representation