iaik.security.ssl

Class KeyAndCert

java.lang.Object

iaik.security.ssl.KeyAndCert

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

KeyAndCertURL, OCSPCertStatusKeyAndCert

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

This class stores a key and the corresponding certificate chain. It is used throughout the library whenever credentials are needed. The certificate chain must contain the end entity certificate at index 0.

Constructor Summary

Constructors

Constructor and Description
KeyAndCert(java.security.cert.X509Certificate[] chain, java.security.PrivateKey privateKey) Creates a new KeyAndCert object.
KeyAndCert(java.security.cert.X509Certificate[] chain, java.security.PrivateKey privateKey, int certType) Creates a new KeyAndCert object.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Get a clone of this object.
boolean	equals(java.lang.Object obj) Tests if the given object is equal to this KeyAndCert.
java.security.cert.X509Certificate[]	getCertificateChain() Gets the certificate chain.
byte[]	getCertificateStatus(int statusType, byte[] statusRequest, SSLTransport transport) Gets information about the (revocation) status of the certificates of this KeyAndCertificate.
int	getCertificateType() Gets the certificate type.
java.security.PrivateKey	getPrivateKey() Gets the private key.
ServerName[]	getTLSServerNames() Gets the TLS server names associated with this KeyAndCert.
int	hashCode() Gets a hashcode for this object.
protected KeyAndCert	isTrustedBy(TrustedAuthorities trustedAuthorities) Checks if this KeyAndCert contains a certificate that is identified as trusted ca by any of the TrustedAuthority elements of the given TrustedAuthorities extension.
void	setTLSServerNames(ServerName[] serverNames) Associates this KeyAndCert with a collection of TLS server names.
void	setTrustedAuthorities(TrustedAuthorities trustedAuthorities) Sets any Trusted Authorities that may be explicitly used to identify this KeyAndCert as trusted by some particular trusted authorities that may be sent by the client within a TrustedAuthorities extension.
java.lang.String	toString() Return a string representation of this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyAndCert

public KeyAndCert(java.security.cert.X509Certificate[] chain,
                  java.security.PrivateKey privateKey)

Creates a new KeyAndCert object. Both arguments must be non-null and the chain has to consist of at least one element.

Parameters:

chain - the ceritificate chain with the end entity (client/server) certificate at index 0 (the chain cert array is not cloned or copied by this method)

privateKey - the private key

Throws:

java.lang.NullPointerException - if both certificate chain and private key are null

KeyAndCert

public KeyAndCert(java.security.cert.X509Certificate[] chain,
                  java.security.PrivateKey privateKey,
                  int certType)

Creates a new KeyAndCert object. Both arguments must be non-null and the chain has to consist of at least one element.

Parameters:

chain - the ceritificate chain with the end entity (client/server) certificate at index 0 (the chain cert array is not cloned or copied by this method)

privateKey - the private key

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)

Throws:

java.lang.NullPointerException - if both certificate chain and private key are null

