iaik.x509.ocsp

Class Response

java.lang.Object

iaik.x509.ocsp.Response

Direct Known Subclasses:

BasicOCSPResponse

public abstract class Response
extends java.lang.Object

This class is the basic implementation for OCSP Response types. Any class which implements a particular OCSP response type must be derived from this class.

The X.509 Online Certificate Status Protocol ( RFC 2560), RFC 6960) allows OCSP responses to be of various type. RFC 2560, 6960 itself only specifies one basic response type ( BasicOCSPResponse) that has to be supported by any conforming implementation. Other response types are identified by their object identifier to be included into the optional responseBytes field of an OCSPResponse message:

 OCSPResponse ::= SEQUENCE {
    responseStatus         OCSPResponseStatus,
    responseBytes          [0] EXPLICIT ResponseBytes OPTIONAL }
 
 ResponseBytes ::=       SEQUENCE {
     responseType   OBJECT IDENTIFIER,
     response       OCTET STRING }
 

Any class implementing a particular response type has to extend this class and therefore has to implement the abstract methods decode, getEncoded and getResponseType. The object identifier to be returned by method getResponseType is the one identifying the particular response type and shall be used for registering the corresponding class as implemenation for this response type, e.g.:

 public class MyResponse extends Response {
 ...
 // the response type
   public static final ObjectID responseType = ...;
 ...
 }
 ...
 // register the implementation:
 ResponseBytes.register(MyResponse.responseType, MyResponse.class);
 

When implementing a response by extending this class please be aware that methods getEncoded and decode only have to convert the response itself (and NOT the responseType OID) into respectively from its DER encoding. More precise, the byte arry parameter of method decode(byte[]) supplies the DER encoding of the response, i.e. the value of the OCTET STRING component of the ResponseBytes object:

 ResponseBytes ::=       SEQUENCE {
     responseType   OBJECT IDENTIFIER,
     response       OCTET STRING }
 

And method getEncoded shall return the DER encoding of the particular response to give the value of the OCTET STRING response component of the ResponseBytes object. Please notice that method decode supplies the DER encoding of the response: when decoding a response it might be useful to keep the original encoding for being able to verify a response that has been signed.

Although RFC 2560, 6960 does not give any recommendations about the general structure of a response type, this class expects extending classes to additionally implement the abstract method getCertificateResponse allowing the response to be queried for status information about a particular certificate identified by its reqCert.

Version:

File Revision 13

See Also:

ResponseBytes, BasicOCSPResponse, ReqCert, CertificateResponse

Constructor Summary

Constructors

Constructor and Description
Response()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	decode(byte[] enc) Decodes a response from its DER encoding.
abstract CertificateResponse	getCertificateResponse(ReqCert reqCert) Searches the response for status information about the certificate identified by the given RegCert ID.
abstract CertificateResponse	getCertificateResponse(X509Certificate targetCert, X509Certificate issuerCert, GeneralName generalName) Searches the response for status information about the certificate identified by the given certificate information.
abstract byte[]	getEncoded() Returns the DER encoding a particular response.
java.lang.String	getName() Returns the name of the response type.
abstract ObjectID	getResponseType() Returns the OID identifying the particular response type.
abstract java.lang.String	toString() Returns a String representation of the response.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Response

public Response()

Method Detail

decode

public abstract void decode(byte[] enc)
                     throws CodingException

Decodes a response from its DER encoding. This method is used by class ResponseBytes when decoding the ASN.1 representation of a particular response. This method only expects the DER encoding of the response, but not the corresponding response type. More precise, the given byte array supplies the DER encoding of the value of the OCTET STRING response component of the ResponseBytes object:

 ResponseBytes ::=       SEQUENCE {
     responseType   OBJECT IDENTIFIER,
     response       OCTET STRING }
 

This method shall not be explicitly called by an application.

Parameters:

enc - the DER encoding of the response, i.e. the value of the OCTET STRING component of a ResponseBytes object

Throws:

CodingException - if an error occurs when decoding the response

getEncoded

public abstract byte[] getEncoded()

Returns the DER encoding a particular response.

The DER encoding returned by this method only represents the response but does not include the corresponding response type. The encoding of will give the value of the OCTET STRING component of the ResponseBytes object:

 ResponseBytes ::=       SEQUENCE {
     responseType   OBJECT IDENTIFIER,
     response       OCTET STRING }
 

This method shall not be explicitly called by an application.

Returns:

the response as ASN1Object

getResponseType

public abstract ObjectID getResponseType()

Returns the OID identifying the particular response type.

Returns:

the OID identifying the response type this class implements

getCertificateResponse

public abstract CertificateResponse getCertificateResponse(X509Certificate targetCert,
                                         X509Certificate issuerCert,
                                         GeneralName generalName)
                                                    throws OCSPException

Searches the response for status information about the certificate identified by the given certificate information.

