iaik.x509
Class RevokedCertificate

java.lang.Object
  |
  +--java.security.cert.X509CRLEntry
        |
        +--iaik.x509.RevokedCertificate

All Implemented Interfaces:

Cloneable, X509Extension

public class RevokedCertificate

extends X509CRLEntry

implements Cloneable

This class represents a revoked certificate.

A revoked certificate denotes a certificate that has been expired for some reason (e.g. the name of the subject has changed, the private key can no more being treated to be only known by the subject, ...) prior to the regular ending of its validity period.

Revoked certificates are collected in certificate revocation lists (CRLs) maintained by certificate issuing certification authorities (CAs). CRLs are publicly available and have to be refreshed in certain time intervals. Each certificate included in a revocation list can be identified by its serial number. The recvocation list is signed by the maintaining CA.

A profile for X.509v2 revocation lists is presented together with the X.509v3 certificate format in RFC 2459, where revoked certificates are defined as the following ASN.1 structure:

 revokedCertificates     SEQUENCE OF SEQUENCE  {
   userCertificate         CertificateSerialNumber,
   revocationDate          Time,
   crlEntryExtensions      Extensions OPTIONAL
                           -- if present, must be v2
 }  OPTIONAL
 

where:

 CertificateSerialNumber  ::=  INTEGER

 Time ::= CHOICE {
   utcTime        UTCTime,
   generalTime    GeneralizedTime }

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension

 Extension  ::=  SEQUENCE  {
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE,
   extnValue   OCTET STRING  }
 

The serial number is used for uniquely identifying some particular certificate within a given revocation list. The revocation date specifies the date on which the revocation of the listed certificate becomes meaning. Dates through the year 2049 shall be encoded as UTCTime, and dates in 2050 or later as GeneralizedTime.

The crlEntryExtensions field may be used for including some additional information. An extension may be a defined standard entry extension (e.g. reasonCode for specifying the reason for revocation), or it may be a private entry extension providing some community-specific information. If an entry extension is marked as critical, but the CRL handling software cannot properly parse this extension, the CRL validation must fail. Non-Critical entry extensions can be ignored, if they cannot be handled (i.e. of unknown state).

The X509CRL class maintaines revoked certificate in a hashtable using the certificate´s serial number as key. A revoked certifcate represents a CRL entry.

For adding a CRL entry extension to a revoked certificate, use the addExtension method, e.g.:

 //Create a revoked certificate from a X509Certificate and set the revocation date
 //to the current date; the X509Certificate is read in from a file:
 GregorianCalendar date = (GregorianCalendar)Calendar.getInstance();
 InputStream fis = new FileInputStream("cert.der");
 X509Certificate cert = new X509Certificate(fis);
 fis.close();
 RevokedCertificate rev_cert = new RevokedCertificate(cert, date.getTime());
 //add the reason code CRL entry extension to the revoked certificate:
 ReasonCode reasonCode = new ReasonCode(ReasonCode.keyCompromise);
 rev_cert.addExtension(reasonCode);
 

Version:

File Revision 30

See Also:

X509CRL, X509Certificate

Constructor Summary

RevokedCertificate(ASN1Object obj)
Creates a revoked certificate from an ASN1Object.

RevokedCertificate(BigInteger serialNumber, Date revocationDate)
Creates a revoked certificate from a serial number and a date.

RevokedCertificate(X509Certificate cert, Date revocationDate)
Creates a revoked certificate from a certificate and a date.

Method Summary

