iaik.security.ssl

Class CertificateStatusRequest

java.lang.Object

iaik.security.ssl.Extension

iaik.security.ssl.CertificateStatusRequest

All Implemented Interfaces:

java.lang.Cloneable

public class CertificateStatusRequest
extends Extension
implements java.lang.Cloneable

This class implements the CertificateStatusRequest structure as used by the staus_request TLS extension.

To save bandwidth when obtaining certificate status (revocation) information a client may request that the server shall send a special certificate_status message after his certificate message. To tell the server to provide a certificate_status message the client first sends a status_request extension within an extended client_hello message. Depending on the requested status type (currently only "ocsp" is defined), the status_request extension may contain protocol specific information (e.g. accepted responders and/or ocsp extensions). The server confirms that he will provide a certificate_status message by sending an empty status_request extension within his extended server_hello message (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>;
 

On the client side, when you create a CertificateStatusRequest to be sent within an extended client_hello message, specify the status type (e.g. ocsp) and the status request. Since this class provides a generic way for handling status requests of any type, the request has to be given as byte array representing the TLS encoded request field of the CertificateStatusRequest structure.
You also can use the IAIK-JCE based ocsp status request implementation:

  // create OCSPStatusRequest
  OCSPStatusRequest ocspStatusRequest = ...;
  ...
  // encode ocsp status request
  byte[] statusRequest = ocspStatusRequest.getEncoded();
  // create CertificateStatusRequest of type ocsp:
  CertificateStatusRequest certStatusRequest = 
    new CertificateStatusRequest(OCSPStatusRequest.STATUS_TYPE, statusRequest);
  // add to ExtensionList
  ExtensionList extensions = new ExtensionList();
  ...
  extensions.addExtension(certStatusRequest);
  ...
  // 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);
  ...
 

Attention: If your request extensions contain a Nonce extension please note that the same nonce shall be only used once! Thus do not use the same SSLClientContext with the same CertificateStatusRequest extension repeatedly if the status request contains a Nonce extension!
Alternatively you do not may specify an ocsp status request at all when creating the CertificateStatusRequest extension. In this case iSaSiLk will use the SecurityProvider method createCertStatusRequest to create an OCSP status request with a fresh nonce anytime a new status request is sent:

  // create CertificateStatusRequest extension of type ocsp:
  CertificateStatusRequest certStatusRequest = 
    new CertificateStatusRequest(OCSPStatusRequest.STATUS_TYPE, null);
  // add to ExtensionList
  ExtensionList extensions = new ExtensionList();
  ...
  extensions.addExtension(certStatusRequest);
  ...
  // set extensions for the SSLClientContext configuration:
  SSLClientContext clientContext = new SSLClientContext();
  ...
  clientContext.setExtensions(extensions);
  ...
 

If you set the critical flag of a client-side CertificateStatusRequest to true (client-side default), the handshake will be aborted if the server does not respond with a status_request extension. It will be also aborted if the server does not send a certificate_status handshake message containing the requested status information.

On the server side you only have to tell the SSLServerContext configuration whether to support the status_request extension or not by adding an empty CertificateStatusRequest extension to your server-side extension list:

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

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

Version:

File Revision 34

See Also:

OCSPStatusRequest, Extension, ExtensionList

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATUS_TYPE_OCSP Status type ocsp (1).
static ExtensionType	TYPE The type (5) of the certificate status_request extension.

Constructor Summary

Constructors

Constructor and Description
CertificateStatusRequest() Creates a new CertificateStatusRequest.
CertificateStatusRequest(boolean requestStatusInformationFromClient) Creates a new CertificateStatusRequest.
CertificateStatusRequest(int statusType, byte[] request) Creates a CertificateStatusRequest for the given status type and status request.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this CertificateStatusRequest.
byte[]	getStatusRequest() Gets the status request as byte array.
int	getStatusType() Gets the status type of this certificate status request.
java.lang.String	toString() Gets a String representation of this CertificateStatusRequest.

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 (5) of the certificate status_request extension.

STATUS_TYPE_OCSP

public static final int STATUS_TYPE_OCSP

Status type ocsp (1).

See Also:

Constant Field Values

Constructor Detail

CertificateStatusRequest

public CertificateStatusRequest()

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

 // create CertificateStatusRequest
 CertificateStatusRequest statusRequest = new CertificateStatusRequest();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(statusRequest);
 ...
 // 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 status_request extension within the extended ClientHello message.

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

The status type field is set to ocsp.

CertificateStatusRequest

public CertificateStatusRequest(boolean requestStatusInformationFromClient)

Creates a new CertificateStatusRequest.
This constructor shall be used on the server side to enable status_request extension support for the SSLServerContext configuration. TLS 1.3 allows servers to request OCSP status information from clients, too. In this case the server includes an empty status_request extension in its CertificateRequest message and the client may provide OCSP status information with the CertificateEntries of the TLS 1.3 Certificate message:

 boolean reaquestStatusInformationFromClient = true;
 // create CertificateStatusRequest
 CertificateStatusRequest statusRequest = new CertificateStatusRequest(reaquestStatusInformationFromClient);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(statusRequest);
 ...
 // 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 status_request extension within the extended ClientHello message. If TLS 1.3 is used and the server requests status information from the client then the handshake will also be aborted if the client does not provide OCSP statis information for the client certificate.

The status type field is set to ocsp.

Parameters:

requestStatusInformationFromClient - whether to request OCSP status information from the client (only meaningful for TLS 1.3)

CertificateStatusRequest

public CertificateStatusRequest(int statusType,
                                byte[] request)

Creates a CertificateStatusRequest for the given status type and status request.
This constructor shall be used on the client side to specify the status type and status request. Since this class provides a generic way for handling status requests of any type, the request has to be given as byte array representing the TLS encoded request field of the CertificateStatusRequest structure (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>;
 

You also can use the IAIK-JCE based ocsp status request implementation:

  // create OCSPStatusRequest
  OCSPStatusRequest ocspStatusRequest = ...;
  ...
  // encode ocso status request
  byte[] statusRequest = ocspStatusRequest.getEncoded();
  // create CertificateStatusRequest of type ocsp:
  CertificateStatusRequest certStatusRequest = 
    new CertificateStatusRequest(OCSPStatusRequest.STATUS_TYPE, statusRequest);
  // add to ExtensionList
  ExtensionList extensions = new ExtensionList();
  ...
  extensions.addExtension(certStatusRequest);
  ...
  // set extensions for the SSLClientContext configuration:
  SSLClientContext clientContext = new SSLClientContext();
  ...
  clientContext.setExtensions(extensions);
  ...
 

Attention: If your request extensions contain a Nonce extension please note that the same nonce shall be only used once! Thus do not use the same SSLClientContext with the same CertificateStatusRequest extension repeatedly if the status request contains a Nonce extension!
Alternatively you do not may specify an ocsp status request at all when creating the CertificateStatusRequest extension. In this case iSaSiLk will use the SecurityProvider method createCertStatusRequest to create an OCSP status request with a fresh nonce anytime a new status request is sent:

  // create CertificateStatusRequest extension of type ocsp:
  CertificateStatusRequest certStatusRequest = 
    new CertificateStatusRequest(OCSPStatusRequest.STATUS_TYPE, null);
  // add to ExtensionList
  ExtensionList extensions = new ExtensionList();
  ...
  extensions.addExtension(certStatusRequest);
  ...
  // set extensions for the SSLClientContext configuration:
  SSLClientContext clientContext = new SSLClientContext();
  ...
  clientContext.setExtensions(extensions);
  ...
 

If you set the critical flag of a client-side CertificateStatusRequest to true (client-side default), the handshake will be aborted if the server does not respond with a status_request extension. It will be also aborted if the server does not send a certificate_status handshake message containing the requested status information.

Parameters:

statusType - the type of the status request

request - the (TLS) encoded request field of the CertificateStatusRequest structure; or null to let iSaSiLk calculate the request by calling the SecurityProvider method createCertStatusRequest. (the request byte array is not cloned or copied by this method)

Throws:

java.lang.IllegalArgumentException - if the status type is out of range (not between 0 and 255)

Method Detail

getStatusType

public int getStatusType()

Gets the status type of this certificate status request.

Returns:

the status type

getStatusRequest

public byte[] getStatusRequest()

Gets the status request as byte array. Depending on the status type the request maybe further parsed and processed.

Returns:

the status request (not cloned!)

clone

public java.lang.Object clone()

Returns a clone of this CertificateStatusRequest.

Overrides:

clone in class Extension

Returns:

a clone of this CertificateStatusRequest

toString

public java.lang.String toString()

Gets a String representation of this CertificateStatusRequest.

Specified by:

toString in class Extension

Returns:

a String representation of the CertificateStatusRequest