com.rsa.certj.cert

Class X509CRL

java.lang.Object
  |
  +--com.rsa.certj.cert.CRL
        |
        +--com.rsa.certj.cert.X509CRL

All Implemented Interfaces:

Cloneable, Serializable

public class X509CRL

extends CRL

implements Cloneable, Serializable

This class builds and holds X.509 certificate revocation lists (CRLs). Certificates can be revoked before their expiration time. Revoke a certificate if the user's private key is assumed to be compromised, the user is no longer to be certified by the CA, or the CA's certificate is assumed to be compromised. Two related points are as follows:

1. The revocation of a user certificate or CA certificate is announced by the CA, and a new certificate is made available, if appropriate. The CA may then inform the owner of the certificate about its revocation by some off-line procedure.

2. The CA maintains the following:
   • a time-stamped list of the previously issued certificates that have been revoked.
   • a time-stamped list of revoked certificates of all CAs known to the CA and certified by the CA.
   Both certified lists exist, even if empty.

An X.509 CRL consists of three elements:

1. the inner DER, which contains all the CRL information
2. the signature algorithm, in the form of an AlgorithmIdentifier
3. the signature.

An X.509 CRL requires the inner CRL to be DER-encoded. The encoding is called the innerDER.

The ASN.1 definition is as follows:

 CRL ::= SEQUENCE {
   innerDER              InnerDER,
   signatureAlgorithm    AlgorithmIdentifier,
   signature             BIT STRING }

 InnerDER  ::=	SEQUENCE {
    version	       Version OPTIONAL, -- if present, version must be v2
    signature		   AlgorithmIdentifier,  -- the algorithm identifier
                                              for the algorithm used 
                                              to sign the CRL.
    issuer   		   Name, -- identifies the entity who has signed and
                              issued the CRL. Alternative name forms may also
                              appear in the issuerAltName extension
    thisUpdate	   Time, -- the issue date of this CRL.
    nextUpdate	   Time OPTIONAL, -- the date by which the next CRL 
                                       will be issued. The next CRL could be issued 
                                       before the indicated date, but it 
                                       will not be issued any later than the
                                       indicated date. 
    revokedCertificates  SEQUENCE OF SEQUENCE {      -- Revoked certificates
                                                        are listed.
      userCertificate	       CertificateSerialNumber,
      revocationDate	       Time,
      crlEntryExtensions     Extensions OPTIONAL } OPTIONAL,
    crlExtensions   [0]  Extensions OPTIONAL }} -- provide methods for 
                                 associating additional attributes with CRLs.

See the X500Name class for more information about an X.500 name.

Copyright © RSA Security Inc., 1999-2001. All rights reserved.

See Also

Serialized Form

Field Summary

static int	X509_VERSION_1 Sets the CRL to be version 1, or determines if an existing CRL is version 1.
static int	X509_VERSION_2 Sets the CRL to be version 2, or determines if an existing CRL is version 2.

Fields inherited from class com.rsa.certj.cert.CRL

DSA_WITH_SHA1_X930, DSA_WITH_SHA1_X957, RSA_WITH_SHA1_ISO_OIW, RSA_WITH_SHA1_PKCS

Constructor Summary

X509CRL()

Constructs an empty X.509CRL object.

X509CRL(byte[] x509CrlBER, int offset, int special)

Constructs a signed X509CRL object and initializes it with the value given by x509CrlBER, beginning at offset, the BER encoding of an X.509-signed CRL.

X509CRL(byte[] x509CrlBER, int offset, int special, CertJ certJContext)

X509CRL(CertJ certJContext)

Constructs an empty X.509CRL object with CertJ context specified.

Method Summary