void	addExtension(V3Extension e) Adds the given extension to this revoked certificate.
Object	clone() Returns a clone of this RevokedCertificate.
int	countExtensions() Returns the number of extensions included into this revoked certificate.
Set	getCriticalExtensionOIDs() Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this revoced certificate.
byte[]	getEncoded() Returns this RevokedCertificate as DER encoded ASN.1 data structure
V3Extension	getExtension(ObjectID oid) Returns a specific extension, identyfied by its object identifier.
byte[]	getExtensionValue(String oid) Returns a byte array representing the DER encoding of the extension value identified by the passed-in OID string.
Set	getNonCriticalExtensionOIDs() Returns a Set of the OID strings identifying the extension(s) that are marked NON-CRITICAL in this revoced certificate.
Date	getRevocationDate() Returns the revocation date of the revoked certificate.
BigInteger	getSerialNumber() Returns the serial number of the revoked certificate.
boolean	hasExtensions() Checks if there are extensions included into this revoked certificate.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
Enumeration	listExtensions() Returns an enumeration of all entry extensions included into this revoked certificate.
void	removeAllExtensions() Removes all extensions from this revoked certificate.
boolean	removeExtension(ObjectID oid) Removes the extension specified by its object identifier.
ASN1Object	toASN1Object() Returns the revoked certificate as ASN1Object.
String	toString() Returns a string that represents this revoked certificate.
String	toString(boolean detailed) Returns a string with - if requested - detailed information about this revoked certificate.

Methods inherited from class java.security.cert.X509CRLEntry

equals, hashCode

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RevokedCertificate

public RevokedCertificate(ASN1Object obj)
                   throws CRLException

Creates a revoked certificate from an ASN1Object.

The given ASN1Object is parsed for required serial number and revocation date, and - if included - CRL entry extensions.

This constructor may be used for parsing an already existing RevokedCertificate, supplied as ASN1Object that may have been created by calling the toASN1Object method.

Parameters:

obj - the revoked certificate as ASN1Object

Throws:

CRLException - if the ASN1Object can not be parsed

RevokedCertificate

public RevokedCertificate(X509Certificate cert,
                          Date revocationDate)

Creates a revoked certificate from a certificate and a date. The required serial number is obtained from the given certificate.

Parameters:

cert - the certificate, which should be revoked

revocationDate - the date when the certificate becomes invalid

RevokedCertificate

public RevokedCertificate(BigInteger serialNumber,
                          Date revocationDate)

Creates a revoked certificate from a serial number and a date.

Parameters:

serialNumber - the serial number of the certificate to revoke

revocationDate - the date when the certificate becomes invalid

Method Detail

clone

public Object clone()

Returns a clone of this RevokedCertificate.

Overrides:

clone in class Object

Returns:

a clone of this RevokedCertificate

toASN1Object

public ASN1Object toASN1Object()
                        throws CRLException

Returns the revoked certificate as ASN1Object.

Returns:

the revoked certificate as (SEQUENCE) ASN1Object

Throws:

CRLException - if the ASN1Object could not be created

getEncoded

public byte[] getEncoded()
                  throws CRLException

Returns this RevokedCertificate as DER encoded ASN.1 data structure

Overrides:

getEncoded in class X509CRLEntry

Returns:

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

Throws:

CRLException - if the RevokedCertificate cannot be encoded correctly

getSerialNumber

public BigInteger getSerialNumber()

Returns the serial number of the revoked certificate.

Overrides:

getSerialNumber in class X509CRLEntry

Returns:

the serial number of the revoked certificate

getRevocationDate

public Date getRevocationDate()

Returns the revocation date of the revoked certificate.

Overrides:

getRevocationDate in class X509CRLEntry

Returns:

the revocation date of the revoked certificate

getCriticalExtensionOIDs

public Set getCriticalExtensionOIDs()

Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this revoced certificate.

Overrides:

getCriticalExtensionOIDs in class X509CRLEntry

Returns:

a Set (or an empty Set if none are marked critical) of the extension OID strings for extensions that are marked critical. If there are no extensions present at all, then this method returns null

See Also:

getNonCriticalExtensionOIDs()

getNonCriticalExtensionOIDs

public Set getNonCriticalExtensionOIDs()

Returns a Set of the OID strings identifying the extension(s) that are marked NON-CRITICAL in this revoced certificate.

Overrides:

getNonCriticalExtensionOIDs in class X509CRLEntry

Returns:

a Set (or an empty Set if none are marked non-critical) of the extension OID strings for extensions that are marked non-critical. If there are no extensions present at all, then this method returns null.

See Also:

getCriticalExtensionOIDs()

getExtensionValue

public byte[] getExtensionValue(String oid)

Returns a byte array representing the DER encoding of the extension value identified by the passed-in OID string.

