iaik.x509.ocsp
Class OCSPRequest

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

public class OCSPRequest

extends Object

Implements the OCSP type OCSPRequest.

The X.509 Online Certificate Status Protocol (RFC 2560) specifies the OCSPRequest type for giving the format of a request message that may be send to a OCSP server for getting status information of one or more certificates:

 OCSPRequest     ::=     SEQUENCE {
     tbsRequest                  TBSRequest,
     optionalSignature   [0]     EXPLICIT Signature OPTIONAL }

 TBSRequest      ::=     SEQUENCE {
     version             [0]     EXPLICIT Version DEFAULT v1,
     requestorName       [1]     EXPLICIT GeneralName OPTIONAL,
     requestList                 SEQUENCE OF Request,
     requestExtensions   [2]     EXPLICIT Extensions OPTIONAL }

 Signature       ::=     SEQUENCE {
     signatureAlgorithm      AlgorithmIdentifier,
     signature               BIT STRING,
      certs               [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL}
 

An OCSPRequest may include any number of single Requests, each of them identifying one particular certificate for which revocation information shall be obtained. Single Requests may be set by calling method setRequestList, e.g.:

 Request request1 = ...;
 Request request2 = ...;
 OCSPRequest ocspRequest = new OCSPRequest();
 Request[] requestList = { request1, request2 };
 ocspRequest.setRequestList(requestList);
 

An OCSP request may be signed by the requestor or may be unsigned. If signed, the requestorName shall be present and the certificates of the signer may be included to help the OCSP responder to verify the signature, e.g.:

 // the certificates of the requestor
 X509Certificate[] requestorCerts = ...;
 // the private key of the requestor, used for signing:
 PrivateKey requestorKey = ...;
 // the name of the requestor:
 GeneralName requestorName = 
   new GeneralName(GeneralName.directoryName, requestorCerts[0].getSubjectDN()));
 ocspRequest.setRequestorName(requestorName);
 // set the certificates:
 ocspRequest.setCertificates(requestorCerts);
 // sign the request:
 ocspRequest.sign(AlgorithmID.sha1WithRSAEncryption, requestorKey); 
 

Please note that, when signing an OCSP request, any information that shall be included in the request has to be set before calling the sign method. In this way, also any extension has to be added before calling the sign method. Finally you may call method writeTo or getEncoded for DER encoding the OCSP request:

 OutputStream os = ...;
 ocspRequest.writeTo(os);
 

Version:

File Revision 16

See Also:

Request, OCSPResponse, ReqCert

Constructor Summary

OCSPRequest()
Default constructor for creating a new empty OCSPRequest.

OCSPRequest(byte[] array)
Creates an OCSPRequest from a PEM or DER byte array.

OCSPRequest(InputStream is)
Creates an OCSPRequest from an input stream.

Method Summary

