OCSPRequest ("Entrust Authority Security Toolkit for the Java Platform")

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

public class OCSPRequest
extends java.lang.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);

See Also:: Request, OCSPResponse, CertID

Constructor Summary

Constructors
Constructor and Description
`OCSPRequest()` Default constructor for creating a new empty OCSPRequest.
`OCSPRequest(byte[] array)` Creates an OCSPRequest from a PEM or DER byte array.
`OCSPRequest(java.io.InputStream is)` Creates an OCSPRequest from an input stream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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(java.io.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.
`java.util.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, java.security.PrivateKey privateKey)` Signs the OCSPRequest with the private key of the requestor.
`void`	`sign(AlgorithmID signatureAlg, java.security.PrivateKey privateKey, java.lang.String provider)` Signs the OCSPRequest with the private key of the requestor.
`ASN1Object`	`toASN1Object()` Returns the OCSPRequest as an ASN1Object.
`java.lang.String`	`toString()` Returns a string that represents the contents of this OCSPRequest.
`java.lang.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(java.security.PublicKey key)` Uses the given public key to verify this OCSPRequest.
`void`	`verify(java.security.PublicKey key, java.lang.String sigProvider)` Uses the given public key to verify this OCSPRequest.
`void`	`writeTo(java.io.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(java.io.InputStream is)
            throws java.io.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:
    
    java.io.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:
    
    enc - the byte array from where the request should be read
    
    Throws:
    
    CodingException - if an decoding/parsing error occurs
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.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:
    
    java.io.IOException - if an the resquest cannot be decoded
  - sign
```
public void sign(AlgorithmID signatureAlg,
                 java.security.PrivateKey privateKey)
          throws OCSPException,
                 java.security.InvalidKeyException,
                 java.security.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
    
    java.security.InvalidKeyException - if the format of the key is wrong
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - sign
```
public void sign(AlgorithmID signatureAlg,
                 java.security.PrivateKey privateKey,
                 java.lang.String provider)
          throws OCSPException,
                 java.security.InvalidKeyException,
                 java.security.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
    
    java.security.InvalidKeyException - if the format of the key is wrong
    
    java.security.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(java.security.PublicKey key)
            throws java.security.NoSuchAlgorithmException,
                   java.security.InvalidKeyException,
                   java.security.SignatureException
```
    Uses the given public key to verify this OCSPRequest.
    
    Parameters:
    
    key - the public key (of the issuer) to verify the response
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response
    
    java.security.InvalidKeyException - if the format of the public key is wrong
    
    java.security.SignatureException - if the signature does not verify
  - verify
```
public void verify(java.security.PublicKey key,
                   java.lang.String sigProvider)
            throws java.security.NoSuchAlgorithmException,
                   java.security.InvalidKeyException,
                   java.security.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:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response
    
    java.security.InvalidKeyException - if the format of the public key is wrong
    
    java.security.SignatureException - if the signature does not verify
  - verify
```
public X509Certificate verify()
                       throws java.security.NoSuchAlgorithmException,
                              java.security.InvalidKeyException,
                              java.security.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:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the algorithm that has been used to sign this response
    
    java.security.InvalidKeyException - if the format of the public key is wrong
    
    java.security.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
    
    Throws:
    
    CodingException
  - writeTo
```
public void writeTo(java.io.OutputStream os)
             throws java.io.IOException
```
    Writes this OCSPRequest DER encoded to the given output stream.
    
    Parameters:
    
    os - the output stream where the response shall be written to
    
    Throws:
    
    java.io.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.
    
    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:
    
    oid - 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 java.util.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:
    
    oid - 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 java.lang.String toString()
```
    Returns a string that represents the contents of this OCSPRequest.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation
  - toString
```
public java.lang.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

Class OCSPRequest

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OCSPRequest

OCSPRequest

OCSPRequest

Method Detail

decode

decode

decode

sign

sign

setSignature

getEncoded

getVersion

getRequestorName

getRequestList

countRequests

getTBSRequest

getSignature

containsSignature

getSignatureAlgorithm

verify

verify

verify

containsCertificates

toASN1Object

writeTo

setRequestorName

setNonce

getNonce

setAcceptableResponseTypes

getAccepatableResponseTypes

setRequestList

setCertificates

getCertifcates

addExtension

removeExtension

removeAllExtensions

listExtensions

hasExtensions

hasUnsupportedCriticalExtension

countExtensions

getExtension

toString

toString