java.lang.IllegalArgumentException - if the given cert type is invalid (not between CERTTYPE_RSA_SIGN and (CERTTYPE_ECDSA_FIXED_ECDH

Method Detail

getPrivateKey

public final java.security.PrivateKey getPrivateKey()

Gets the private key.

Returns:

the private key

getCertificateChain

public final java.security.cert.X509Certificate[] getCertificateChain()

Gets the certificate chain.

Returns:

the certificate chain (the returned cert array is not cloned or copied by this method)

getCertificateType

public final int getCertificateType()

Gets the certificate type. It will be one of the constants defined in SSLContext. Note that this method returns RSA_SIGN for all RSA certificates irrespective of their actual extensions.

Returns:

the certificate type

See Also:

SSLContext.CERTTYPE_RSA_SIGN

hashCode

public int hashCode()

Gets a hashcode for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hashcode

equals

public boolean equals(java.lang.Object obj)

Tests if the given object is equal to this KeyAndCert.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to be compared with this KeyAndCert

Returns:

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

clone

public java.lang.Object clone()

Get a clone of this object.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

Return a string representation of this object.

Overrides:

toString in class java.lang.Object

setTLSServerNames

public void setTLSServerNames(ServerName[] serverNames)

Associates this KeyAndCert with a collection of TLS server names. This method is only meaningful for server credentials. It can be used to map the certificate of this server credential to TLS ServerNames that may be sent by the client in an extended ClientHello message. If the client has sent a Server Name Indication extension, an iSaSiLk server checks his cerdentials to see if he has a certificate that matches to any of the server names provided by the client.

This method may be used to explicitly specify server names for the server certificate contained in this server KeyAndCert. If no server names are explicitly specified, they are calculated from the server certificate, if required. Server name calculation is done by calling the SecurityProvider method getTLSServerName(int nameType, X509Certificate serverCert), where nameType represents the TLS server name type. The default implementation supports server name caluclation for the name type "HostName" which currently is the only one name type defined by the TLS Extensions specification (see RFC 4366):

   struct {
       NameType name_type;
       select (name_type) {
           case host_name: HostName;
       } name;
   } ServerName;
 
   enum {
       host_name(0), (255)
   } NameType;
 
   opaque HostName<1..2^16-1>;
   
   struct {
       ServerName server_name_list<1..2^16-1>
   } ServerNameList;
 

Parameters:

serverNames - the server names to be associated with the server certificate of this server KeyAndCert (the serverNames array is not cloned or copied by this method)

getTLSServerNames

public ServerName[] getTLSServerNames()

Gets the TLS server names associated with this KeyAndCert. Server names are only meaningful for server credentials. They map the certificate of a server credential to TLS ServerNames that may be sent by the client in an extended ClientHello message. If the client has sent a Server Name Indication extension, an iSaSiLk server checks his cerdentials to see if he has a certificate that matches to any of the server names provided by the client.

If no server names have been explicitly set by the application, this method calculates them from the server certificate by calling the SecurityProvider method getTLSServerName(int nameType, X509Certificate serverCert), The default implementation supports server name caluclation for the name type "HostName" which currently is the only one name type defined by the TLS Extensions specification (see RFC 4366):

   struct {
       NameType name_type;
       select (name_type) {
           case host_name: HostName;
       } name;
   } ServerName;
 
   enum {
       host_name(0), (255)
   } NameType;
 
   opaque HostName<1..2^16-1>;
   
   struct {
       ServerName server_name_list<1..2^16-1>
   } ServerNameList;
 

Returns:

the server names associated with the server certificate of this server KeyAndCert; the array may be empty if no server names are associated with the server certificate of this KeyAndCert (the returned array is not cloned or copied by this method)

isTrustedBy

protected KeyAndCert isTrustedBy(TrustedAuthorities trustedAuthorities)

Checks if this KeyAndCert contains a certificate that is identified as trusted ca by any of the TrustedAuthority elements of the given TrustedAuthorities extension.

This method compares the identifier of any of the TrustedAuthority elements of the given TrustedAuthorities extension with a same-type identifier calculated for any of the certificates of this KeyAndCert object. If any of the certificate-identifiers matches to any of the TrustedAuthority-identifiers, a KeyAndCert object is returned with the matching certificate at certChain index [n-1] (or will contain all its original certificates if it has been explicitly configured to be used for specific trusted authorities). If no appropriate certificate is found, null is returned to indicate that this KeyAndCert cannot be used as server credential for a session with the client that has sent the given TrustedAuthorities extension. Attention: This method uses the SecurityProvider method calculateTrustedAuthorityIdentifier to calculate TrustedAuthority identifiers for the certificates of this KeyAndCert object. Identifiers for the TrustedAuthority identifier type PRE_AGREED will always be an empty byte array. Thus if the client has sent a TrustedAuthorities extension with identifier type PRE_AGREED this KeyAndCert object will be recognized as appropriate in any case. Since PRE_AGREED depends on out-of-band agreement between the communicating parties it cannot be handled in a global way; you may override this method to implement a particular server credential selection policy for TrustedAuthorities of type PRE_AGREED.

Parameters:

trustedAuthorities - the TrustedAuthorities identifying some trusted ca keys

Returns:

a KeyAndCert object with the certificate that is identified by the given TrustedAuthorities at certChain index [n-1] or nullif none of the certs is identified by the TrustedAuthorities

Throws:

java.lang.NullPointerException - if trustedAuthorities is null

setTrustedAuthorities

public void setTrustedAuthorities(TrustedAuthorities trustedAuthorities)

Sets any Trusted Authorities that may be explicitly used to identify this KeyAndCert as trusted by some particular trusted authorities that may be sent by the client within a TrustedAuthorities extension. This method is only meaningful for server credentials.

Parameters:

trustedAuthorities - the trusted authrorities used to identify this KeyAndCert

getCertificateStatus

public byte[] getCertificateStatus(int statusType,
                                   byte[] statusRequest,
                                   SSLTransport transport)
                            throws SSLException

Gets information about the (revocation) status of the certificates of this KeyAndCertificate. This method is used on the server side for asking for certficate status information when the client has sent a status_request extension within an extended client_hello message.

If the client has sent a status_request extension and the server has agreed to provide a status responce, he will send a certificate_status handshake message immediately after the certificate message. This method is called by iSaSiLk to ask for status information of the certificates included in this server credentials. The given statusType indicates the type of status response expected by the client (currently only "ocsp" is defined). The given statusRequest represents the (TLS) encoded request field of the CertificateStatusRequest structure sent by the client (see RFC 4366):

 struct {
    CertificateStatusType status_type;
        select (status_type) {
            case ocsp: OCSPStatusRequest;
        } request;
    } CertificateStatusRequest;

    enum { ocsp(1), (255) } CertificateStatusType;

    struct {
        ResponderID responder_id_list<0..2^16-1>;
        Extensions  request_extensions;
    } OCSPStatusRequest;

    opaque ResponderID<1..2^16-1>;
    opaque Extensions<0..2^16-1>;
 

The status response returned by this method must represent the (TLS) encoded response field of the CertificateStatus handshake message to be sent to the client (see RFC 4366):

 struct {
    CertificateStatusType status_type;
    select (status_type) {
        case ocsp: OCSPResponse;
    } response;
 } CertificateStatus;

 opaque OCSPResponse<1..2^24-1>;
 

It is not possible to implement (OCSP) certificate status requests / responses in a provider independent way. For that reason by default null is returned by this method to indicate that by default no status information can be obtained. To support OCSP you may use the IAIK-JCE based class OCSPCertStatusKeyAndCert for your server credentials.

Parameters:

statusType - the type of the certificate status request received from the client

statusRequest - the (TLS) encoded status request received from the client

transport - the current SSLTransport object (may be used for printing debug information)

Returns:

the (TLS) encoded status response of the the requested type containing (revocation) status information for the certificates contained in this server KeyAndCert; by default null is returned

Throws:

SSLException - if an error occurs when processing the status request and/or creating the status response

See Also:

OCSPCertStatusKeyAndCert