Object	clone() Overrides the default clone method to get a deeper clone.
boolean	compareIssuerName(X500Name issuerName) Compares the given name, issuerName, with the issuer name of the CRL represented by this object.
boolean	equals(Object obj) Returns true if this object and obj contain the same X509CRL; otherwise false.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the CRL in this object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes of the DER encoding of this CRL.
X509V3Extensions	getExtensions() Gets the extensions in this CRL.
int	getInnerDER(byte[] encoding, int offset) Places the DER encoding of the inner DER of the CRL in this object into encoding, beginning at offset.
int	getInnerDERLen() Returns the number of bytes of the innerDER.
X500Name	getIssuerName() Gets the issuer name of this CRL.
static int	getNextBEROffset(byte[] x509CrlBER, int offset) Given x509CrlBER, the BER encoding of an X.509 CRL, beginning at offset, finds the index to the next element in the encoding.
Date	getNextUpdate() Gets the date by which the next update will be issued.
RevokedCertificates	getRevokedCertificates() Gets the revoked certificates of this CRL.
byte[]	getSignature() Gets the signature octets.
Date	getThisUpdate() Gets the issue date of this CRL.
int	getVersion() Gets the version of this CRL.
void	setExtensions(X509V3Extensions extensions) Sets the extensions of this CRL to be extensions.
void	setInnerDER(byte[] x509InnerDER, int offset) Sets this object to be the unsigned CRL represented by x509InnerDER, beginning at offset, the DER encoding of the inner CRL of an X.509 CRL.
void	setIssuerName(X500Name issuerName) Sets the issuer name of this CRL to be issuerName.
void	setNextUpdate(Date update) Sets the time when the next CRL is updated.
void	setRevokedCertificates(RevokedCertificates revokedCerts) Sets the value of the revokedCerts field of this CRL to revokedCerts.
void	setThisUpdate(Date update) Sets the time of the issue date of this CRL to be update.
void	setTimeType(boolean flag) Sets the flag specifying the time encoding type to use.
void	setVersion(int version) Sets the version of this CRL to version.
void	signCRL(String transformation, String device, com.rsa.jsafe.JSAFE_PrivateKey signingKey, SecureRandom random) Signs the CRL using transformation and signingKey on the specified device.
boolean	verifyCRLSignature(String device, com.rsa.jsafe.JSAFE_PublicKey verifyingKey, SecureRandom random) Verifies the CRL's signature, using verifyingKey, on the specified device.

Methods inherited from class com.rsa.certj.cert.CRL

getCertJ, getDevice, getDeviceList, getSignatureAlgorithm, getSignatureAlgorithmDER, getSignatureFormat, getSignatureStandard, setCertJ, setSignatureStandard, signCRL, verifyCRLSignature, verifyCRLSignature

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

X509_VERSION_1

public static final int X509_VERSION_1

Sets the CRL to be version 1, or determines if an existing CRL is version 1.

X509_VERSION_2

public static final int X509_VERSION_2

Sets the CRL to be version 2, or determines if an existing CRL is version 2.

Constructor Detail

X509CRL

public X509CRL()

Constructs an empty X.509CRL object.

X509CRL

public X509CRL(CertJ certJContext)

Constructs an empty X.509CRL object with CertJ context specified.

Parameters

certJContext

CertJ is a CertJ context.

X509CRL

public X509CRL(byte[] x509CrlBER,
               int offset,
               int special)
        throws CertificateException

Constructs a signed X509CRL object and initializes it with the value given by x509CrlBER, beginning at offset, the BER encoding of an X.509-signed CRL. This constructor only reads the CRL, it does not perform any verification.

The ASN.1 definition means the tag will be 0x30. However, an X.509 CRL object can be part of a PKCS #7 message (or some other construct), and it might have a different tag caused by IMPLICIT or EXPLICIT. For example, if the definition is as follows:

      crl   [2] IMPLICIT CRL 

In this case, the tag will be changed from 0x30 to 0xa2. To indicate that the DER encoding of the X.509 certificate object should follow any special circumstances, use the special argument. Set special to any special circumstances of the BER encoding; for example, to indicate the following:

      crl   [2] IMPLICIT CRL  

