iaik.x509.extensions

Class CRLDistributionPoints

java.lang.Object

iaik.x509.V3Extension

iaik.x509.extensions.CRLDistPointsSyntax

iaik.x509.extensions.CRLDistributionPoints

public class CRLDistributionPoints
extends CRLDistPointsSyntax

This class implements the CRLDistributionPoints Extension.

The CRLDistributionPoints extension is a non critical standard X509v3 extension.

Each extension is associated with a specific certificateExtension object identifier, derived from:

 certificateExtension  OBJECT IDENTIFIER ::=
                            {joint-iso-ccitt(2) ds(5) 29}
 id-ce                 OBJECT IDENTIFIER ::=  certificateExtension
 

The object identifier for the CRLDistributionPoints extension is defined as:

id-ce-cRLDistributionPoints OBJECT IDENTIFIER ::= { id-ce 31 }

which corresponds to the OID string "2.5.29.31".

The X.509 Certificate and CRL profile presented in RFC 3280 specifies the CRL distribution points extension for identifiying how CRL information is obtained.

ASN.1 definition:

 cRLDistributionPoints ::= {
    CRLDistPointsSyntax }
 

 CRLDistPointsSyntax ::= SEQUENCE SIZE (1..MAX) OF DistributionPoint
 

 DistributionPoint ::= SEQUENCE {
    distributionPoint       [0]     DistributionPointName OPTIONAL,
    reasons                 [1]     ReasonFlags OPTIONAL,
    cRLIssuer               [2]     GeneralNames OPTIONAL }
 

 DistributionPointName ::= CHOICE {
    fullName                [0]     GeneralNames,
    nameRelativeToCRLIssuer [1]     RelativeDistinguishedName }
 

 ReasonFlags ::= BIT STRING {
    unused                  (0),
    keyCompromise           (1),
    cACompromise            (2),
    affiliationChanged      (3),
    superseded              (4),
    cessationOfOperation    (5),
    certificateHold         (6) }
 

If the cRLDistributionPoints extension contains a DistributionPointName of type URI, the following semantics shall be assumed: the URI is a pointer to the current CRL for the associated reasons and will be issued by the associated cRLIssuer. If the distributionPoint omits reasons, the CRL shall include revocations for all reasons. If the distributionPoint omits cRLIssuer, the CRL shall be issued by the CA that issued the certificate.

The DistributionPointName maybe a GeneralNames object (fullName field) or a RelativeDistinguishedName (nameRelativeToCRLIssuer field).
If given as GeneralNames, the distribution name typically will represent a URI pointing to a location from where the CRL can be obtained. If the GeneralNames contains more than one value, each value uses a different mechanism to reference the same CRL (for instance, one value may represent a http url and a second value may represent an ldap url from where the same crl can be loaded).
If the distribution point name is given as RelativeDistinguishedName, the RDN value has to be appended to the distinguished name of the CRL issuer to represent an entry in a X.500 or LDAP directory. If the cRLIssuer field is present (indirect CRL), it has to contain a distinguished name to which the distribution point name RDN has to be appended. Otherwise (if the cRLIssuer field is not set) the crl issuer is the same as the certificate issuer and the distribution point name RDN has to be appended to the distinguished name of the certificate issuer.
If the DistributionPointName field is not present, the cRLIssuer field must be present and must represent the DN of a X.500 or LDAP directory from which the crl can be obtained.

More information can be found in RFC 3280, section 4.2.1.14 "CRLDistributionPoints".

A CRLDistributionPoints object may be created by either using the empty default constructor, or by directly supplying one distribution point which has to be of type DistributionPoint, e.g.:

 String crlUri = "http://ca.iaik.at/test.crl";
 DistributionPoint dp = new DistributionPoint(new String[] { crlUri });
 dp.setReasonFlags(DistributionPoint.keyCompromise);
 CRLDistributionPoints cRLDistributionPoints = new CRLDistributionPoints(dp);
 