The oid string is represented by a set of positive whole numbers separated by periods, e.g. "2.5.29.21" for the ReasonCode extension.

In ASN.1, the Extensions field is defined as a SEQUENCE of Extension:

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension

 Extension  ::=  SEQUENCE  {
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE,
   extnValue   OCTET STRING  }
 

where critical specifies whether an extension has to be treated as being critical or not; the default value is FALSE. An extension can be identified by its object identifier, given in the extnID field. The value of the extension is represented as ASN.1 encoded OCTET STRING data structure in the extnValue field.

The byte value returned by this method represents the DER encoding of the extnValue (OCTET_STRING) from above, and the value of this OCTET STRING represents the DER encoding of the specific extension´s ASN.1 representation itsself.

Attention: For compatibility reasons to the standard JCA certificate API this method has been changed to return the OCTET STRING value as described above. Prior versions of this class have returned the DER encoding of the specific extension´s ASN.1 representation itsself.

Overrides:

getExtensionValue in class X509CRLEntry

Parameters:

oid - the Object identifier of the extension to be searched for, as String

Returns:

the DER encoding of the requested extension value or null if it is not present

hasExtensions

public boolean hasExtensions()

Checks if there are extensions included into this revoked certificate.

Overrides:

hasExtensions in class X509CRLEntry

Returns:

true if extensions are included, false if not

hasUnsupportedCriticalExtension

public boolean hasUnsupportedCriticalExtension()

Returns true if there are unsupported critical extensions.

Overrides:

hasUnsupportedCriticalExtension in class X509CRLEntry

Returns:

true, if there are unsupported critical extensions

addExtension

public void addExtension(V3Extension e)
                  throws X509ExtensionException

Adds the given extension to this revoked certificate.

The extension to be added shall be an implemented V3Extension. Extensions are managed by the X509Extensions class which maintaines two hashtables, one for recording critical extensions, and the other for non-critical extensions. This method only calls the addExtension method of the X509Extensions class for putting the given extension into the proper hashtable. Note that only the DER encoded extension value is written to the hashtable using the OID of the extension as key. If an extension with the same object ID already exists, it is replaced.

For instance:

 ReasonCode reasonCode = new ReasonCode(ReasonCode.keyCompromise);
 revokedCertificate.addExtension(reasonCode);
 

For reading back some extension from one of the hashtables, use the getExtension(ObjectID) method. Only at this time actually the appropriate implementation class is created and initialized through the DER encoded extension value derived from the corresponding hashtable.

Parameters:

e - the extension to add to the list of extensions

Throws:

X509ExtensionException - if an error occurs while DER encoding the extension

See Also:

V3Extension

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 successfully has been removed false otherwise

removeAllExtensions

public void removeAllExtensions()

Removes all extensions from this revoked certificate.

listExtensions

public Enumeration listExtensions()

Returns an enumeration of all entry extensions included into this revoked certificate.

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

Notice that this method only calls the listExtensions method of the X509Extensions class for actually instantiating implementations for the included extensions and initializing them with the appertaining extension values previously written to proper hashtables. If any extension cannot be parsed properly, an ErrorExtension is created from it and written to the enumeration list returned by this method.

Returns:

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

countExtensions

public int countExtensions()

Returns the number of extensions included into this revoked certificate.

Returns:

the number of extensions

getExtension

public V3Extension getExtension(ObjectID oid)
                         throws X509ExtensionInitException

Returns a specific extension, identyfied by its object identifier.

This method only calls the getExtension(ObjectID) method of the X509Extensions class for actually instantiating an implementation for the requested extension and initializing it with the appertaining extension value previously written to a proper hashtable. 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

See Also:

X509Extensions.getExtension(iaik.asn1.ObjectID)

toString

public String toString()

Returns a string that represents this revoked certificate.

Overrides:

toString in class X509CRLEntry

Returns:

the string representation

toString

public String toString(boolean detailed)

Returns a string with - if requested - detailed information about this revoked certificate.

Parameters:

detailed - - whether or not to give detailed information about this revoked certificate.

Returns:

the string representation