Chapter 7   CRL Extension Plug-in Modules


You can configure a Certificate Manager to generate CRLs and publish them to repositories such as an LDAP directory, a flat file, or an OCSP responder which other applications may use for checking the revocation status of a certificate or from which other applications can retrieve the CRL. You can also configure the Certificate Manager to generate and publish CRLs conforming to either X.509 version 1 or X.509 version 2 standards—CRLs compliant to X.509 version 2 standards contain CRL extensions.

To enable you to add these extensions to the CRL it generates, the Certificate Manager provides a set of plug-in modules. These modules are implemented as Java classes and are registered with the Certificate Manager's publishing framework.

This chapter explains plug-in modules that are installed with a Certificate Manager—it lists and briefly describes the modules and then explains each one in detail.

The chapter has the following sections:

• Overview of CRL Extension Modules

• AuthorityKeyIdentifier Rule

• CRLNumber Rule

• CRLReason Rule

• HoldInstruction Rule

• InvalidityDate Rule

• IssuerAlternativeName Rule

• IssuingDistributionPoint Rule

Overview of CRL Extension Modules

---

To enable you issue or publish X.509 v2 CRLs (that is, CRLs with extensions), Certificate Management System provides a set of plug-in modules; each module enables you to configure the Certificate Manager to set a particular CRL or CRL-entry extension in CRLs it issues. Plug-in modules are implemented as Java classes and are registered in the CMS publishing framework. The CRL Extensions Management tab of the CMS window (Figure 7-1) lists all the modules that are registered with a Certificate Manager.

When deciding whether to add CRL extensions, keep in mind that not all applications support version 2 CRLs. Among the applications that do support extensions, not all applications will recognize every extension. For general guidelines on using these extensions in CRLs, see Appendix C, "Certificate and CRL Extensions."

Figure 7-1    Default CRL extension modules registered with a Certificate Manager

Table 7-1 lists CRL extension modules that are installed with a Certificate Manager. For instructions on how to configure a Certificate Manager to set CRL extensions, see section "Configuring a Certificate Manager to Publish Certificates and CRLs" in Chapter 19, "Setting Up LDAP Publishing" of CMS Installation and Setup Guide.

Table 7-1    Default CRL extension modules  

Plug-in module name	Function
AuthorityKeyIdentifier	Sets the Authority Key Identifier extension in CRLs. For details, see "AuthorityKeyIdentifier Rule".
CRLNumber	Sets the CRL Number extension in CRLs. For details, see "CRLNumber Rule".
CRLReason	Sets the Reason Code extension in CRL entries. For details, see "CRLReason Rule".
HoldInstruction	Sets the Hold Instruction Code extension in CRL entries. For details, see "HoldInstruction Rule".
InvalidityDate	Sets the Invalidity Date extension in CRL entries. For details, see "InvalidityDate Rule".
IssuerAlternativeName	Sets the Issuer Alternative Name extension in CRLs. For details, see "IssuerAlternativeName Rule".
IssuingDistributionPoint	Sets the Issuing Distribution Point extension in CRLs. For details, see "IssuingDistributionPoint Rule".

AuthorityKeyIdentifier Rule

---

The AuthorityKeyIdentifier rule enables you to configure a Certificate Manager to set the Authority Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is used to identify the public key that corresponds to the private key used by a CA to sign CRLs.

The PKIX standard recommends that the CA must include this extension in all CRLs it issues. Therefore, you should consider adding this extension to all CRLs issued by the Certificate Manager. The reason for this is that in certain situations, a CA's public key may change (for example, when the key gets updated) or the CA may have multiple signing keys (either because of multiple concurrent key pairs or because of key changeover). In these cases, the CA ends up with more than one key pair. When verifying a signature on a certificate, other applications need to know which key was used in the signature. The extension, if present in a certificate, enables applications (those that can use the extension) to identify the correct key to use in situations when multiple keys exist; the extension specifies the public key to be used to verify the signature on the CRL.

For general guidelines on setting the authority key identifier extension in CRLs, see "authorityKeyIdentifier".

Figure 7-2 shows how configurable parameters for the AuthorityKeyIdentifier rule are displayed in the CMS window.

Figure 7-2    Parameters defined in the AuthorityKeyIdentifier rule