Pass in the following:

      special = (ASN1.CONTEXT_IMPLICIT | 2);

If there are no special circumstances, pass in the following:

      special = 0

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	x509CrlBER		The BER encoding of an X.509-signed CRL.
	offset		The offset into x509CrlBER where the encoding begins.
	special		The special circumstances of the BER encoding, if there are any.

Throws

CertificateException - If the BER is not a valid X.509 CRL.

X509CRL

public X509CRL(byte[] x509CrlBER,
               int offset,
               int special,
               CertJ certJContext)
        throws CertificateException

Method Detail

getNextBEROffset

public static int getNextBEROffset(byte[] x509CrlBER,
                                   int offset)
                            throws CertificateException

Given x509CrlBER, the BER encoding of an X.509 CRL, beginning at offset, finds the index to the next element in the encoding. In other words, gets the next offset after the CRL.

For example, if the offset is 120 and the CRL's BER encoding is 1819 bytes, this method returns 1939, the index immediately following the CRL. That is, x509CrlBER[120] is the first byte in the encoding of the CRL, x509CrlBER[1938] is the last byte in the encoding of the CRL, and the next element begins at index 1939.

Parameters

	x509CrlBER		The BER encoding of an X.509 CRL.
	offset		The offset into x509CrlBER where the encoding begins.

Returns

An int that contains the index to the next element in the BER encoding.

Throws

CertificateException - If the method cannot read the BER encoding.

getDERLen

public int getDERLen(int special)

Returns the number of bytes of the DER encoding of this CRL. If this object is not set with values, this method returns zero.

The ASN.1 definition of the CRL, previously defined in his class, means the tag will be 0x30. However, a CRL object can be part of a PKCS #7 message (or some other construct), and it can have a different tag caused by IMPLICIT or EXPLICIT. This can affect the length. For example, suppose a definition is as follows:

   crl   [2] IMPLICIT CRL  

In this case, the tag will be changed from 0x30 to 0xa2.

To indicate that the DER encoding of the X509CRL should follow any special circumstances, use the special argument. Set special to any special circumstances of the DER encoding; for example, to indicate the following:

      crl   [2] IMPLICIT CRL 

Pass in the following:

      special = (ASN1.CONTEXT_IMPLICIT | 2); 

If there are no special circumstances, pass in the following:

 
      special = 0 

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

special

The special circumstances of the DER encoding, if there are any.

Returns

The number of bytes of the DER encoding of this X.509 CRL.

getDEREncoding

public int getDEREncoding(byte[] encoding,
                          int offset,
                          int special)
                   throws CertificateException

Places the DER encoding of the CRL in this object into encoding, beginning at offset. To determine the length of the encoding, call getDERLen. If this object is not yet set with a CRL (or not yet signed), this method throws an exception.

The ASN.1 definition, previously defined in this class, means the tag will be 0x30. However, a CRL can be part of a PKCS #7 message (or some other construct), and it might have a different tag caused by IMPLICIT or EXPLICIT. For instance, suppose the definition is as follows:

      crl   [2] EXPLICIT CRL  

To indicate that the DER encoding of the X509CRL object should follow any special circumstances, use ther special argument. Set special to any special circumstances of the DER encoding.

For example, to indicate the following:

      crl   [2] EXPLICIT CRL  

Pass in the following:

 
      special = (ASN1.CONTEXT_EXPLICIT | 2);   

If there are no special circumstances, pass in

      special = 0   

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	encoding		The byte array into which the result will be placed.
	offset		The offset into encoding where writing begins.
	special		The special circumstances of the DER encoding, if there are any.

Returns

The number of bytes actually placed into encoding.

Throws

CertificateException - If the CRL is not signed or if all required fields are not set.

setInnerDER

public void setInnerDER(byte[] x509InnerDER,
                        int offset)
                 throws CertificateException