Any further distribution point can be added by using the addDistributionPoint method:

cRLDistributionPoints.addDistributionPoint(<a_second_distribution_point>); ...

For adding a CRLDistributionPoints extension object to a X509Certificate, use the addExtension method of the iaik.x509.X509Certificate class:

 X505Certificate cert = new X509Certificate();
   ...
 cert.addExtension(cRLDistributionPoints);
 ...
 

On the receiving side, when validating the CRLDistributionPoints extension of a certificate, you may check the included DistributionPoints:

 X509Certificate cert = ...;
 ...
 // get CRLDistributionPoints extension
 CRLDistributionPoints cRLDistributionPoints = cert.getExtension(CRLDistributionPoints.oid);
 if (cRLDistributionPoints != null) {
   // get DistributionPoints
   Enumeration e = cRLDistributionPoints.getDistributionPoints();
   while (e.hasMoreElements()) {
     DistributionPoint dp = (DistributionPoint)e.nextElement();
     // assume URI distribution point name(s)
     String[] crlUris = dp.getDistributionPointNameURIs();
     ...
     // get CRL issuer
     Name crlIssuerName = dp.getCrlIssuerName();
     if (crlIssuerName != null) {
       ...
     }
     // get reason flags
     int reasonFlags = dp.getReasonFlags();
     if (reasonFlags != -1) {
       ...
     }
   }
 }
 
 

While stepping through the included DistributionPoints you may use DistributionPoint method loadCrl or loadCrl(String ldapUrl, Name crlIssuer) for downloading the crl from its distribution point.
Most usually you only will need the first method (loadCrl()) since it downloads the crl from an uri distribution point name which is the most common way of referencing a crl location from within a DistributionPoint. If more than one distribution point name value is present, each value uses a different mechanism to point to the same CRL. For instance, a DistributionPointName may contain two uri values, one pointing to a "http" location (e.g. "http://democa.iaik.at/testCA.crl") and the second pointing to a "ldap" location (e.g. "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary"). Method loadCrl() steps through all uri distribution point names included and tries to download the crl from them. In the sample above, loadCrl first would connect to "http://democa.iaik.at/testCA.crl" and try to download the crl from it. If not successful the second (and in this example last) distribution point name "ldap://demoldap.iaik.at/cn=TestCA,o=iaik,c=at?certificateRevocationList;binary" is contacted to download the crl from it.

If you want to be sure that this DistributionPoint contains an distribution point name of type uniformResourceIdentifier, you first may call method containsUriDpName:

 ...
   DistributionPoint dp = (DistributionPoint)e.nextElement();
   if (dp.containsUriDpName()) {
     // download crl
     X509CRL crl = dp.loadCrl();
     ...
   }
 ...  
 

If you expect to download a very large crl you alternatively may call method loadCrlStream and use the stream based crl implementation of IAIK-JCE for parsing the crl.

If this distribution point does not contain a uri distribution point name, but a RDN and/or cRLIssuer field, you may use method loadCrl(String url, Name certificateIssuer) for downloading the crl from a specific entry of an ldap server. In this case the DistributionPoint only contains the DN pointing to an entry at the ldap directory, but does not contain the ldap server url itself. For that reason you have to specify the ldap server url when calling method loadCrlStream(), e.g.:

 String url = "ldap://demoldap.iaik.at";
 Name crlIssuer = ...;
 DistributionPoint distributionPoint = ...;
 X509CRL crl = distributionPoint.loadCrl(url, crlIssuer);
 

The crlIssuer only has to be specified if the cRLIssuer field of the DistributionPoint is not set and therefore the crl issuer is the same entity as the certificate issuer. For instance, let us assume, that the distributionPoint from above contains a RDN distribution point name with "uid=crl". The crlIssuer shall be given as "cn=TestCA,o=iaik,c=at". In this case the crl is downloaded from the entry "uid=crl,cn=TestCA,o=iaik,c=at" from the ldap server running at "ldap://demoldap.iaik.at".