Each particular certificate response included is expected to be identified by its reqCert identifying the corresponding certificate by one of the following id types:

 ReqCert  ::= CHOICE {
   certID            CertID,
   issuerSerial      [0] IssuerandSerialNumber,
   pKCert            [1] Certificate,
   name              [2] GeneralName,
   certHash          [3] OCTET STRING}
 

When searching an OCSP response for a CertificateResponse the search has to be done by checking the ReqCert identifiers of the certificate responses included.

Since OCSP v2-01 (see draft-ietf-pkix-ocspv2-01) uses not less than five alternatives (certID, issuerSerial, pKCert, name, certHash) to identify the target cert for which status information shall be obtained, it might be the -- hopefully not very probable -- case that an OCSP server responds by using a different reqCert type (namely when maintaining precomputed responses) as the one sent with the client request.
If method getCertificateResponse does not find a certificate response for a given ReqCert thereby throwing an OCSPException there maybe certificate responses included having a different ReqCert type (or -- in the case of certIDs -- using different hash algorithms} as the one queried for. In this case this method can be used for stepping through the certificate responses included and using their ReqCert types for searching for a certificate response for the cert identified by the given certificate data. For each certifcate response included the given certificate information is tried to be "translated" in a ReqCert of appropriate type according to the following rules:

• If a certificate response uses a reqCert of type certID, both targetCert and issuerCert are required; generalName is ignored. From the given certs, a certID is created and checked for equality with the certID of the reqCert of the particular certificate response.
• If a certificate response uses a reqCert of type issuerSerial, the targetCert is required; issuerCert and generalName are ignored. From the given target cert, an IssuerAndSerialNumber object is created and checked for equality with the issuerSerial of the reqCert of the particular certificate response.
• If a certificate response uses a reqCert of type pKCert, the targetCert is required; issuerCert and generalName are ignored. The given target cert is checked for equality with the pKCert of the reqCert of the particular certificate response.
• If a certificate response uses a reqCert of type name, targetCert or generalName are required; issuerCert is ignored. If generalName is present, it is compared with the GeneralName of the reqCert of the particular response. If generalName is null, but targetCert is present, a GeneralName of type directoryName is created from the target cert's SubjectDN and checked for equality with the generalName of the reqCert of the particular certificate response.
• If a certificate response uses a reqCert of type certHash, the targetCert is required; issuerCert and generalName are ignored. From the given target cert a SHA-1 hash is computed and compared with the certHash of the reqCert of the particular certificate response.

Note that any reqCert type can be created if target cert and issuer cert a set.

Assuming, for instance, that you have used method getCertificateResponse for asking if a response for your request is included. The search has stopped by throwing an OCSPException indicating that no certificate response for your ReqCert is included, but there are certificate responses present having a different ReqCert type. Now you may start a second search using the ReqCert types of the certificate responses included, e.g.:

 // the target cert chain
 X509Certificate[] targetCerts = ...;
 // the ReqCert used in the request:
 ReqCert reqCert ...;
 ...
 // search the response by ReqCert ID:
 CertificateResponse certificateResponse = null;
 try {
   certificateResponse = response.getCertificateResponse(reqCert);
 } catch (OCSPException ex) {
   // not found, but cert responses with different types are present
   System.out.println("Not found: " + ex.getMessage());
   System.out.println("Searching again...");
   certificateResponse = response.getCertificateResponse(targetCerts[0],
                                                         targetCerts[1],
                                                         null);
 }
 if (certificateResponse != null) {
  ...
 } else {
   System.out.println("Got no response!");
 }
 

Parameters:

targetCert - the target cert, if required

issuerCert - the cert of the target cert issuer, if required

generalName - a general name (if required for reqCert type "name")

Returns:

a certificate response giving status information about the certificate identified by the given certificate information; or null if no certificate response for the certificate in mind is included

Throws:

OCSPException - if some processing error occurs, e.g. if the ReqCert of some response represents a CertID but the certID's hash algorithm is not supported by the installed providers

getCertificateResponse

public abstract CertificateResponse getCertificateResponse(ReqCert reqCert)
                                                    throws OCSPException

Searches the response for status information about the certificate identified by the given RegCert ID.

Parameters:

reqCert - the reqCert of the certificate for which status information shall be obtained

Returns:

a certificate response giving status information about the certificate identified by the given reqCert; or null if no certificate response for the certificate in mind is included

Throws:

OCSPException - if a certificate response for the given reqCert cannot be found, but certificate responses included having a different reqCert type or -- in the case of certIDs -- using a hash algorithms different to the given certID's one; in this case you may try method getCertificateResponse to use the reqCert types of the certificate responses included

toString

public abstract java.lang.String toString()

Returns a String representation of the response.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of the response.

getName

public java.lang.String getName()

Returns the name of the response type.

Returns:

the name of the response type