void	addExtension(V3Extension e) Adds the given extension.
boolean	containsCertificates() Checks if certificates are included.
boolean	containsSignature() Checks if this OCSPRequest has been signed.
int	countExtensions() Returns the number of extensions included in this ocsp request.
int	countRequests() Returns the number of requests included.
void	decode(ASN1Object obj) Decodes a OCSPRequest from an ASN1Object.
void	decode(byte[] enc) Decodes a OCSPRequest from a byte array.
void	decode(InputStream is) Decodes an OCSPRequest from an InputStream.
ObjectID[]	getAccepatableResponseTypes() A convenience method for getting the response type list of the AcceptableResponses extension, if included in this request.
X509Certificate[]	getCertifcates() Returns the signer certificates that may be included in this request.
byte[]	getEncoded() Returns this OCSPRequest as DER encoded ASN.1 data structure
V3Extension	getExtension(ObjectID oid) Returns a specific extension, identified by its object identifier.
byte[]	getNonce() A convenience method for getting the value of the Nonce extension, if included in this request.
Request[]	getRequestList() Returns all single requests included in this OCSPRequest.
GeneralName	getRequestorName() Returns the requestorName, if included.
byte[]	getSignature() Returns the signature of this OCSPRequest, if included.
AlgorithmID	getSignatureAlgorithm() Returns the signature algorithm of this OCSPRequest.
byte[]	getTBSRequest() Returns the DER encoded TBSRequest ASN.1 data structure specifying request data to be signed.
int	getVersion() Returns the version number of this OCSPRequest as int.
boolean	hasExtensions() Checks, if there are any extensions included in this ocsp request.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
Enumeration	listExtensions() Returns an enumeration of all extensions included in this ocsp request.
void	removeAllExtensions() Removes all extensions from this ocsp request.
boolean	removeExtension(ObjectID oid) Removes the extension specified by its object identifier.
void	setAcceptableResponseTypes(ObjectID[] acceptableResponseTypes) A convenience method for setting the response Types of the AcceptableResponses extension.
void	setCertificates(X509Certificate[] signerCerts) Sets the certificates to be included into this OCSPRequest.
void	setNonce(byte[] nonce) A convenience method for setting the value of the Nonce extension.
void	setRequestList(Request[] requestList) Sets the request list of this OCSPRequest.
void	setRequestorName(GeneralName requestorName) Sets the requestorName.
void	setSignature(AlgorithmID signatureAlg, byte[] signature) Sets the signature value of this OCSP request.
void	sign(AlgorithmID signatureAlg, PrivateKey privateKey) Signs the OCSPRequest with the private key of the requestor.
void	sign(AlgorithmID signatureAlg, PrivateKey privateKey, String provider) Signs the OCSPRequest with the private key of the requestor.
ASN1Object	toASN1Object() Returns the OCSPRequest as an ASN1Object.
String	toString() Returns a string that represents the contents of this OCSPRequest.
String	toString(boolean detailed) Returns a string that represents the contents of this OCSPRequest.
X509Certificate	verify() Verifies this request using the included signer certificates.
void	verify(PublicKey key) Uses the given public key to verify this OCSPRequest.
void	verify(PublicKey key, String sigProvider) Uses the given public key to verify this OCSPRequest.
void	writeTo(OutputStream os) Writes this OCSPRequest DER encoded to the given output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

OCSPRequest

public OCSPRequest()

Default constructor for creating a new empty OCSPRequest.

Any value may be set using the corrseponding set<Value> method. The version number per default is set to 0 indicating a v1 response.

OCSPRequest

public OCSPRequest(InputStream is)
            throws IOException

Creates an OCSPRequest from an input stream.

The supplied OCSPRequest can be in PEM or DER format. This constructor reads a OCSPRequest previously written with method writeTo(OutputStream).

For instance:

 InputStream is = ...;
 OCSPRequest request = new OCSPRequest(is);
 is.close();
 

Parameters:

is - InputStream from which to create the OCSPRequest

Throws:

IOException - if the request could not be read

OCSPRequest

public OCSPRequest(byte[] array)
            throws CodingException

Creates an OCSPRequest from a PEM or DER byte array.

This constructor may be used for parsing an already exisiting OCSPRequest ASN.1 object, supplied as DER encoded byte array, which may have been created by calling method getEncoded.

Parameters:

array - the byte array containing the DER encoded request

Throws:

CodingException - if the request cannot be decoded

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes a OCSPRequest from an ASN1Object.

The given ASN1Object represents an already existing OCSPRequest which may have been created by calling the toASN1Object method.

Parameters:

obj - the ASN1Object which representing the request

Throws:

CodingException - if there is a problem when parsing the request

decode

public void decode(byte[] enc)
            throws CodingException

Decodes a OCSPRequest from a byte array. The given byte array supplies the OCSP request in DER or PEM encoded format. This method internally is called when creating a OCSPRequest from a byte array.

Parameters:

is - the byte array from where the request should be read

Throws:

CodingException - if an decoding/parsing error occurs

decode

public void decode(InputStream is)
            throws IOException

Decodes an OCSPRequest from an InputStream. The given InputStream supplies the OCSP response in DER or PEM encoded format. This method internally is called when creating a OCSPRequest from an InputStream.

Parameters:

is - the InputStream from where the request should be read

Throws:

IOException - if an the resquest cannot be decoded

sign

public void sign(AlgorithmID signatureAlg,
                 PrivateKey privateKey)
          throws OCSPException,
                 InvalidKeyException,
                 NoSuchAlgorithmException

Signs the OCSPRequest with the private key of the requestor.

Parameters:

signatureAlg - the AlgorithmID of the signature algorithm

privateKey - the private key of the requestor

Throws:

OCSPException - if the request could not be signed

InvalidKeyException - if the format of the key is wrong

NoSuchAlgorithmException - if there is no implementation for the specified algorithm

sign

public void sign(AlgorithmID signatureAlg,
                 PrivateKey privateKey,
                 String provider)
          throws OCSPException,
                 InvalidKeyException,
                 NoSuchAlgorithmException

