iaik.x509.ocsp.utils
Class ResponseGenerator

java.lang.Object
  |
  +--iaik.x509.ocsp.utils.ResponseGenerator

public class ResponseGenerator

extends Object

A simple utility for generating OCSP responses (of type BasicOCSPResponse).

This class provides an utility for caching pre-calculated single responses (either immediately set or computed from a crl) and creating a OCSPResponse according to the single reponses cached.

When creating a ResponseGenerator object the certificates and private signing key of the responder have to be supplied (either as PrivateKey and X509Certificate chain) or as PKCS12 object:

 // the responder certs:
 X509Certificate[] responderCerts = ...;
 // the private key of the responder:
 PrivateKey responderKey = ...;
 ResponseGenerator generator = 
   new ResponseGenerator(responderKey, responderCerts);
 

respectively:

 // the PKCS12Object containing key and ceritifcates of the responder:
 PKCS12 pkcs12 = ...;
 // the password for decrypting the PKCS12 object:
 char[] password = ...;
 ResponseGenerator generator = 
   new ResponseGenerator(pkcs12, password);
 

After optionally initializing the generator with the contents previously written to a file, adding single response entries (by using one of the addResponseEntry methods or creating them from a CRL) and/or adding trusted certificate issuers method createOCSPResponse may be called for creating an OCSPResponse in response to an OCSPRequest received, e.g.:

 // add a single response
 generator.addResponseEntry(singleResponse);
 // create and add a second response
 generator.addResponseEntry(reqCert, certStatus, thisUpdate, nextUpdate);
 // create and add response entries from a crl
 X509CRL crl = ...;
 // the crl issuer cert
 X509Certificate crlIssuer = ...;
 generator.addResponseEntries(crl, crlIssuer, ReqCert.certID);
 // add a trusted certificate issuer
 Name issuer = ...;
 generator.addCertificateIssuer(issuer);
 // sign and create an OCSPResponse for an OCSPRequest read from a stream
 InputStream is = ...;
 AlgorithmID signingAlg = ...;
 OCSPResponse ocspResponse = createOCSPResponse(is, null, sigingAlg, null);
 

The OCSPResponse will be created according to the following proceeding: First the OCSP request is read and decoded from the given input stream. For each of the included single requests a SingleResponse is created thereby setting the CertStatus according to the following rules (in this order):