The configuration shown in Figure 7-2 specifies that the server should not set the authority key identifier extension in CRLs.

Table 7-2 describes these parameters.

Table 7-2    Description of parameters defined in the AuthorityKeyIdentifierExt rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the authority key identifier extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).

CRLNumber Rule

---

The CRLNumber rule enables you to configure a Certificate Manager to set the CRL Number Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. This extension specifies a monotonically increasing sequence number for each CRL issued by a CA, allowing CRL users to easily determine when a particular CRL supersedes another CRL.

For general guidelines on setting the CRL number extension in CRLs, see "CRLNumber".

Figure 7-3 shows how the configurable parameters for the CRLNumber rule are displayed in the CMS window.

Figure 7-3    Parameters defined in the CRLNumber rule

The configuration shown in Figure 7-3 specifies that the server should not set the CRL number extension in CRLs.

Table 7-3 describes these parameters.

Table 7-3    Description of parameters defined in the CRLNumber rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the CRL number extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).

CRLReason Rule

---

The CRLReason rule enables you to configure a Certificate Manager to set the CRL ReasonCode Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRL entries. The extension is used to identify the reason for the revocation of a certificate included in the CRL.

For general guidelines on setting the CRL reason code in CRL entries, see "reasonCode".

The revocation reasons defined by the standard are listed in Table 7-4.

Table 7-4    Certificate revocation reasons  

Code	Reason
0	unspecified
1	keyCompromise
2	cACompromise
3	affiliationChanged
4	superseded
5	cessationOfOperation
6	certificateHold
8	removeFromCRL

Figure 7-4 shows how the configurable parameters for the CRLReason rule are displayed in the CMS window.

Figure 7-4    Parameters defined in the CRLReason rule

The configuration shown in Figure 7-4 specifies that the server should set the CRL reason code extension in CRL entries.

Table 7-5 describes these parameters.

Table 7-5    Description of parameters defined in the CRLReason rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule (default). Uncheck the box to disable the rule. If you enable the rule and set the remaining parameters correctly, the server sets the CRL number extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).

HoldInstruction Rule

---

The HoldInstruction rule enables you to configure a Certificate Manager to set the CRL Hold Instruction Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is a non-critical CRL entry extension that is used to specify a registered instruction identifier—the identifier indicates what action the validating application should take when it encounters a certificate that has been placed on hold.

For general guidelines on setting the CRL hold instruction code in CRL entries, see "holdInstructionCode".

Figure 7-5 shows how the configurable parameters for the HoldInstruction rule are displayed in the CMS window.

Figure 7-5    Parameters defined in the HoldInstruction rule

The configuration shown in Figure 7-5 specifies that the server should not set the hold instruction extension in CRL entries.

Table 7-6 describes these parameters.

Table 7-6    Description of parameters defined in the HoldInstruction rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the Hold Instruction extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).
instruction	Specifies the action a validating application must take when it encounters a certificate that has been put on hold. Permissible values: none, callissuer, or reject. none specifies that the validating application need not do anything; the PKIX standard says that this is semantically equivalent to the absence of a holdInstructionCode (default). callissuer specifies that the validating application must call the CA that has issued the certificate or reject the certificate. reject specifies that the validating application must reject the certificate on hold. Example: none

InvalidityDate Rule

---

The InvalidityDate rule enables you to configure a Certificate Manager to set the Invalidity Date Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is a non-critical CRL entry extension that is used to specify the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid.

For general guidelines on setting the invalidity date extension in CRL entries, see "invalidityDate".

Figure 7-6 shows how the configurable parameters for the InvalidityDate rule are displayed in the CMS window.

Figure 7-6    Parameters defined in the InvalidityDate rule

The configuration shown in Figure 7-6 specifies that the server should not set the invalidity date extension in CRL entries.

Table 7-7 describes these parameters.

Table 7-7    Description of parameters defined in the InvalidityDate rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the Invalidity Date extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).

IssuerAlternativeName Rule

---

The IssuerAlternativeName rule enables you to configure a Certificate Manager to set the Issuer Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. This extension enables binding of or associating alternative identities, such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI), with the issuer of the CRL.