Signs the OCSPRequest with the private key of the requestor.

Parameters:

signatureAlg - the AlgorithmID of the signature algorithm

privateKey - the private key of the requestor

provider - the name of the provider supplying the Signature engine to be used

Throws:

OCSPException - if the request could not be signed

InvalidKeyException - if the format of the key is wrong

NoSuchAlgorithmException - if there is no implementation for the specified algorithm

setSignature

public void setSignature(AlgorithmID signatureAlg,
                         byte[] signature)
                  throws OCSPException

Sets the signature value of this OCSP request.

This method provides an alternative way to method sign for "signing" this basic OCSP requst with a precalculated signature value. If using this method please make sure that the signature value provided actually has beeb calculated over the TBS request.

Parameters:

signatureAlg - the AlgorithmID of the signature algorithm

signature - the (precalculated) signature value

Throws:

OCSPException - if the request could not be signed

getEncoded

public byte[] getEncoded()
                  throws CodingException

Returns this OCSPRequest as DER encoded ASN.1 data structure

Returns:

a byte array holding the DER encoded OCSPRequest as ASN.1 data structure

Throws:

CodingException - if the reponse cannot be encoded correctly

getVersion

public int getVersion()

Returns the version number of this OCSPRequest as int. Default version: v1.

ASN.1 definition:

 Version  ::=  INTEGER  {  v1(0), v2(1) }
 

Returns:

version number of the response as int, 1 for v1, 2 for v2.

getRequestorName

public GeneralName getRequestorName()

Returns the requestorName, if included.

Returns:

the requestorName, or null if not included

getRequestList

public Request[] getRequestList()

Returns all single requests included in this OCSPRequest.

Returns:

an Enumeration holding all the single requests included in this OCSPRequest; the list may be null

countRequests

public int countRequests()

Returns the number of requests included.

Returns:

the number of requests included

getTBSRequest

public byte[] getTBSRequest()
                     throws CodingException

Returns the DER encoded TBSRequest ASN.1 data structure specifying request data to be signed.

 TBSRequest      ::=     SEQUENCE {
   version             [0] EXPLICIT Version DEFAULT v1,
   requestorName       [1] EXPLICIT GeneralName OPTIONAL,
   requestList             SEQUENCE OF Request,
   requestExtensions   [2] EXPLICIT Extensions OPTIONAL }
 

Returns:

the inherent TBSRequest as DER encoded ASN.1 structure

Throws:

CodingException - if an encoding error occurs

getSignature

public byte[] getSignature()

Returns the signature of this OCSPRequest, if included. The signature is defined as an ASN.1 BIT STRING structure. This method returns the inherent signature value as byte array.

Returns:

the signature value as byte array, or null if request has not be signed

containsSignature

public boolean containsSignature()

Checks if this OCSPRequest has been signed.

Returns:

true if this OCSPRequest has been signed, false if not

getSignatureAlgorithm

public AlgorithmID getSignatureAlgorithm()

Returns the signature algorithm of this OCSPRequest.

Returns:

the AlgorithmID of the algorithm used for signing this response

See Also:

AlgorithmID

verify

public void verify(PublicKey key)
            throws NoSuchAlgorithmException,
                   InvalidKeyException,
                   SignatureException

Uses the given public key to verify this OCSPRequest.

Parameters:

key - the public key (of the issuer) to verify the response

Throws:

NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response

InvalidKeyException - if the format of the public key is wrong

SignatureException - if the signature does not verify

verify

public void verify(PublicKey key,
                   String sigProvider)
            throws NoSuchAlgorithmException,
                   InvalidKeyException,
                   SignatureException

Uses the given public key to verify this OCSPRequest.

Parameters:

key - the public key (of the issuer) to verify the response

sigProvider - the crypto provider supplying the Signature engine to be used

Throws:

NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response

InvalidKeyException - if the format of the public key is wrong

SignatureException - if the signature does not verify

verify

public X509Certificate verify()
                       throws NoSuchAlgorithmException,
                              InvalidKeyException,
                              SignatureException,
                              OCSPException

Verifies this request using the included signer certificates.

This method only can be used for verifying this request if signer certificates are included. If so, this method assumes that all certificates included belong to same chain. It tries to sort the chain to get the signer certificate public key for verifying the request. If no certificates are included or the chain cannot be sorted, an OCSPException is thrown. In this case you may use method verify for verifying the request with the right public key supplied by other means.

Returns:

the certificate of the signer; if included and verification is successful

