iaik.x509.ocsp
Class SingleResponse

java.lang.Object
  |
  +--iaik.x509.ocsp.SingleResponse

All Implemented Interfaces:

ASN1Type, CertificateResponse

public class SingleResponse

extends Object

implements CertificateResponse

This class implements the OCSP type SingleResponse. Within a BasicOCSPResponse a single response is included for each certificate for which revocation information is requested. Beside an identifier for the certificate in mind a single response contains status information and gives the time at which the status being indicated is known to be correct. Optionally also the time of the next status update and extensions may be included (see OCSP, version 2, draft-ietf-pkix-ocspv2-01.txt):

 SingleResponse ::= SEQUENCE {
   reqCert                      ReqCert,
   certStatus                   CertStatus,
   thisUpdate                   GeneralizedTime,
   nextUpdate           [0]     EXPLICIT GeneralizedTime OPTIONAL,
   singleExtensions     [1]     EXPLICIT Extensions OPTIONAL }
 

When creating a SingleResponse for a specifiec certificate the ReqCert of the certificate has to be supplied. The revocation status of the cert is given by its CertStatus and the thisUpdate date indicates the date at which the given status is known as being correct, e.g.:

 // the reqCert; got from the request
 ReqCert reqCert = request.getReqCert();
 // we assume cert status "unknown"
 CertStatus certStatus = new CertStatus(new UnknownInfo());
 // thisUpdate is today
 Date thisUpdate = new Date();
 // create the single response:
 SingleRespone singleResponse = 
   new SingleResponse(reqCert, certStatus, thisUpdate);
 

After optionally setting the nextUpdate date and adding any extensions the SingleResponse may be included into a BasicOCSPResponse by calling the setSingleResponses method:

 BasicOCSPResponse basicOCSPResponse = ...;
 ...
 basicOCSPResponse.setSingleResponses(new SingleResponse[] { singleResponse });
 

Version:

File Revision 13

See Also:

ReqCert, CertStatus, BasicOCSPResponse

Constructor Summary

SingleResponse()
Default constructor.

SingleResponse(ASN1Object obj)
Creates a SingleResponse from an ASN1Object.

SingleResponse(ReqCert reqCert, CertStatus certStatus, Date thisUpdateDate)
Creates a SingleResponse from reqCert, certStatus and thisUpdate date.

Method Summary

void	addExtension(V3Extension e) Adds the given extension.
int	countExtensions() Returns the number of extensions included in this single response.
void	decode(ASN1Object obj) Creates a SingleResponse from an ASN1Object.
Date	getArchiveCutoff() A convenience method for getting the cutoff time of the ArchiveCutoff extension, if included in this response.
CertStatus	getCertStatus() Returns the certStatus of this SingleResponse.
CrlID	getCrlID() A convenience method for getting the CrlID extension, if included in this single response.
V3Extension	getExtension(ObjectID oid) Returns a specific extension, identified by its object identifier.
Date	getNextUpdate() Returns the nextUpdate date.
ReqCert	getReqCert() Returns the reqCert of this SingleResponse.
Date	getThisUpdate() Returns the thisUpdate date.
boolean	hasExtensions() Checks, if there are any extensions included in this single response.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
boolean	isResponseFor(ReqCert reqCert) Checks if this is a SingleResponse for a certificate identified by the given reqCert identifier.
boolean	isResponseFor(X509Certificate targetCert, X509Certificate issuerCert, GeneralName generalName) Checks if this is a single response for the given certificate identifying information.
Enumeration	listExtensions() Returns an enumeration of all extensions included in this single response.
void	removeAllExtensions() Removes all extensions from this single response.
boolean	removeExtension(ObjectID oid) Removes the extension specified by its object identifier.
void	setArchiveCutoff(Date cutoffTime) A convenience method for setting the value of the ArchiveCutoff extension.
void	setCrlID(CrlID crlID) A convenience method for setting the CrlID extension.
void	setNextUpdate(Date nextUpdateDate) Sets the nextUpdate date.
ASN1Object	toASN1Object() Returns this SingleResponse as an ASN1Object.
String	toString() Returns a String representation of this SingleResponse.
String	toString(boolean detailed) Returns a String representation of this SingleResponse.

Methods inherited from class java.lang.Object

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

Constructor Detail

SingleResponse

public SingleResponse()

Default constructor. Creates an empty SingleResponse object. Only used for dynamic object creation. Shall not be called by an application!.

SingleResponse

public SingleResponse(ReqCert reqCert,
                      CertStatus certStatus,
                      Date thisUpdateDate)

Creates a SingleResponse from reqCert, certStatus and thisUpdate date.

Parameters:

reqCert - the reqCert identifying the certificate for which this single response gives status information

certStatus - the status information for the certificate in mind

thisUpdateDate - the time at which the certStatis is known as being correct

SingleResponse

public SingleResponse(ASN1Object obj)
               throws CodingException,
                      X509ExtensionException

Creates a SingleResponse from an ASN1Object.

Parameters:

obj - the SingleResponse as ASN1Object

Throws:

CodingException - if the ASN1Object has the wrong format

X509ExtensionException - if the extensions cannot be parsed

Method Detail

setNextUpdate

public void setNextUpdate(Date nextUpdateDate)

Sets the nextUpdate date.

Parameters:

nextUpdateDate - the time at or before newer information will be available about the status of the certificate

getReqCert

public ReqCert getReqCert()

Returns the reqCert of this SingleResponse.

Specified by:

getReqCert in interface CertificateResponse

Returns:

the reqCert of this SingleResponse.

getCertStatus

public CertStatus getCertStatus()

Returns the certStatus of this SingleResponse.

Returns:

the certStatus of this SingleResponse.

isResponseFor

public boolean isResponseFor(X509Certificate targetCert,
                             X509Certificate issuerCert,
                             GeneralName generalName)
                      throws OCSPException

Checks if this is a single response for the given certificate identifying information.

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 precompted responses) as the one sent with the client request.
If the reqCert types are the same in request and response, method isResponseFor can be used for checking if this single response actually is a response referring to the certificate in mind. However, if request and response use different ReqCert types (e.g. request: pkCert, response: certID) or they use a certID with different hash algorithms, this method may be used for trying to "translate" the given cert data into a reqCert of the type the reqCert of this single response represents for checking if they are equal. Translation thereby is performed according to the following rules:

• If this single response uses a reqCert of type certID, both targetCert and issuerCert have to be supplied; generalName is ignored. From the given certs, a certID is created and checked for equality with the certID of the reqCert of this single response.
• If this single response uses a reqCert of type issuerSerial, the targetCert has to be supplied, 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 this single response.
• If this single response uses a reqCert of type pKCert, the targetCert has to be supplied, issuerCert and generalName are ignored. The given target cert is checked for equality with the pKCert of the reqCert of this single response.
• If this single response uses a reqCert of type name, targetCert or generalName have to be supplied, issuerCert is ignored. If generalName is supplied, it is compared with the GeneralName of the reqCert of this response. If generalName is null, but targetCert is supplied, a GeneralName of type directoryName is created from the target certīs SubjectDN and checked for equality with the generalName of the reqCert of this single response.
• If this single response uses a reqCert of type certHash, the targetCert has to be supplied, 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 this single response.

This method only returns true if the supplied informations fit to the type of the ReqCert of this response (according to the conditions above) and identify the same certificate. In any other case this method returns false (e.g. the ReqCert of this response represents a type for which the supplied informations are not appropriate, or the type is ok but another certificate is referenced).

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

Assumimg, for instance, that the ReqCert of this response represents a certID, but you expect a pKCert, method isResponseFor will fail. Now you may supply both target cert and its issuing cert for checking if this is a response for the target certificate in mind, e.g.:

 // the target cert chain
 X509Certificate[] targetCerts = ...;
 booelan isResponseFor = certResponse.isResponseFor(targetCerts[0], targetCerts[1], null);
 

Specified by:

isResponseFor in interface CertificateResponse

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:

true if this is a response for the target certificate asked for; or false if this is not a response for the target certificate in mind or not enough information is provided for handling the type of the inherent ReqCert

Throws:

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

isResponseFor

public boolean isResponseFor(ReqCert reqCert)

Checks if this is a SingleResponse for a certificate identified by the given reqCert identifier. Attention! When using this method for asking if this single response corresponds to the given reqCert be sure that the reqCert of this SingleResponse has the same type as the given reqCert (as usual).

Specified by:

isResponseFor in interface CertificateResponse

Parameters:

reqCert - the ReqCert identifying the certificate in mind

Returns:

true if this is a single response for the certificate identified by the given ReqCert, false if not

getThisUpdate

public Date getThisUpdate()

Returns the thisUpdate date.

Returns:

the thisUpdate date.

getNextUpdate

public Date getNextUpdate()

Returns the nextUpdate date.

Returns:

the nextUpdate date, if included.

addExtension

public void addExtension(V3Extension e)
                  throws X509ExtensionException

Adds the given extension.

The extension to be added shall be an implemented V3Extension. If an extension with the same object ID already exists, it is replaced.

For reading back some extension use the getExtension(ObjectID) method.

Parameters:

e - the extension to be added

Throws:

X509ExtensionException - if the extension cannot be added

removeExtension

public boolean removeExtension(ObjectID oid)

Removes the extension specified by its object identifier.

Parameters:

objectID - the object ID of the extension to remove

Returns:

true if the extension has been successfully removed, false otherwise

removeAllExtensions

public void removeAllExtensions()

Removes all extensions from this single response.

listExtensions

public Enumeration listExtensions()

Returns an enumeration of all extensions included in this single response.

