CRL Distribution Points with CMS 4.0

Background

A CRL Distribution Point is the location whence a CRL can be obtained. RFC 2459 section 4.2.1.14 defines the ASN.1 as follows:

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) }

The intention is that one or more CRL Distribution Points be included as an extension in each certificate. One reason for having more than one DP associated with a cert is that the different DPs may have different reasons. For example, one DP might contain certs that have been revoked because of key compromise, and it would be consulted with higher priority and frequency than a DP whose certs were revoked for more mundane reasons.

Source Code

The source code for the plugin is contained in three files:

CRLDistributionPoint.java contains a class that models a CRL Distribution Point as defined by PKIX.
CRLDistributionPointsExtension.java is the extension plugin. It extends the Extension class and implements the CertAttrSet interface, which allows it to be plugged in to the server's extension map.
CRLDistributionPointPolicy is the policy plugin. It implements IEnrollmentPolicy, which allows it be installed as a policy module within the server.

These classes are defined in the default, top-level package. To compile them, the CLASSPATH must point to that of an existing CMS installation. Then, javac can be run on each source file to produce the following class files:

CRLDistributionPoint.class
CRLDistributionPointPolicy.class
CRLDistributionPointsExtension.class
DistPointParams.class
NameType.class
Reason.class

Installation within CMS 4

CRL Distribution Point functionality is included as sample code with CMS 4.01. It operates as a policy plug-in module. It initially reads its parameters from the CMS.cfg file, and uses them to construct a static CRL Distribution Point certificate extension. Then, it appends this same extension to every certificate it examines. The following steps can be followed to install the sample plugin:

Install and configure the server normally.
Copy the sample class files (listed in the previous section) to <server-root>/<instance-name>/classes:
In the CMS management console, register the plugin.
- Select the Configuration tab.
- Expand the Certificate Manager folder.
- Click the Policies node.
- In the right pane, click the Policy Plugin Registration tab.
- Click the Register button.
- Enter the plugin name and class name. The plugin name can be any convenient name (no spaces allowed); for example, "CRLDistributionPoints". The class name must be CRLDistributionPointPolicy.
- Click OK.
Add the new policy.
- Click the Policy Rules Management tab.
- Click the Add button.
- Select the plugin name (chosen in the last step) for the CRL Distribution Point policy.
- Click Next.
- Enter a convenient name, such as "CRLDistributionPoints", in the Policy Rule ID box.
- Change the value of the "enable" parameter to "false".
- Click OK.
Shutdown the server.
Edit the server configuration file, CMS.cfg.
- Insert parameters for the policy. Policy parameters are explained later in this document.
- Save the configuration file.
Start the server.

Enable the policy.

Edit the Policy Rule, changing the value of the "enable" parameter to "true".

At this point, the CRL Distribution Point extension will be included in all certificates issued by the server. The contents of the extension will be determined by the parameters in the configuration file.

Configuration Parameters

Extension Parameters

Name	Value	Default
enable	`true` to enable the plugin, `false` to disable it	true
critical	`true` if the extension should be critical, `false` otherwise.	`false`, since RFC 2459 specifies it SHOULD NOT be critical
numPoints	The number of distribution points to be contained in the extension. There must be configuration parameters given for each.	None.

Individual Distribution Point Parameters

There should be one set of these for each distribution point. The index number n is appended to the name of the attribute. All attributes are optional; if not specified, they will be left out of the distribution point.

Name	Value
pointName, pointType	The name of the distribution point. This can be in one of the following formats: An X.500 Name in RFC1779 syntax, in which case the `pointType` attribute must be `DirectoryName`. A URI, in which case the `pointType` attribute must be `URI`. An RDN which specifies a location relative to the CRL Issuer. In this case, the `pointType` attribute must be `RelativeToIssuer`.
reasons	The reasons for this CRL. Should be a comma-separated list of the following constants: `unused` `keyCompromise` `cACompromise` `affiliationChanged` `superseded` `cessationOfOperation` `certificateHold`
issuerName, issuerType	The name of the CRL issuer. May be: an X.500 Name, in which case `issuerType` should be `DirectoryName`. a URI, in which case `issuerType` should be `URI`.

Sample Parameters

These simple parameters describe a single distribution point with no reason flags or issuer name.

ca.Policy.rule.CRLDistributionPoints.numPoints=1
ca.Policy.rule.CRLDistributionPoints.pointName0=http://crlfest.com/get/your/crls/here/
ca.Policy.rule.CRLDistributionPoints.pointType0=URI

These parameters describe two distribution points. The first has a directory (distinguished) name. The second distribution point name is relative to the location of the CRL issuer, which is also given as a directory name. The points are differentiated by their reasons.

ca.Policy.rule.CRLDistributionPoints.numPoints=2
ca.Policy.rule.CRLDistributionPoints.pointName0=CN=CRLCentral,OU=Research Dept.,O=CertCorp,C=US
ca.Policy.rule.CRLDistributionPoints.pointType0=DirectoryName
ca.Policy.rule.CRLDistributionPoints.reasons0=keyCompromise,cACompromise
ca.Policy.rule.CRLDistributionPoints.pointName1=CN=SubCN
ca.Policy.rule.CRLDistributionPoints.pointType1=RelativeToIssuer
ca.Policy.rule.CRLDistributionPoints.reasons1=superseded,cessationOfOperation
ca.Policy.rule.CRLDistributionPoints.issuerName1=OU=Research Dept.,O=CertCorp,C=US
ca.Policy.rule.CRLDistributionPoints.issuerType1=DirectoryName