Throws:

NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response

InvalidKeyException - if the format of the public key is wrong

SignatureException - if the signature does not verify

OCSPException - if no certs are included or the signer cert cannot be found in the certificate list included

containsCertificates

public boolean containsCertificates()

Checks if certificates are included.

Returns:

true if certificates are included, false otherwise

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns the OCSPRequest as an ASN1Object.

Returns:

this response as ASN1Object

writeTo

public void writeTo(OutputStream os)
             throws IOException

Writes this OCSPRequest DER encoded to the given output stream.

Parameters:

os - the output stream where the response shall be written to

Throws:

IOException - if an I/O error occurs

setRequestorName

public void setRequestorName(GeneralName requestorName)

Sets the requestorName.

Parameters:

requestorName - the name of the requestor

setNonce

public void setNonce(byte[] nonce)
              throws X509ExtensionException

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

This method provides an convenient alternative to method addExtension for including the Nonce extension in this OCSPRequest. From the given nonce value a Nonce extension object is created an added to the list of request extensions.

The Nonce extension can be used for cryptographically binding a request and a response to prevent replay attacks.

Parameters:

nonce - the nonce value

Throws:

X509ExtensionException - if the Nonce extension cannot be created

getNonce

public byte[] getNonce()
                throws X509ExtensionInitException

A convenience method for getting the value of the Nonce extension, if included in this request.

This method provides an convenient alternative to method getExtension for getting the value of the Nonce extension, if included in this OCSPRequest.

The Nonce extension can be used for cryptographically binding a request and a response to prevent replay attacks.

Returns:

the value of the Nonce extension, if included in this request; otherwise null

Throws:

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

setAcceptableResponseTypes

public void setAcceptableResponseTypes(ObjectID[] acceptableResponseTypes)
                                throws X509ExtensionException

A convenience method for setting the response Types of the AcceptableResponses extension.

This method provides an convenient alternative to method addExtension for including the AcceptableResponses extension in this OCSPRequest. From the given response type list a AcceptableResponses extension object is created an added to the list of request extensions.

The AcceptableResponses extension can be used by an OCSP client to specify the kinds of response types it understands. The OIDs included in AcceptableResponses are the OIDs of the various response types this client can accept (e.g., id-pkix-ocsp-basic), e.g.:

 ObjectID[] acceptedResponseTypes = { BasicOCSPResponse.responseType };
 ocspRequest.setAcceptableResponseTypes(acceptedResponseTypes);
 

Parameters:

acceptableResponseTypes - the list of acceptable response types

Throws:

X509ExtensionException - if the AcceptableResponses extension cannot be created

getAccepatableResponseTypes

public ObjectID[] getAccepatableResponseTypes()
                                       throws X509ExtensionInitException

A convenience method for getting the response type list of the AcceptableResponses extension, if included in this request.

This method provides an convenient alternative to method getExtension for getting the value of the AcceptableResponses extension, if included in this OCSPRequest.

The AcceptableResponses extension can be used by an OCSP client to specify the kinds of response types it understands. The OIDs included in AcceptableResponses are the OIDs of the various response types this client can accept (e.g., id-pkix-ocsp-basic).

Returns:

the resonse type list of the AcceptableResponses extension, if included in this request; otherwise null

Throws:

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

setRequestList

public void setRequestList(Request[] requestList)

Sets the request list of this OCSPRequest. Any request already included is cleared. If any of the supplied Requests has a reqCert type other than certID, version is set to 2.

Parameters:

requestList - the request list to be set

setCertificates

public void setCertificates(X509Certificate[] signerCerts)

Sets the certificates to be included into this OCSPRequest.

Parameters:

signerCerts - the certificates of the signer to be included

getCertifcates

public X509Certificate[] getCertifcates()

Returns the signer certificates that may be included in this request.

Returns:

the certificates of the signer, if included; null otherwise

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 ocsp request.

listExtensions

public Enumeration listExtensions()

Returns an enumeration of all extensions included in this ocsp request.

The returned enumeration may contain unknown extensions (instances of UnknownExtension if there are any extensions included in request, 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 ocsp request.

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 ocsp request.

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

toString

public String toString()

Returns a string that represents the contents of this OCSPRequest.

Overrides:

toString in class Object

Returns:

the string representation

toString

public String toString(boolean detailed)

Returns a string that represents the contents of this OCSPRequest.

Parameters:

detailed - whether or not to give detailed information about the included single responses and extensions

Returns:

the string representation