The returned enumeration may contain unknown extensions (instances of UnknownExtension if there are any extensions included in this single response, for which there exists no registered implementation, and it may contain error extensions (instances of ErrorExtension) indicating extensions which cannot be parsed properly because of some kind of error.

Returns:

an enumeration of the extensions, or null if there are no extensions present at all

hasExtensions

public boolean hasExtensions()

Checks, if there are any extensions included in this single response.

Returns:

true if there are extensions, false if not

hasUnsupportedCriticalExtension

public boolean hasUnsupportedCriticalExtension()

Returns true if there are unsupported critical extensions.

Returns:

true, if there are unsupported critical extensions

countExtensions

public int countExtensions()

Returns the number of extensions included in this single response.

Returns:

the number of extensions

getExtension

public V3Extension getExtension(ObjectID oid)
                         throws X509ExtensionInitException

Returns a specific extension, identified by its object identifier.

If the extension cannot be initialized for some reason, an X509ExtensionInitException is thrown. If the requested extension is an unknown extension, which is not supported by a registered implementation, this method creates and returns an UnknownExtension which may be queried for obtaining as much information as possible about the unknown extension.

Parameters:

objectID - the object ID of the extension

Returns:

the desired extension or null if the requested extension is not present

Throws:

X509ExtensionInitException - if the extension can not be initialized

setArchiveCutoff

public void setArchiveCutoff(Date cutoffTime)
                      throws X509ExtensionException

A convenience method for setting the value of the ArchiveCutoff extension.

This method provides an convenient alternative to method addExtension for including the ArchiveCutoff extension in this single response. From the given cuttoff time value a ArchiveCutoff extension object is created an added to the list of single response extensions.

The ArchiveCutoff extension allows a responder to choose to retain revocation information beyond a certificate's expiration. The date obtained by subtracting this retention interval value from the producedAt time in a response is defined as the certificate's "archive cutoff" date. OCSP-enabled applications would use an OCSP archive cutoff date to contribute to a proof that a digital signature was (or was not) reliable on the date it was produced even if the certificate needed to validate the signature has long since expired.

Parameters:

cuttoffTime - the archiv cutoff time

Throws:

X509ExtensionException - if the ArchiveCutoff extension cannot be created

getArchiveCutoff

public Date getArchiveCutoff()
                      throws X509ExtensionInitException

A convenience method for getting the cutoff time of the ArchiveCutoff extension, if included in this response.

This method provides an convenient alternative to method getExtension for getting the cutoff time of the ArchiveCutoff extension, if included in this single response.

The ArchiveCutoff extension allows a responder to choose to retain revocation information beyond a certificate's expiration. The date obtained by subtracting this retention interval value from the producedAt time in a response is defined as the certificate's "archive cutoff" date. OCSP-enabled applications would use an OCSP archive cutoff date to contribute to a proof that a digital signature was (or was not) reliable on the date it was produced even if the certificate needed to validate the signature has long since expired.

Returns:

the cutoff time of the ArchiveCutoff extension, if included in this single response; otherwise null

Throws:

X509ExtensionInitException - if the ArchiveCutoff extension cannot be initialized from its encoding

setCrlID

public void setCrlID(CrlID crlID)
              throws X509ExtensionException

A convenience method for setting the CrlID extension.

This method provides an convenient alternative to method addExtension for including the CrlID extension in this single response.

The CrlID extension may be used by a responder to indicate the CRL on which a revoked or onHold certificate is found. This can be useful where OCSP is used between repositories, and also as an auditing mechanism. The CRL may be specified by a URL (the URL at which the CRL is available), a number (value of the CRL number extension of the relevant crl) or a time (the time at which the relevant CRL was created).

Parameters:

crlID - the crlID extension

Throws:

X509ExtensionException - if the CrlID extension cannot be added

getCrlID

public CrlID getCrlID()
               throws X509ExtensionInitException

A convenience method for getting the CrlID extension, if included in this single response.

This method provides an convenient alternative to method getExtension for getting the CrlID extension, if included in this single response.

The ArchiveCutoff extension allows a responder to choose to retain revocation information beyond a certificate's expiration. The date obtained by subtracting this retention interval value from the producedAt time in a response is defined as the certificate's "archive cutoff" date. OCSP-enabled applications would use an OCSP archive cutoff date to contribute to a proof that a digital signature was (or was not) reliable on the date it was produced even if the certificate needed to validate the signature has long since expired.

Returns:

the CrlID extension, if included in this single response; otherwise null

Throws:

X509ExtensionInitException - if the CrlID extension cannot be initialized from its encoding

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this SingleResponse as an ASN1Object.

Specified by:

toASN1Object in interface ASN1Type

Throws:

CodingException - if an encoding error occurs

decode

public void decode(ASN1Object obj)
            throws CodingException

Creates a SingleResponse from an ASN1Object.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the SingleResponse as ASN1Object

Throws:

CodingException - if the ASN1Object has the wrong format

toString

public String toString()

Returns a String representation of this SingleResponse.

Specified by:

toString in interface CertificateResponse

Overrides:

toString in class Object

Returns:

a String representation

toString

public String toString(boolean detailed)

Returns a String representation of this SingleResponse.

Parameters:

detailed - whether to print detailed information about the extensions

Returns:

a String representation