Sets this object to be the unsigned CRL represented by x509InnerDER, beginning at offset, the DER encoding of the inner CRL of an X.509 CRL. If this object is already set with CRL information, this method deletes any internal copy of that data and replaces it with the new CRL.

Parameters

	x509InnerDER		The DER encoding of the inner CRL of an X.509 unsigned CRL.
	offset		The offset into x509InnerDER where the encoding begins.

Throws

CertificateException - If the DER is not a valid X.509 CRL.

getInnerDERLen

public int getInnerDERLen()

Returns the number of bytes of the innerDER. If this object is not set with values, the method returns zero.

Returns

The number of bytes in the inner DER encoding of the CRL information.

getInnerDER

public int getInnerDER(byte[] encoding,
                       int offset)
                throws CertificateException

Places the DER encoding of the inner DER of the CRL in this object into encoding, beginning at offset. To determine the length of the encoding, call getInnerDERLen. If this object is not yet set with a CRL, this method throws an exception.

Parameters

	encoding		The byte array into which the result will be placed.
	offset		The offset into encoding where the writing is to begin.

Returns

The number of bytes placed into encoding.

Throws

CertificateException - if the object is not set with a valid signed X.509 CRL.

getSignature

public byte[] getSignature()
                    throws CertificateException

Gets the signature octets. An X.509 CRL wraps the signature in a BIT STRING.

Overrides

getSignature in class CRL

Returns

The new byte array that contains the signature octets.

Throws

CertificateException - If the CRL has not yet been signed.

setVersion

public void setVersion(int version)
                throws CertificateException

Sets the version of this CRL to version. The input should be X509CRL.X509_VERSION_1 or X509CRL.X509_VERSION_2. If the CRL object possesses a signature, calling this method causes the signature to be deleted.

Parameters

version

The version number of this CRL.

Throws

CertificateException - If the input value is an unsupported version number.

getVersion

public int getVersion()

Gets the version of this CRL. The result will be X509CRL.X509_VERSION_1 or X509CRL.X509_VERSION_2, previously defined in this class. If the CRL has not yet been set, this method will return the default version number, version 1.

Returns

An int that contains the version number.

setIssuerName

public void setIssuerName(X500Name issuerName)
                   throws CertificateException

Sets the issuer name of this CRL to be issuerName. If the CRL object possesses a signature, calling this method causes the signature to be deleted.

Parameters

issuerName

An X500Name object that contains the issuer name.

Throws

CertificateException - If the issuerName is invalid.

getIssuerName

public X500Name getIssuerName()

Gets the issuer name of this CRL. If there is no issuer name in this CRL object, this method returns null.

Returns

A new X500Name object that contains the name.

setNextUpdate

public void setNextUpdate(Date update)

Sets the time when the next CRL is updated. If the CRL object possesses a signature, calling this method causes the signature to be deleted.

Parameters

update

A Date specifying when the next CRL is updated.

getNextUpdate

public Date getNextUpdate()

Gets the date by which the next update will be issued.

Returns

A Date that contains the nextUpdate value.

setThisUpdate

public void setThisUpdate(Date update)

Sets the time of the issue date of this CRL to be update. If the CRL object possesses a signature, calling this method causes the signature to be deleted.

Parameters

update

A Date specifying the issue date value.

getThisUpdate

public Date getThisUpdate()

Gets the issue date of this CRL.

Returns

A Date that contains the issue date value.

setRevokedCertificates

public void setRevokedCertificates(RevokedCertificates revokedCerts)
                            throws CertificateException

Sets the value of the revokedCerts field of this CRL to revokedCerts. If the CRL object possesses a signature, calling this method causes the signature to be deleted.

Parameters

revokedCerts

A RevokedCertificates object that contains the revoked certificates.

getRevokedCertificates

public RevokedCertificates getRevokedCertificates()

Gets the revoked certificates of this CRL. If there is no revoked certificate in this CRL object, this method returns null.