If you expect to download a large crl you alternatively may call method loadCrlStream(String ldapUrl, Name certificateIssuer) and use the stream based crl implementation of IAIK-JCE for parsing the crl.

All loadCrl, loadCrlStream methods use an java.net.URLConnection for downloading the crl. Thus only protocols can be supported for which an java.net.URLStreamHandler is available. Since the http protocol is supported by the JDK by default, crls can be downloaded from http uri distribution point names. If you want to support ldap, too, you will have to register the IAIK LdapURLConnection implementation, e.g. by using the java.protocol.handler.pkgs system property:

 System.getProperties().put("java.protocol.handler.pkgs", "iaik.x509.net");
 

In this case you will have to ensure that the Java Naming and Directory interface (JNDI) is available. For JDK versions >=1.3 the JNDI is included in the JDK, for JDK versions <1.3 you also will have to put jndi.jar, ldap.jar and providerutil.jar into your classpath which can be downloaded from the JNDI homepage at SUN: http://java.sun.com/products/jndi.

Version:

File Revision 29

See Also:

DistributionPoint, GeneralNames, Name, V3Extension, X509Extensions, X509Certificate, CRLDistPointsSyntax

Field Summary

Fields

Modifier and Type	Field and Description
static ObjectID	oid The object identifier of this CRLDistributionPoints extension.

Fields inherited from class iaik.x509.V3Extension

critical

Constructor Summary

Constructors

Constructor and Description
CRLDistributionPoints() Default constructor.
CRLDistributionPoints(DistributionPoint dp) Creates an CRLDistributionPoints object and adds an DistributionPoint.

Method Summary

Methods

Modifier and Type	Method and Description
ObjectID	getObjectID() Returns the object ID of this CRLDistributionPoints extension
int	hashCode() Returns a hashcode for this identity.

Methods inherited from class iaik.x509.extensions.CRLDistPointsSyntax

addDistributionPoint, getDistributionPoints, init, removeAllDistributionPoints, toASN1Object, toString

Methods inherited from class iaik.x509.V3Extension

getName, isCritical, setCritical

Methods inherited from class java.lang.Object

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

Field Detail

oid

public static final ObjectID oid

The object identifier of this CRLDistributionPoints extension. The corresponding OID string is "2.5.29.31".

Constructor Detail

CRLDistributionPoints

public CRLDistributionPoints()

Default constructor. Creates an empty CRLDistributionPoints object.

For adding a distribution point use the addDistributionPoint method. Any distribution point to be added has to be of type iaik.asn1.structures.DistributionPoint, e.g.:

 String crlUri = "http://ca.iaik.at/test.crl";
 DistributionPoint dp = new DistributionPoint(new String[] { crlUri });
 dp.setReasonFlags(DistributionPoint.keyCompromise);
 CRLDistributionPoints cRLDistributionPoints = new CRLDistributionPoints();
 cRLDistributionPoints.addDistributionPoint(dp);
 

See Also:

DistributionPoint

CRLDistributionPoints

public CRLDistributionPoints(DistributionPoint dp)

Creates an CRLDistributionPoints object and adds an DistributionPoint.

The distribution point to be added has to be of type iaik.asn1.structures.DistributionPoint, e.g.:

 String crlUri = "http://ca.iaik.at/test.crl";
 DistributionPoint dp = new DistributionPoint(new String[] { crlUri });
 CRLDistributionPoints cRLDistributionPoints = new CRLDistributionPoints(dp);
 

Parameters:

dp - the distribution point to add

See Also:

DistributionPoint

Method Detail

getObjectID

public ObjectID getObjectID()

Returns the object ID of this CRLDistributionPoints extension

Specified by:

getObjectID in class V3Extension

Returns:

the object ID

hashCode

public int hashCode()

Returns a hashcode for this identity.

Specified by:

hashCode in class V3Extension

Returns:

a hash code for this identity