The IssuerAlternativeName rule enables you to associate the following identities with a CRL issuer, by including them in the extension:

• An rfc822Name

• A DNS name

• A directory name

• A uniform resource indicator (URI)

• An IP address

• An object identifier (OID)

For general guidelines on setting the issuer alternative name extension in CRLs, see "issuerAltName".

Figure 7-7 shows how configurable parameters for the IssuerAlternativeName rule are displayed in the CMS window.

Figure 7-7    Parameters defined in the IssuerAlternativeName rule

The configuration shown in Figure 7-7 specifies that the server should not set the issuing point extension in CRLs.

Table 7-8 describes these parameters.

Table 7-8    Description of parameters defined in the IssuerAlternativeName rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the issuer alternative name extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical. Uncheck the box if you want the server to mark the extension noncritical (default).
numNames	Specifies the total number of alternative names or identities permitted in the extension. Note that each name has a set of configuration parameters— nameType and name—and you must specify appropriate values for each of those parameters; otherwise, the policy rule will return an error. You can change the total number of identities by changing the value specified in this field; there's no restriction on the total number of identities you can include in the extension. Each set of configuration parameters is distinguished by <n>, which is an integer derived from the value you assign in this field. For example, if you set the numNames parameter to 2, <n> would be 0 and 1. Permissible values: 0 or n. 0 specifies that no identities can be contained in the extension. n specifies the total number of identities to be included in the extension; it must be an integer greater than zero. The default value is 3. Example: 1
nameType<n>	Specifies the general-name type. Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName. Select rfc822Name if the name is an Internet mail address. Select directoryName if the name is an X.500 directory name. Select dNSName if the name is a DNS name. Select ediPartyName if the name is a EDI party name. Select URL if the name is a uniform resource identifier (default). Select iPAddress if the name is an IP address. Select OID if the name is an object identifier. Select otherName if the name is in any other name form. Example: URL
name<n>	Specifies the general-name value. Permissible values: Depends on the name type specified in the nameType<n> field. If the type is rfc822Name, the value must be a valid Internet mail address in the local-part@domain format; see the definition of an rfc822Name as defined in RFC 822 (http://www.ietf.org/rfc/rfc0822.txt). You may use upper and lower case letters in the mail address; no significance is attached to the case. For example, testCA@siroe.com. If the type is directoryName, the value must be a string form of X.500 name, similar to the subject name in a certificate, in the RFC 2253 syntax (see http://www.ietf.org/rfc/rfc2253.txt). Note that RFC 2253 replaces RFC 1779. For example, CN=CACentral,OU=Research Dept,O=Siroe Corp,C=US. If the type is dNSName, the value must be a valid domain name in the preferred-name syntax as specified in RFC 1034 (http://www.ietf.org/rfc/rfc1034.txt). You may use upper and lower case letters in the domain name; no significance is attached to the case. Do not use the string " " for the DNS name. Also don't use the DNS representation for Internet mail addresses; such identities should be encoded as rfc822Name. For example, testCA.siroe.com.
	If the type is ediPartyName, the name must be an IA5String. For example, Siroe Corporation. If the type is URL, the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules specified in RFC 1738 (http://www.ietf.org/rfc/rfc1738.txt). That is, the name must include both a scheme (for example, http) and a fully qualified domain name or IP address of the host. For example, http://testCA.siroe.com. If the type is iPAddress, the value must be a valid IP address specified in dot-separated numeric component notation. The syntax for specifying the IP address is as follows: For IP version 4 (IPv4), the address should be in the form specified in RFC 791 (http://www.ietf.org/rfc/rfc0791.txt). IPv4 address must be in the n.n.n.n format; for example, 128.21.39.40. IPv4 address with netmask must be in the n.n.n.n,m.m.m.m format. For example, 128.21.39.40,255.255.255.00. For IP version 6 (IPv6), the address should be in the form described in RFC 1884 (http://www.ietf.org/rfc/rfc1884.txt), with netmask separated by a comma. Examples of IPv6 addresses with no netmask are 0:0:0:0:0:0:13.1.68.3 and FF01::43. Examples of IPv6 addresses with netmask are 0:0:0:0:0:0:13.1.68.3,FFFF: FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0 and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000. If the type is OID, the value must be a unique, valid OID specified in the dot-separated numeric component notation. Although you can invent your own OIDs for the purposes of evaluating and testing this server, in a production environment, you should comply with the ISO rules for defining OIDs and for registering subtrees of IDs. See Appendix B "Object Identifiersfor information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99. If the type is otherName, the name must be must be the absolute path to the file that contains the general name in its base-64 encoded format. For example, C:\netscape\server4\extn\ian\othername.txt.

IssuingDistributionPoint Rule

---

The IssuingDistributionPoint rule enables you to configure a Certificate Manager to set the Issuing Distribution Point Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The CRL issuing point extension enables you to specify a pointer to a particular CRL and to include additional information about the CRL at that location—whether it covers revocation of end-entity certificates only, CA certificates only, or revoked certificates that have a limited set of reason codes.

By default, the pointer can be in either of these forms:

• The name of the X.500 directory that stores the CRL

• The URI to the location that contains the CRL

Optionally, each issuing point may contain a set of reason flags, indicating what revocation reasons are covered by the CRL at the specified location. Note that you can modify the rule to support any name form by making the appropriate changes to the sample code provided for this purpose. The sample code is located here:

<server_root>/cms_sdk/cms_jdk/samples/CRLs/IssuingDistributionPoint

For general guidelines on setting the issuing distribution point extension in CRLs, see "issuingDistributionPoint".

Figure 7-8 shows how configurable parameters for the IssuingDistributionPoint rule are displayed in the CMS window.

Figure 7-8    Parameters defined in the IssuingDistributionPoint rule

The configuration shown in Figure 7-8 specifies that the server should not set the issuing point extension in CRLs.

Table 7-9 describes these parameters.

Table 7-9    Description of parameters defined in the IssuingDistributionPoint rule  

Parameter	Description
enable	Specifies whether the rule is enabled or disabled. Check the box to enable the rule. Uncheck the box to disable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the issuing distribution point extension in CRLs. If you disable the rule, the server does not add the extension to CRLs; it ignores the values in the remaining fields.
critical	Specifies whether the extension should be marked critical or noncritical in CRLs issued by the server. Check the box if you want the server to mark the extension critical (default). Uncheck the box if you want the server to mark the extension noncritical.
pointType	Specifies the type (for example, URI) of the issuing distribution point. Permissible values: By default, DirectoryName and URI. DirectoryName specifies that the type is an X.500 Directory Name (that is, the CRL is stored in an X.500 directory). URI specifies that the type is a uniform resource indicator (this provides a pointer to the location for the most current CRL issued by this CA). Example: URI
pointName	Specifies the name of the issuing distribution point. The name of the distribution point can be in any of the following formats: Permissible values: Depends on the value specified for the pointType parameter. If the pointType attribute is set to DirectoryName, the name must be an X.500 Name (in RFC1779 syntax). If the pointType attribute is set to URI, the name must be a URI; the URI must be an absolute pathname and must specify the host. Example: If the name is a URI, it would look similar to this: http://testCA.siroe.com/get/your/crls/here/ If the name is an X.500 Directory Name, it would look similar to this: CN=CRLCentral,OU=Research Dept,O=Siroe Corp,C=US (Note that the CRL may be stored in the directory entry corresponding to the CRL issuing point, which may be different than the directory entry of the CA.)
onlySomeReasons	Specifies the reason codes associated with the distribution point. Permissible values: A combination of reason codes—unspecified, keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, and removeFromCRL—separated by commas. Leave field blank if the distribution point contains revoked certificates with all reason codes or if you don't want to set this field (default). Example: unspecified, keyCompromise, cessationOfOperation
onlyContainsCACerts	Specifies whether the distribution point contains only revoked CA certificates. Check the box if the distribution point contains CA certificates only. Uncheck the box if the distribution point contains all types of revoked certificates (default).
onlyContainsUserCerts	Specifies whether the distribution point contains only revoked user certificates. Check the box if the distribution point contains user certificates only. Uncheck the box if the distribution point contains all types of certificates (default).
indirectCRL	Specifies whether the distribution point contains an indirect CRL. Check the box if the distribution point contains an indirect CRL. Uncheck the box if the distribution point doesn't contain an indirect CRL (default).