• If the request contains a ServiceLocator extension indicating that the owner of this generator is not an accepted responder for the request in mind, the CertStatus of the corresponding single response is set to "unknown".
• If any of the single responses in the cache matches to the ReqCert of the request in mind, this single response is the one to be sent in response to the request.
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find the issuer of its target certificate, and the owner of this generator itself is equal to the target certificate issuer, the CertStatus of the corresponding single response is set to "good".
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find the issuer of its target certificate, and the owner of this generator has a certificate (with ExtendedKeyUsage ocspSigning set) issued by the target certificate issuer, the CertStatus of the corresponding single response is set to "good".
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find that any of the certificate issuers cached is the issuer of the target certificate and also the issuer of the responder certificate, the certStaus of the corresponding single response is set to "good" if the responder certificate is allowed to sign OCSP responses (has to ocspSigning ExtendedKeyUsage set.
• In any other case the CertStatus of the corresponding request is set to "unknown"

The OCSPResponse created will indicate another response status than "successful" if any of the following situations occur:

• The OCSP request supplied by the given input stream cannot be read because of an decoding/parsing error ==> response status "malformedRequest"
• The OCSP request is signed but the signature is invalid ==> response status "malformedRequest"
• The OCSP request is signed but the ceritificates included to not belong to the request signer ==> response status "malformedRequest"
• The OCSP request is signed but no ceritificates are included and no signer key is available; so the signature cannot be verified ==> response status "malformedRequest"
• The OCSP request is signed but the verification key is invalid ==> response status "malformedRequest"
• The OCSP request is signed but the signature cannot be verified because the signature algorithm used is not supported ==> response status "internalError"
• If some other, general, not request specific error occurs during request parsing or verification ==> response status "tryLater"
• If an error occurs when signing the OCSPResponse ==> response status "tryLater"
• If some general error occurs ==> response status "tryLater"

Version:

File Revision 17

See Also:

OCSPResponse, OCSPRequest, BasicOCSPResponse, SingleResponse, Request, ReqCert

Constructor Summary

ResponseGenerator(PKCS12 pkcs12, char[] password)
Creates a ResponseGenerator from the given PCSK#12 object.

ResponseGenerator(PrivateKey responderKey, X509Certificate[] responderCerts)
Creates a ResponseGenerator from responder private key and responder certs.

Method Summary

void	addCertificateIssuer(Name issuer) Adds a certificate issuers to this response generator.
void	addResponseEntries(X509CRL crl, X509Certificate crlIssuer, int reqCertType) Creates and adds SingleResponse entries for the given CRL.
void	addResponseEntries(X509CRL crl, X509Certificate crlIssuer, int reqCertType, CrlID crlID) Creates and adds SingleResponse entries for the given CRL.
void	addResponseEntry(ReqCert reqCert, CertStatus certStatus, Date thisUpdate, Date nextUpdate) Creates a SingleResponse for the given reqCert, certStatus and thisUpdate (and optional nextUpdate) date and adds it to the list of single responses.
void	addResponseEntry(SingleResponse singleResponse) Adds the given SingleResponse.
OCSPResponse	createOCSPResponse(InputStream requestStream, PublicKey requestorKey, AlgorithmID signatureAlgorithm, V3Extension[] extensions) Creates an OCSPResponse for the OCSPRequest read from the given input stream.
X509Certificate[]	getResponderCertificates() Gets the certificates of the responder.
PrivateKey	getResponderKey() Gets the signing key of the responder.
SingleResponse	getSingleResponse(ReqCert reqCert) Returns the single response identified by the given ReqCert, if included.
SingleResponse	getSingleResponse(Request request) Creates a single response for the given single request.
Enumeration	getSingleResponses() Returns all single responses produced by this response generator.
void	init(InputStream is) Inits the single response repository from the from the given input stream.
void	printDebug(boolean debug) Turns debug printing to System.out on/off.
void	removeAllCertIssuers() Removes all certificate issuers included.
void	removeAllSingleResponses() Removes all single responses included.
boolean	removeCertificateIssuer(Name issuer) Removes the given certificate issuer.
SingleResponse	removeSingleResponse(ReqCert reqCert) Removes the single response identified by the given ReqCert.
void	setDebugStream(OutputStream out) Sets the stream to which debug information shall be printed.
String	toString() Returns a string representation of this resposne generator.
void	writeTo(OutputStream os) Writes the contents of this response generator to the given output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

ResponseGenerator

public ResponseGenerator(PrivateKey responderKey,
                         X509Certificate[] responderCerts)

Creates a ResponseGenerator from responder private key and responder certs.

The certificate of the response signer (i.e. the certificate corresponding to the responder key) has to be at index 0 of the supplied array. No certificate chain verification or rearranging is performed. It is the responsibility of the calling application to supply valid certificates.

Parameters:

responderKey - the key used for signing the response

responderCerts - the certificates of the responder

ResponseGenerator

public ResponseGenerator(PKCS12 pkcs12,
                         char[] password)
                  throws PKCSException

Creates a ResponseGenerator from the given PCSK#12 object.

Parameters:

pkcs12 - the PKCS12 object supplying responder key and certs.

password - the password for decrypting the PKCS12 object.

Method Detail

getResponderKey

public PrivateKey getResponderKey()

Gets the signing key of the responder.

Returns:

the signing key of the responder.

getResponderCertificates

public X509Certificate[] getResponderCertificates()

Gets the certificates of the responder.

Returns:

the certificates of the responder.

addResponseEntry

public void addResponseEntry(ReqCert reqCert,
                             CertStatus certStatus,
                             Date thisUpdate,
                             Date nextUpdate)

Creates a SingleResponse for the given reqCert, certStatus and thisUpdate (and optional nextUpdate) date and adds it to the list of single responses.

Any included SingleResponse with the same ReqCert is cleared.
Attention! This method does not check if the owner of this generator is authorized to send the single response created from the given information (such a check only might be possible if only ReqCert types (CertID, issuerSerial, pKCert) were used allowing to find the issuer of the corresponding target certificate. It is the responsibiltity of the calling application to ensure that the given single responses matches to the OCSP signing abilities of the owner of this generator (i.e. the responder).

Parameters:

reqCert - the reqCert identifying the target cert for which revocation information maybe requested

certStatus - the certStatus for the target certificate in mind

thisUpdate - the time at which the certStatus is known as being correct

nextUpdate - the time at or before newer information will be available about the status of the certificate (maybe null)

addResponseEntry

public void addResponseEntry(SingleResponse singleResponse)

Adds the given SingleResponse.

Any included SingleResponse with the same ReqCert is cleared.
Attention! This method does not check if the owner of this generator is authorized to send the given single response (such a check only might be possible if only ReqCert types (CertID, issuerSerial, pKCert) were used allowing to find the issuer of the corresponding target certificate. It is the responsibiltity of the calling application to ensure that the given single responses matches to the OCSP signing abilities of the owner of this generator (i.e. the responder).

Parameters:

singleResponse - the SingleResponse to be added

addResponseEntries

public void addResponseEntries(X509CRL crl,
                               X509Certificate crlIssuer,
                               int reqCertType)
                        throws OCSPException,
                               SignatureException

Creates and adds SingleResponse entries for the given CRL.

This method tries to create single response entries for the revoked certificate of the given crl. This method throws an OCSPException if one of the following situations occur:

• Single responses only can be created for ReqCert types certID or IssuerSerial; if the given crl is an indirect crl, certID cannot be used, too. If any other ReqCert type is claimed, an OCSPException is thrown.
• If the given crl is not an indirect CRL, but the response signer is different from the crl issuer and is not authorized by the crl issuer to sign the response (ExtendedKeyUsage bit ocpSigning is not set). If ocspSigning is set but the response signing cert is not issued by the crl issuer also an OCSPException is thrown.
• If the given crl is an indirect one but the response signer is not authorized by any certificate issuer included (ExtendedKeyUsage bit ocpSigning is not set). If ocspSigning is set but the response signing cert is not issued by the ceritificate issuer in mind also an OCSPException is thrown. However, if the response signer is equal to a certificate issuer an entry for the corresponding revoked certificate may be created
• If some processing error occurs when creating the single response for an revoked certificate included.

Parameters:

crl - the crl from which to create single responses

crlIssuer - the certificate of the CRL issuer (required for OCSPv1 CertID creation)

reqCertType - the ReqCert type the single responses should have (either certID or issuerSerial

Throws:

OCSPException - if single response entries cannot be created because one of the reasons stated above

SignatureException - if the crl cannot be verified with the given crl issuer cert

addResponseEntries

public void addResponseEntries(X509CRL crl,
                               X509Certificate crlIssuer,
                               int reqCertType,
                               CrlID crlID)
                        throws OCSPException,
                               SignatureException

Creates and adds SingleResponse entries for the given CRL.

This method tries to create single response entries for the revoked certificate of the given crl. This method throws an OCSPException if one of the following situations occur:

• Single responses only can be created for ReqCert types certID or IssuerSerial; if the given crl is an indirect crl, certID cannot be used, too. If any other ReqCert type is claimed, an OCSPException is thrown.
• If the given crl is not an indirect CRL, but the response signer is different from the crl issuer and is not authorized by the crl issuer to sign the response (ExtendedKeyUsage bit ocpSigning is not set). If ocspSigning is set but the response signing cert is not issued by the crl issuer also an OCSPException is thrown.
• If the given crl is an indirect but the response signer is not authorized by any certificate issuer included (ExtendedKeyUsage bit ocpSigning is not set). If ocspSigning is set but the response signing cert is not issued by the ceritificate issuer in mind also an OCSPException is thrown. However, if the response signer is equal to a certificate issuer an entry for the corresponding revoked certificate may be created
• If some processing error occurs when creating the single response for an revoked certificate included.

Parameters:

crl - the crl from which to create single responses

crlIssuer - the certificate of the CRL issuer (required for OCSPv1 CertID creation)

reqCertType - the ReqCert type the single responses should have (either certID or issuerSerial

crlID - the crlID extension, if to be included, otherwise null

Throws:

OCSPException - if single response entries cannot be created because one of the reasons stated above

SignatureException - if the crl cannot be verified with the given crl issuer cert

getSingleResponses

public Enumeration getSingleResponses()

Returns all single responses produced by this response generator.

Returns:

all single responses produced in this response generator.

getSingleResponse

public SingleResponse getSingleResponse(ReqCert reqCert)

Returns the single response identified by the given ReqCert, if included.

Returns:

the single response identified by the given ReqCert, or null if no single response for the given ReqCert is included

removeSingleResponse

public SingleResponse removeSingleResponse(ReqCert reqCert)

Removes the single response identified by the given ReqCert.

Parameters:

ReqCert - the reqCert ID for the single response to be removed

Returns:

the SingleResponse, if removed, null if the SingleResponse cannot be removed because it was not included

removeAllSingleResponses

public void removeAllSingleResponses()

Removes all single responses included.

addCertificateIssuer

public void addCertificateIssuer(Name issuer)

Adds a certificate issuers to this response generator.

When asking for a single response for a particular request, but no SingleResponse has been set for this request, a new SingleResponse has to be created for this request using the following proceeding for determining the certStatus of the single response:
If the ReqCert of the request in mind has a type (certID, issuerSerial or pKCert} allowing to find the issuer of its target certificate, and if this issuer is the response signer itself or is some of the issuers previously set by method addCertificateIssuer and has signed the responderīs OCSP signing certificate, the certStatus is set to "good". In any other case the cert status is set to "unknown".

Parameters:

issuer - the issuer name to be set

removeCertificateIssuer

public boolean removeCertificateIssuer(Name issuer)

Removes the given certificate issuer.

Certificate issuer names can be added by calling method addCertificateIssuer to be used for determining the certStatus of a SingleResponse for a request for which no SingleResponse has been explicitly set: If the ReqCert of the request in mind has a type (certID, issuerSerial or pKCert} allowing to find the issuer of its target certificate, and if this issuer is the response signer itself or is some of the issuers previously set by method addCertificateIssuer and has signed the responderīs OCSP signing certificate, the certStatus is set to "good". In any other case the cert status is set to "unknown".

Parameters:

issuer - the issuer name to be removed

Returns:

true, if removed, false if the issuer name cannot be removed because it was not included

removeAllCertIssuers

public void removeAllCertIssuers()

Removes all certificate issuers included.

Certificate issuer names can be added by calling method addCertificateIssuer to be used for determining the certStatus of a SingleResponse for a request for which no SingleResponse has been explicitly set: If the ReqCert of the request in mind has a type (certID, issuerSerial or pKCert} allowing to find the issuer of its target certificate, and if this issuer is the response signer itself or is some of the issuers previously set by method addCertificateIssuer and has signed the responderīs OCSP signing certificate, the certStatus is set to "good". In any other case the cert status is set to "unknown".

getSingleResponse

public SingleResponse getSingleResponse(Request request)

Creates a single response for the given single request.

For the given single request a SingleResponse is created thereby setting the CertStatus according to the following rules (in this order):

• If the request contains a iaik.x509.ocsp.extensions extension indicating that the owner of this generator is not an accepted responder for the request in mind, the CertStatus of the corresponding single response is set to "unknown".
• If any of the single responses in the cache matches to the ReqCert of the request in mind, this single response is the one sent in response to the request.
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find the issuer of its target certificate, and the owner of this generator itself is equal to the target certificate issuer, the CertStatus of the corresponding single response is set to "good".
• If the given ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find the issuer of its target certificate, and the owner of this generator has a certificate (with ExtendedKeyUsage ocspSigning set) issued by the target certificate issuer, the CertStatus of the corresponding single response is set to "good".
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find that any of the certificate issuers cached is the issuer of the target certificate and also the issuer of the responder certificate, the certStaus of the corresponding single response is set to "good" if the responder certificate is allowed to sign OCSP responses (has to ocspSigning ExtendedKeyUsage set.
• In any other case the CertStatus of the corresponding request is set to "unknown"

Parameters:

request - the request for which to create a single response

Returns:

a SingleResponse for the given request

createOCSPResponse

public OCSPResponse createOCSPResponse(InputStream requestStream,
                                       PublicKey requestorKey,
                                       AlgorithmID signatureAlgorithm,
                                       V3Extension[] extensions)

Creates an OCSPResponse for the OCSPRequest read from the given input stream.

This method first reads and decodes the request from the given input stream. For each of the included single requests a SingleResponse is created thereby setting the CertStatus according to the following rules (in this order):

• If the request contains a ServiceLocator extension indicating that the owner of this generator is not an accepted responder for the request in mind, the CertStatus of the corresponding single response is set to "unknown".
• If any of the single responses in the cache matches to the ReqCert of the request in mind, this single response is the one sent in response to the request.
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find the issuer of its target certificate, and the owner of this generator itself is equal to the target certificate issuer, the CertStatus of the corresponding single response is set to "good".
• If the ReqCert of the request is of a type (CertID, issuerSerial, or pKCert) allowing to find that any of the certificate issuers cached is the issuer of the target certificate and also the issuer of the responder certificate, the certStaus of the corresponding single response is set to "good" if the responder certificate is allowed to sign OCSP responses (has to ocspSigning ExtendedKeyUsage set.
• In any other case the CertStatus of the corresponding request is set to "unknown"

The OCSPResponse returned by this method will indicate another response status than "successful" if any of the following situations occur:

• The OCSP request supplied by the given input stream cannot be read because of an decoding/parsing error ==> response status "malformedRequest"
• The OCSP request is signed but the signature is invalid ==> response status "malformedRequest"
• The OCSP request is signed but the ceritificates included to not belong to the request signer ==> response status "malformedRequest"
• The OCSP request is signed but no ceritificates are included and no signer key is available; so the signature cannot be verified ==> response status "malformedRequest"
• The OCSP request is signed but the verification key is invalid ==> response status "malformedRequest"
• The OCSP request is signed but the signature cannot be verified because the signature algorithm used is not supported ==> response status "internalError"
• If some other, general, not request specific error occurs during request parsing or verification ==> response status "tryLater"
• If an error occurs when signing the OCSPResponse ==> response status "tryLater"
• If some general error occurs ==> response status "tryLater"

If any of the given extensions cannot be added to the response because of some reason, the response is sent without including the particular extension (i.e. it is ignored)

Parameters:

requestStream - the input stream from where to read the DER encoded OCSP request

requestorKey - the public key of the requestor used to verify the request (may be null if the request is not signed or is signed and has the requestor certificates included

signatureAlgorithm - the signature algorithm which will be used for signing the OCSPResponse

extensions - any response extensions to be added to the OCSPResponse created by this method

init

public void init(InputStream is)
          throws IOException

Inits the single response repository from the from the given input stream.

Attention! The data read in by this method does not represent the OCSPResponse to be sent in response to a request. The final OCSPResponse is created when calling method createOCSPResponse. This method only provides the possibiltiy to init the generator from a file previously created by calling method writeTo.
This method reads in the (previously written) contents of the generator thereby using a proprietary ASN.1 structure:

 GeneratorContents  ::= SEQUENCE {
   tbs         Contents,
   signature   BIT STRING }

 Contents ::= SEQUENCE {
   responderID      ResponderID,
   certIssuers      SEQUENCE OF Name OPTIONAL
    responses   [0] SEQUENCE OF SingleResponse }
 

For providing the integrity and authenticy of the generator the contents has been signed with the responderīs private key and now is verified with its public key.

Parameters:

is - the input stream supplying the contents of this generator

Throws:

IOException - if an initialization, verification error,... occurs or the contents read in has does not belong to the owner of this generator

writeTo

public void writeTo(OutputStream os)
             throws IOException

Writes the contents of this response generator to the given output stream.

Attention! The output created and stored by this method is not the the OCSPResponse to be sent in response to a request. The final OCSPResponse is created when calling method createOCSPResponse. This method only provides the possibiltiy to store the repository to a file from where it can be read back when calling method init.
This method uses a proprietary ASN.1 structure for writing the contents to the given stream:

 GeneratorContents  ::= SEQUENCE {
   tbs         Contents,
   signature   BIT STRING }

 Contents ::= SEQUENCE {
   responderID      ResponderID,
   certIssuers      SEQUENCE OF Name OPTIONAL
    responses   [0] SEQUENCE OF SingleResponse }
 

For providing the integrity and authenticy of the generator the contents is signed with the responderīs private key before writing it to the stream.

Parameters:

os - the output stream to which to write the contents of this generator

Throws:

IOException - if some I/O, signing, ... error occurs

printDebug

public void printDebug(boolean debug)

Turns debug printing to System.out on/off.

Parameters:

debug - whether to write debug messages to System.out or not

setDebugStream

public void setDebugStream(OutputStream out)

Sets the stream to which debug information shall be printed.

Parameters:

out - the stream to which debug information shall be written; maybe null for disabling debug output

toString

public String toString()

Returns a string representation of this resposne generator.

Overrides:

toString in class Object

Returns:

the String representation