Returns

A new RevokedCertificates object. If there is no revoked certificate, this method returns null.

compareIssuerName

public boolean compareIssuerName(X500Name issuerName)

Compares the given name, issuerName, with the issuer name of the CRL represented by this object. If they are the same, this method returns true; otherwise, false. This method is useful for finding a CRL in a collection of CRLs.

Parameters

issuerName

An X500Name object that contains the issuer name to compare.

Returns

A boolean indicating whether the given name matches the issuer name of the CRL represented by this object.

setTimeType

public void setTimeType(boolean flag)

Sets the flag specifying the time encoding type to use.

Parameters

flag

A true value sets the encoding type to GeneralTime. A false value sets the encoding type to UTC.

setExtensions

public void setExtensions(X509V3Extensions extensions)
                   throws CertificateException

Sets the extensions of this CRL to be extensions. The CRL must be a version 2 CRL. If the CRL object possesses a signature, calling this method causes the signature to be deleted. Valid values for extensions are one of the X509_EXT_TYPE_* fields defined in the X509V3Extentions class.

Parameters

extensions

An X509V3Extensions object that contains the extensions.

Throws

CertificateException - If the CRL is not version 2, or if the extensions object is of the wrong type.

getExtensions

public X509V3Extensions getExtensions()

Gets the extensions in this CRL. If there are no extensions, this method returns zero.

Returns

An X509V3Extensions object that contains the extensions.

signCRL

public void signCRL(String transformation,
                    String device,
                    com.rsa.jsafe.JSAFE_PrivateKey signingKey,
                    SecureRandom random)
             throws CertificateException

Signs the CRL using transformation and signingKey on the specified device. The format of transformation follows the format specified in the Crypto-J class JSAFE_Signature. The following are examples of transformation arguments:

   "MD5/RSA/PKCS1Block01Pad"
   "SHA1/DSA"

The format of device follows the format specified in Crypto-J. The following are examples of device arguments.

   Java          --Perform signature using Java code
   Native        --Perform signature using the native link
   Native/Java   --Use native if possible, if not, use Java

For more information, see the RSA BSAFE Crypto-J Javadocs.

Overrides

signCRL in class CRL

Parameters

	transformation		A String specifying the algorithm to use to sign the CRL.
	device		A String specifying the device or choice of devices to use in computing the signature.
	signingKey		A JSAFE_PrivateKey used to compute the signature.
	random		If the signature algorithm needs random bytes, get them from this object.

Throws

CertificateException - If the code cannot perform the specified transformation on the specified device, the CRL is not set properly, or the CRL is already signed.

verifyCRLSignature

public boolean verifyCRLSignature(String device,
                                  com.rsa.jsafe.JSAFE_PublicKey verifyingKey,
                                  SecureRandom random)
                           throws CertificateException

Verifies the CRL's signature, using verifyingKey, on the specified device.

The format of device follows the format specified in Crypto-J. The following are examples of device arguments.

   Java          --Perform signature using Java code
   Native        --Perform signature using the native link
   Native/Java   --Use native if possible, if not, use Java

For more information, see the RSA BSAFE Cert-J Javadocs.

Overrides

verifyCRLSignature in class CRL

Parameters

	device		A String specifying the device or choice of devices to use in computing the signature.
	verifyingKey		A JSAFE_PublicKey used to verify the signature.
	random		If the signature algorithm needs random bytes, get them from this object.

Returns

A boolean indicating whether the signature on the CRL is valid.

Throws

CertificateException - If the code cannot perform the signature algorithm on the specified device.

equals

public boolean equals(Object obj)

Returns true if this object and obj contain the same X509CRL; otherwise false.

Overrides

equals in class Object

Parameters

obj

An instance of the X509CRL object.

Returns

A boolean indicating whether these objects are equal.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A copy of this object in its current state.

Throws

CloneNotSupportedException - If the cloning operation is not successful.