Previous     Contents     Index     Next     
iPlanet Certificate Management System Plug-ins Guide



Chapter 4   Certificate Extension Plug-in Modules


iPlanet Certificate Management System (CMS) comes with a set of policy plug-in modules that enable you to add X.509 certificate extensions to certificates the server issues. This chapter explains those modules—it lists and briefly describes the modules that are installed with a Certificate Manager and Registration Manager, and then explains each one in detail.

The chapter has the following sections:



Overview of Extension-Specific Policy Modules

To enable you to add standard and private extensions to end-entity certificates, Certificate Management System provides a set of policy plug-in modules; each module enables you to add a particular extension to a certificate request. Plug-in modules are implemented as Java classes and are registered in the CMS policy framework. The Policy Plugin Registration tab of the CMS window (Figure 4-1) lists all the modules that are registered with a CMS instance.

Note that the name of the Java class for a policy plug-in module is in this format:

com.netscape.certsrv.policy.<plugin_name>

where <plugin_name> is the name of a plug-in module. For example, the Java class for the AuthorityKeyIdentifierExt module would be:

com.netscape.certsrv.policy.AuthorityKeyIdentifierExt

When deciding whether to add any of the X.509 v3 certificate extensions, keep in mind that not all applications support X.509 v3 extensions. Among the applications that do support extensions, not all applications will recognize every extension. For general guidelines on using extensions in certificates, see Appendix C "Certificate and CRL Extensions."

Figure 4-1    Extension policy modules registered with a Certificate Manager


Table 4-1 lists extension-specific policy modules that are installed with a Certificate Manager. A Registration Manager installation also includes all the modules, expect for the ones noted below:

  • AuthorityKeyIdentifierExt

  • BasicConstraintsExt

  • NameConstraintsExt

  • PolicyConstraintsExt

  • PolicyMappingsExt

You can use these modules to configure a Certificate Manager and Registration Manager to add extensions to certificates. Both subsystems add extensions to a certificate request when it undergoes policy processing (see section "Policy Processor" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide). Keep in mind that the changes made to a request by a Registration Manager may be overwritten by a Certificate Manager when it subjects the request to its own policy checks.


Table 4-1    Default extension-specific policy plug-in modules  

Plug-in module

Function

AuthInfoAccessExt  

Adds the Authority Information Access extension to certificates. For details, see "AuthInfoAccessExt Plug-in Module".  

AuthorityKeyIdentifierExt  

Adds the Authority Key Identifier extension to certificates. For details, see "AuthorityKeyIdentifierExt Plug-in Module".  

BasicConstraintsExt  

Adds the Basic Constraints extension to certificates. For details, see "BasicConstraintsExt Plug-in Module".  

CertificatePoliciesExt  

Adds the Certificate Policies extension to certificates. For details, see "CertificatePoliciesExt Plug-in Module".  

CertificateRenewalWindowExt  

Adds the Certificate Renewal Window extension to certificates. For details, see "CertificateRenewalWindowExt Plug-in Module".  

CertificateScopeOfUseExt  

Adds the Certificate Scope of Use extension to certificates. For details, see "CertificateScopeOfUseExt Plug-in Module".  

CRLDistributionPointsExt  

Adds the CRL Distribution Points extension to certificates. For details, see "CRLDistributionPointsExt Plug-in Module".  

ExtendedKeyUsageExt  

Adds the Extended Key Usage extension to certificates. For details, see "ExtendedKeyUsageExt Plug-in Module".  

GenericASN1Ext  

Adds ASN.1 type custom extension to certificates. For details, see "GenericASN1Ext Plug-in Module".  

IssuerAltNameExt  

Adds the Issuer Alternative Name extension to certificates. For details, see "IssuerAltNameExt Plug-in Module".  

KeyUsageExt  

Adds the Key Usage extension to certificates. For details, see "KeyUsageExt Plug-in Module".  

NameConstraintsExt  

Adds the Name Constraints extension to certificates. For details, see "NameConstraintsExt Plug-in Module".  

NSCCommentExt  

Adds the Netscape Certificate Comment extension to certificates. For details, see "NSCCommentExt Plug-in Module".  

NSCertTypeExt  

Adds the Netscape Certificate Type extension to certificates. For details, see "NSCertTypeExt Plug-in Module".  

OCSPNoCheckExt  

Adds the OCSP No Check extension to certificates. For details, see "OCSPNoCheckExt Plug-in Module".  

PolicyConstraintsExt  

Adds the Policy Constraints extension to certificates. For details, see "PolicyConstraintsExt Plug-in Module".  

PolicyMappingsExt  

Adds the Policy Mappings extension to certificates. For details, see "PolicyMappingsExt Plug-in Module".  

PrivateKeyUsagePeriodExt  

Adds the Private Key Usage Period extension to certificates. For details, see "PrivateKeyUsagePeriodExt Plug-in Module".  

RemoveBasicConstraintsExt  

Detects and removes the Basic Constraints extension in certificate requests. For details, see "RemoveBasicConstraintsExt Plug-in Module".  

SubjectAltNameExt  

Adds the Subject Alternative Name extension to certificates. For details, see "SubjectAltNameExt Plug-in Module".  

SubjectDirectoryAttributesExt  

Adds a Subject Directory Attributes extension to certificates. For details, see "SubjectDirectoryAttributesExt Plug-in Module".  

SubjectKeyIdentifierExt  

Adds the Subject Key Identifier extension to certificates. For details, see "SubjectKeyIdentifierExt Plug-in Module".  

As indicated in Table 4-1, Certificate Management System enables you to add almost all of the extensions defined in the PKIX standard RFC 2459 (http://www.ietf.org/rfc/rfc2459.txt). All modules have three features in common, enabling you to specify these:

  • Whether to add the extension to certificates.

  • The certificates to which the extension is to be added.

  • Whether to mark the extension critical or noncritical.

By default, only noncritical extensions are added to certificates. This ensures that the resulting certificates can be used with all clients. If you add a critical extension, the resulting certificate can only be used by clients that support that extension.

Additionally, the server also provides a module for adding any custom, ASN.1 type extensions. If you determine that the default policy modules do not meet your requirements entirely, you can develop a custom module using CMS SDK. It is available in the form of Java Docs at this location:

<server_root>/cms_sdk/cms_jdk/javadocs

For general guidelines on developing custom policy modules and adding them to the CMS policy framework, take a look at the samples installed at these locations:

<server_root>/cms_sdk/cms_jdk/samples/policies

For instructions to configure a Certificate Manager and Registration Manager to use one or more of the policy modules, see section "Configuring Policy Rules for a Subsystem" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.



AuthInfoAccessExt Plug-in Module


The AuthInfoAccessExt plug-in module implements the authority information access extension policy. This policy enables you to configure Certificate Management System to add the Authority Information Access Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension specifies how an application validating a certificate can access information, such as on-line validation services and CA policy statements, about the CA that has issued the certificate in which the extension appears. Note that this extension should not be used to point directly to the CRL location maintained by a CA; the CRL Distribution Points extension explained in "CRLDistributionPointsExt Plug-in Module" allows you to reference to CRL locations.

The PKIX standard recommends that you may include the authority information access extension in end-entity and CA certificates and that the extension be marked noncritical. For general guidelines on setting the authority information access extension, see "authorityInfoAccess".

The authority information access extension policy in Certificate Management System allows you to set the authority information access extension as defined in its X.509 definition. The policy enables you to specify any number of access points for CA information. For each access point, you can specify the access method, actual location that contains the additional information about the CA, and the mechanism for retrieving the information. The location can be specified in any of the following general-name forms: an rfc822name, a directory name, a DNS name, an EDI party name, a uniform resource indicator (URI), an IP address, an object identifier (OID), and any other name.

By default, the policy supports three access methods:

  • caIssuers (this method is also identified by its OID, 1.3.6.1.5.5.7.48.2).

    As specified in the PKIX standard, you should use the caIssuers method when the additional information is a list of parent CAs or CAs that have issued certificates superior to the CA that issued the certificate containing the extension. The certificate-using application may use the list of parent CAs referenced by the extension to determine the certification path and to check whether the path terminates at a point trusted by the certificate user.

    When you use the caIssuers method, the access location referenced in the extension must take any of the following general-name forms:

    • Uniform resource identifier (URI) if the information is available via HTTP, FTP, or LDAP.

    • An X.500 directory name if the information is available via the directory access protocol (DAP).

    • An rfc822Name if the information is available via electronic mail.

  • ocsp (this method is also identified by its OID, 1.3.6.1.5.5.7.48.1).

    The ocsp method indicates to the certificate-using client that it must use the OCSP protocol to access the location that contains additional information about the CA that has issued the certificate. You should use the ocsp method when you want to reference to the online validation authority that maintains the revocation status of certificates issued by the CA.

    When you use the ocsp method, the access location referenced in the extension must be a uniform resource indicator (URI); this means, the location type must be URL and the location value must be the complete URL (including the port number) at which the online validation authority for the CA is listening for OCSP requests from OCSP-compliant clients.

  • renewal (this method is also identified by its OID, 2.16.840.1.113730.16.1)

    The renewal method works with the automated-certificate-renewal feature built into Netscape Personal Security Manager. When you use this method, the access location referenced in the extension must be a URI. For details, check the Personal Security Manager Deployment Guide available at: http://docs.iplanet.com/docs/manuals/psm.html

The built-in support for the ocsp access method and a URI value for the access location in the extension conform to the profile defined in RFC 2560 (see http://www.ietf.org/rfc/rfc2560.txt) for CAs that support the OCSP service. For details about OCSP support in Certificate Management System, see Chapter 21, "Setting Up an OCSP Responder" of CMS Installation and Setup Guide.

If you configure a Certificate Manager to publish CRLs to an OCSP responder and want to include the authority information access extension referencing to the responder, you should configure an instance of this policy as follows: access method is set to ocsp, name type is set to URI, and name value is set to the URL at which the OCSP responder listens to OCSP requests. This way, OCSP-compliant applications can verify the revocation status of certificates issued by the Certificate Manager by accessing the validation authority using the OCSP method.

During installation, Certificate Management System automatically creates an instance of the authority information access extension policy. See "AuthInfoAccessExt Rule".


Note The CMS configuration file (CMS.cfg) includes a parameter named jss.ocspcheck.enable, which enables you to specify whether a CMS manager should use Online Certificate Status Protocol (OCSP) to verify the revocation status of the certificate it receives as a part of SSL client or server authentication (from clients or servers it makes connections with). If you change the value of this parameter to true, the CMS manager reads the Authority Information Access extension in the certificate and verifies the revocation status of the certificate from the OCSP responder specified in the extension.



Configuration Parameters of AuthInfoAccessExt

In the CMS configuration file, the AuthInfoAccessExt module is identified as
<subsystem>.Policy.impl.AuthInfoAccessExt.class=
com.netscape.certsrv.policy.AuthInfoAccessExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as AuthInfoAccessExt. Figure 4-2 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-2    Parameters defined in the AuthInfoAccessExt module


The configuration shown in Figure 4-2 creates a policy rule named AuthInfoAccessExtForClientCert, which enforces a rule that the server should add the authority information access extension to client certificates. The extension indicates that the online validation service (or the OSCSP responder) for the CA that has issued these certificates is at this URL:

http://ocspResponder.siroe.com:8000

The extension is marked noncritical (to comply with the PKIX recommendation).

Table 4-2 gives details about the configurable parameters defined in the AuthInfoAccessExt module.


Table 4-2    Description of parameters defined in the AuthInfoAccessExt module  

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 adds the authority information access extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numADs  

Specifies the total number of access locations to be contained or allowed in the extension.

By default, this field is set to 3 and the UI shows fields for configuring three locations. You can change the total number of locations by changing the value assigned to this parameter; there's no restriction on the total number of locations you can include in the extension.

Note that each location has its own set of configuration parameters and you must specify appropriate values for each of those parameters; otherwise the policy rule will return an error. 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 numADs parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no locations can be contained in the extension.

  • n specifies the total number of locations to be included in the extension; it must be an integer greater than zero. The default value is 3.

Example: 2  

ad<n>_method  

Specifies the access method for retrieving additional information about the CA that has issued the certificate in which the extension appears.

Permissible values:

  • ocsp (or 1.3.6.1.5.5.7.48.1).

  • caIssuers (or 1.3.6.1.5.5.7.48.2).

  • renewal (or 2.16.840.1.113730.16.1)

Example 1: ocsp

Example 2: 1.3.6.1.5.5.7.48.1  

ad<n>_location_type  

Specifies the general-name type for the location that contains additional information about the CA that has issued the certificate in which this extension appears.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName.

  • Select rfc822Name if the location is an Internet mail address.

  • Select directoryName if the location is an X.500 directory name.

  • Select dNSName if the location is a DNS name.

  • Select ediPartyName if the location is a EDI party name.

  • Select URL if the location is a uniform resource identifier (default).

  • Select iPAddress if the location is an IP address.

  • Select OID if the location is an object identifier.

  • Select otherName if the location is in any other name form.

Example: URL  

ad<n>_location  

Specifies the address or location to get additional information about the CA that has issued the certificate in which this extension appears.

Permissible values: Depends on the location type you specified in the ad<n>_location_type field.

  • If you selected 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, ocspResponder@siroe.com.

  • If you selected 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=corpDirectory, OU=IS, O=Siroe.com, C=US.

  • If you selected 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, ocspResponder.siroe.com.

  • If you selected ediPartyName, the value must be an IA5String. For example, Siroe Corporation.

 

 
  • If you selected 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://ocspResponder.siroe.com:8000

  • If you selected 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 you selected OID, the value must be a unique, valid OID specified in 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 Identifiers" for information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99.

  • If you selected otherName, the value must be the absolute path to the file containing the base-64 encoded string of the location. For example, /usr/netscape/server4/ext/aia/othername.txt.

 


AuthInfoAccessExt Rule

The rule named AuthInfoAccessExt is an instance of the AuthInfoAccessExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled.

  • The predicate expression (predicate=HTTP_PARAMS.certType==client) ensures that the policy is to be applied to client certificate requests processed by the server.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The total number of access locations to be contained or allowed in the extension is set to 1 (numADs=1).

  • The access method for retrieving additional information about the CA that has issued the certificate in which the extension appears is set to OCSP (ad0_method=ocsp).

  • The general-name type for the location that contains additional information about the CA that has issued the certificate in which the extension appears is set to URL (ad0_location_type=URL).

  • The address or location to get additional information about the CA that has issued the certificate in which this extension appears is left blank for you to enter the URL at which the OCSP responder will service requests from OCSP-compliant clients.

Note that if you installed the Certificate Manager with it's built-in OCSP service enabled, the policy rule will be enabled and the address location (ad0_location=) will be pointed to the Certificate Manager's nonSSL end-entity port. For example, if the nonSSL end-entity port of your Certificate Manager is 80, the URL would look like this: http://ocspResponder.siroe.com:80/ocsp

For details on individual parameters defined in the rule, see Table 4-2. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



AuthorityKeyIdentifierExt Plug-in Module


The AuthorityKeyIdentifierExt plug-in module implements the authority key identifier extension policy. This policy enables you to configure Certificate Management System to add the Authority Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to identify the public key that corresponds to the private key used by a CA to sign certificates.

You should consider adding this extension to all certificates, especially CA certificates, issued by Certificate Management System. The reason is, 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 due to multiple concurrent key pairs or due to key changeover). In these cases, the CA ends up with more than one distinct key. 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 certificate.

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

The authority key identifier extension policy in Certificate Management System allows setting of the authority key identifier extension as defined in its X.509 definition with key identifiers. The policy enables you to specify what is to be done if the CA certificate does not have a subject key identifier extension—whether to use the a SHA-1 hash of the CA's subject public key information (carries the public key and identifies the algorithm with which the key is used) or skip adding the authority key identifier extension itself. For information on setting the subject key identifier extension in certificates, see "SubjectKeyIdentifierExt Plug-in Module".

Note that PKIX and Federal PKI standards recommend against the use of authorityCertIssuer and authorityCertSerialNumber fields of the X.509 definition.

If enabled, the policy does the following:

  • Sets the authority key identifier extension in certificates using the CA's key identifier in the CA's subject key identifier extension, if it exists. In the absence of a subject key identifier extension, the policy does either of the following (as specified by the configuration):

    • Uses the SHA-1 hash of the CA's subject public key information as the key identifier. This option is compatible with Netscape Communicator when the CA does not have a subject public key identifier extension.

    • Does not set the authority key identifier extension.

  • Adds a authority key identifier extension to an enrollment request if the extension does not already exist. If the extension exists in the request, for example from a CRMF request, the policy replaces the extension. In case of manual enrollments, after an agent approves the enrollment request, the policy accepts any authority key identifier extension that is already there.

During installation, Certificate Management System automatically creates an instance of the authority key identifier extension policy. See "AuthorityKeyIdentifierExt Rule".


Configuration Parameters of AuthorityKeyIdentifierExt

In the CMS configuration file, the AuthorityKeyIdentifierExt module is identified as ca.Policy.impl.AuthorityKeyIdentifierExt.class=
com.netscape.certsrv.policy.AuthorityKeyIdentifierExt.

In the CMS window, the module is identified as AuthorityKeyIdentifierExt. Figure 4-3 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-3    Parameters defined in the AuthorityKeyIdentifierExt module


The configuration shown in Figure 4-3 creates a policy rule named AuthKeyIDExtForCACert, which enforces a rule that the server should set the authority key identifier extension in all CA certificates.

Table 4-3 gives details about each of these parameters.


Table 4-3    Description of parameters defined in the AuthorityKeyIdentifierExt module  

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 adds the authority key identifier extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

AltKeyIdType  

Specifies what should be done if the CA certificate does not have a Subject Key Identifier extension.

Permissible values: SpkiSHA1 or None.

  • Select SpkiSHA1 if you want the server to use a SHA-1 hash of the CA's subject public key information (default).

  • Select None if you don't want the server to set the authority key identifier extension in certificates.

Example: SpkiSHA1  


AuthorityKeyIdentifierExt Rule

The rule named AuthorityKeyIdentifierExt is an instance of the AuthorityKeyIdentifierExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is left blank so that the extension gets added to all certificates the server issues.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The rule specifies that a SHA-1 hash of the CA's subject public key info be used if the CA certificate does not have a Subject Key Identifier extension (AltKeyIdType=SpkiSHA1).

For details on individual parameters defined in the rule, see Table 4-3. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



BasicConstraintsExt Plug-in Module


The BasicConstraintsExt plug-in module implements the basic constraints extension policy. This policy enables you to configure Certificate Management System to add the Basic Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in certificates. The extension identifies whether the Certificate Manager is a CA. In addition, the extension is also used during the certificate chain verification process to identify CA certificates and to apply certificate chain-path length constraints.

You should consider adding this extension to all CA certificates (root as well as subordinate) issued by Certificate Management System. The current PKIX standard requires that this extension be marked critical and that it appear in all CA certificates. The standard also recommends that the extension should not appear in end-entity certificates. For general guidelines on setting the basic constraints extension, see "basicConstraints".

Because the basic constraints extension is a critical extension and is used by applications to determine the path length during certificate validation to chain up to the trusted CA, it's important that you set this extension correctly.

Also note that when a user submits a certificate request using the manual-enrollment method, the basic constraints extension is set on that request as per the configured policy, and then the request is queued for agent approval. When an agent approves the request, it is subjected to the configured policy again. If there's a change in the configuration of the basic constraints extension, the server may reject the agent-approved request. For the server to approve the request, the user will have to resubmit the request.

During installation, Certificate Management System automatically creates an instance of the basic constraints extension policy. See "BasicConstraintsExt Rule".


Configuration Parameters of BasicConstraintsExt

In the CMS configuration file, the BasicConstraintsExt module is identified as
ca.Policy.impl.BasicConstraintsExt.class=com.netscape.certsrv.
policy.BasicConstraintsExt.

In the CMS window, the module is identified as BasicConstraintsExt. Figure 4-4 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-4    Parameters defined in the BasicConstraintsExt module


The configuration shown in Figure 4-4 creates a policy rule named BasicConsExtForCACert, which enforces a rule that the server should set the basic constraints extension in all CA certificates.

Table 4-4 gives details about each of these parameters.


Table 4-4    Description of parameters defined in the BasicConstraintsExt module  

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 adds the basic constraints extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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.  

isCA  

Specifies whether the certificate subject is a CA. If you select the option, the server checks the maxPathLen parameter and sets the specified path length in the certificate. If you deselect the option, the server treats the certificate subject as a non-CA and ignores the value specified for the maxPathLen parameter.  

maxPathLen  

Specifies the path length, the maximum number of CA certificates that may be chained below (subordinate to) the subordinate CA certificate being issued. Note that the path length you specify affects the number of CA certificates to be used during certificate validation. The chain starts with the end-entity certificate being validated and moving up the chain.

The maxPathLen parameter has no effect if the extension is set in end-entity certificates.

Permissible values: 0 or n. Make sure that the value you choose is less than the path length specified in the Basic Constraints extension of the CA signing certificate (owned by the CA that will issue these certificates).

  • 0 specifies that no subordinate CA certificates are allowed below the subordinate CA certificate being issued—that is, only an end-entity certificate may follow in the path.

  • n must be an integer greater than zero. It specifies at the most n subordinate CA certificates are allowed below the subordinate CA certificate being used.

  • If you leave the field blank, the path length defaults to a value that is determined by the path length set on the Basic Constraints extension in the issuer's certificate. If the issuer's path length is unlimited, the path length in the subordinate CA certificate will also be unlimited. If the issuer's path length is an integer greater than zero, the path length in the subordinate CA certificate will be set to a value that's one less than the issuer's path length; for example, if the issuer's path length is 4, the path length in the subordinate CA certificate will be set to 3.

Example: 2  


BasicConstraintsExt Rule

The rule named BasicConstraintsExt is an instance of the BasicConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ca) so that the extension gets added to CA certificates only.

  • The extension is marked critical to comply with the PKIX recommendation.

  • The path length field (maxPathLen) is left blank so that it defaults to a value that is determined by the path length set on the Basic Constraints extension in the issuer's certificate.

For details on individual parameters defined in the rule, see Table 4-4. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



CertificatePoliciesExt Plug-in Module


The CertificatePoliciesExt plug-in module implements the certificate policies extension policy. This policy enables you to configure Certificate Management System to add the Certificate Policies Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in certificates. The extension contains a sequence of one or more policy statements, each indicating the policy under which the certificate has been issued and identifying the purposes for which the certificate may be used. Presence of this extension in certificates enables an application with specific policy requirements to compare its list of policies to the ones contained in a certificate during its validation; typically, such applications will have a list of policies (which they will accept) and compare the policies in the certificate to their list as a part validating the certificate.

To promote interoperatability, the PKIX standard recommends that the policy statements or information terms should be included in certificates in the form of object identifiers (OIDs). For more information on OIDs, see Appendix B "Object Identifiers." This means, in order for the server to add this extension to any certificate it issues, you need to compose policy statements you want to include in the extension, define OIDs for these policy statements, and configure the server with these OIDs.

When determining whether to add this extension to certificates, keep in mind that if the extension exists in a certificate and if it is marked critical, the application validating the certificate must be able to interpret the extension (including the optional qualifiers, if any), or else it must reject the certificate. For general guidelines on setting the certificate policies extension, see "certificatePolicies".

The certificate policies extension policy in Certificate Management System enables you to set the extension with the following information:

  • The name of the your company or organization.

  • The OID assigned to the policy statement you want to include in the certificate.

  • A pointer (URI) to the published Certification Practice Statement (CPS).

    Any company deploying its own PKI should make a CPS available to anyone who may come across certificates issued by the CA deployed in the PKI. (The reason for this is people outside the company intranet may receive signed email messages from an employee.) To see an example of a CPS, check this site: http://people.netscape.com/shadow/cps.html

  • A textual user notice (which the application validating the certificate can interpret and display).

During installation, Certificate Management System automatically creates an instance of the certificate policies extension policy. See "CertificatePoliciesExt Rule".


Configuration Parameters of CertificatePoliciesExt

In the CMS configuration file, the CertificatePoliciesExt module is identified as <subsystem>.Policy.impl.CertificatePoliciesExt.class=
com.netscape.certsrv.policy.CertificatePoliciesExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as CertificatePoliciesExt. Figure 4-5 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-5    Parameters defined in the CertificatePoliciesExt module


The configuration shown in Figure 4-5 creates a policy rule named CertPoliciesExtForClientCert, which enforces a rule that the server should set the certificate policies extension in all client certificates.

Table 4-5 gives details about each of these parameters.


Table 4-5    Description of parameters defined in the CertificatePoliciesExt module  

Parameter

Description

enable  

Specifies whether the rule is enabled or disabled.

  • Check the box to enable the rule (default). If you enable the rule and set the remaining parameters correctly, the server adds the certificate policies extension to certificates specified by the predicate parameter.

  • Uncheck the box to disable the rule. If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

policyId  

Specifies the OID assigned to the policy statement you want to include in the extension. If you specify a valid OID, the server includes the OID in the extension.

The policyId, if specified, identifies by number a particular textual statement prepared by your organization (which is specified by the parameter named organizationName, listed next in this table). For example, it might identify the organization as Siroe Corporation and notice number 1.2.3.4.5.6.99. Typically, applications validating the certificate will have a notice file containing the current set of notices for your company; these application will interpret the number in the certificate by extracting the notice text that corresponds to the number from the file and display it to the relying party.

Permissible values: A unique, valid OID specified in dot-separated numeric component notation (see the example). 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 Identifiers"for information on allocating private OIDs.

Example: 2.16.840.1.113730.1.99  

organizationName  

Specifies the name of the organization that owns the OID or is the owner of the policy statement referenced by the OID.

Permissible values: The name of a company or its organizational unit.

Example: Siroe Corporation  

cpsURI  

Specifies the location where the Certification Practice Statement published by the CA (that has issued the certificate) can be found.

Permissible values: An IA5String value. The PKIX standard recommends that the pointer should be in the form of a URI.

Example: http://testCA.siroe.com/CPS_statement  

displayText  

Specifies the textual statement to be included in certificates; this parameter corresponds to the explicitText field of the user notice. If you want to embed a textual statement (for example, your company's legal notice) in certificates, then add that statement here. The text you enter here will be displayed to a relying party when the certificate is used or viewed.

Note that certain applications may not have the capability to display this text. Also, embedding a policy statement in a certificate increases its size.

If you specify values for both policyId and displayText parameters and if the application software cannot locate the notice text indicated by the policyId parameter, then it is supposed to display the embedded notice; otherwise, it's supposed to display the information specified by the policyId parameter. (This feature is application specific and Certificate Management System has no control over it.)

Permissible values: A string with up to 200 characters.

Example: SiroeCorp's CPS incorp. by reference liab. ltd.
(c)97 SiroeCorp  


CertificatePoliciesExt Rule

The policy rule named CertificatePoliciesExt is an instance of the CertificatePoliciesExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate field is left blank so that the extension gets added to all certificates.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • Other fields are left blank for you to enter the appropriate information.

For details on individual parameters defined in the rule, see Table 4-5. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter. For example, if you want to include different policy statements in different types of certificates, you should create multiple instances of the policy module and configure each instance with the appropriate policy OID and predicate expression.



CertificateRenewalWindowExt Plug-in Module


The CertificateRenewalWindowExt plug-in module implements the certificate renewal window extension policy. This policy enables you to configure Certificate Management System to add the Certificate Renewal Window Extension to certificates. The extension, which must be noncritical, aids in managing the life cycle of a certificate by specifying a process to follow for renewing a certificate and by defining a time window when automatic renewal of the certificate should be attempted.

Every certificate issued by Certificate Management System has a validity period beyond which it cannot be used. In order to continue to participate in the PKI-using system beyond this validity period, the entity owning the certificate must renew the certificate. Renewal of a certificate essentially means getting a new certificate for the existing key pair with a new validity time period (and updated attributes).

Once a certificate is issued, the owner of the certificate may attempt its renewal any time. To prevent certificate owners from renewing their certificates too often and thus reduce the overhead of processing new certificate requests, the CA can use a policy that restricts the time period when certificate renewal may occur. For example, the CA can use a policy that limits the renewal process to the last few weeks or days of validity of the certificate, thus defining a certificate renewal window. In general, the renewal window must be sufficient for the renewal to occur, but at the same time delay the renewal as long as possible to best utilize a certificate's life time.

The certificate-renewal process is often different than the enrollment process an entity uses to obtain the certificate; this is because the entity already owns a key pair that is associated with his or her identity. For example, in Certificate Management System, the certificate-renewal process for end users is different than the enrollment process they used to obtain the certificate. To renew their certificates, end users go to the certificate-renewal interface of Certificate Management System and submit their original certificates; for details, see section "Authentication of End Users During Certificate Renewal" in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

Because the renewal process requires end users to remember when their certificates expire and renew them before the expiry date, some clients provide built-in support for automated renewal. Inclusion of the certificate renewal window extension in certificates is useful in a PKI setup with such clients; such a setup eliminates the need for the owner of the certificate to manually submit a renewal request to the CA and install the renewed certificate. For example, assume you have deployed clients that can automatically submit certificate-renewal requests to Certificate Management System. If you issue certificates with the certificate renewal window extension to these clients, they can then read this extension for the renewal window and automatically get the certificate renewed from the CA during that window.

For a PKI setup without clients that can handle automated certificate renewals, Certificate Management System enables administrators to easily manage certificate renewals using the following features:

  • The renewal notification job, which reminds users to renew their certificates before they expire.

  • The renewal constraints policy, which determines whether expired certificates can be renewed; see "RenewalConstraints Plug-in Module".

  • The renewal validity constraints policy, which controls when users can renew their certificates and what should be the validity period in renewed certificates; see "RenewalValidityConstraints Plug-in Module".

Unlike some of the other policy modules, Certificate Management System does not create an instance of the certificate renewal window extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the CertificateScopeOfUseExt module and configure it. For instructions, see section "Step 4. Add New Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of CertificateRenewalWindowExt

In the CMS configuration file, the CertificateRenewalWindowExt module is identified as <subsystem>.Policy.impl.CertificateRenewalWindowExt.
class=com.netscape.certsrv.policy.CertificateRenewalWindowExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as CertificateRenewalWindowExt. Figure 4-6 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-6    Parameters defined in the CertificateRenewalWindowExt module


The configuration shown in Figure 4-6 creates a policy rule named CertRenewWindowExtForClientCert, which enforces a rule that the server should set the certificate renewal window extension in client certificates only; the renewal window starts 30 days before a certificate expires and ends with certificate expiration.

Table 4-6 gives details about each of these parameters.


Table 4-6    Description of parameters defined in the CertificateRenewalWindowExt module  

Parameter

Description

enable  

Specifies whether the rule is enabled or disabled.

  • Check the box to enable the rule (default). If you enable the rule and set the remaining parameters correctly, the server adds the certificate renewal window extension to certificates specified by the predicate parameter.

  • Uncheck the box to disable the rule. If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

relativeBeginTime  

Specifies the first time automatic renewal of certificate that contains the extension should be attempted.

Permissible values: 0 or n.

  • 0 specifies that the renewal window begins at the same time the certificate is issued; the beginTime field of the extension will be set to the time of certificate issuance.

  • n specifies a future time for certificate renewal; the beginTime field of the extension will be set to the specified time since certificate issuance. You can specify the time period in seconds, minutes, hours, days, or months. Use the following suffixes to indicate the time unit.
    s - seconds
    m - minutes
    h - hours
    D - days
    M - months
    For example, if you're issuing certificates with a validity period of two years and want the renewal window to begin a month before the certificates expire, and want to specify the interval in months, you would enter 23M in this field. To specify the same validity interval in seconds, you would set the value to 59616000s (23 months x 30 days x 24 hours x 60 minutes x 60 seconds).

Example: 23M  

relativeEndTime  

Specifies the last opportunity for automatic renewal of the certificate that contains this extension. Specifying a value for this parameter is optional; if you leave the field blank, the certificate-using application is expected to use the expiration date (notAfter value) in the certificate.

Permissible values: 0 or n.

  • 0 specifies that the renewal window ends at the same time the certificate expires; the endTime field of the extension will be set to the time the certificate expires.

  • n specifies a past or future time, in seconds, by which the certificate must be renewed; the endTime field of the extension will be set to the specified time since certificate issuance. You can specify the time period in seconds, minutes, hours, days, or months. Use the following suffixes to indicate the time unit.
    s - seconds
    m - minutes
    h - hours
    D - days
    M - months
    For example, if you're issuing certificates with a validity period of two years and want the renewal window to end a month after the certificates expire, and want to specify the interval in months, you would enter 25M in this field. On the other hand, if you want the renewal window to end 15 days before certificates expire, then you would set the value to 705D ((23 months x 30 days) + 15 days).
    Note that if you choose to extend the renewal window after the expiration date of the certificate itself, your CA must maintain appropriate status information about the certificate during that window in order to allow appropriate authentication in the renewal process. (Automatic renewal may take place after the certificate has expired, when it is not valid for other purposes.)

Example: 705D  



CertificateScopeOfUseExt Plug-in Module


The CertificateScopeOfUseExt plug-in module implements the certificate scope of use extension policy. This policy enables you to configure Certificate Management System to add the Certificate Scope of Use Extension to certificates. The extension enables you to specify a list of web sites that may request the use of a particular certificate for SSL client authentication, thus aiding certificate-using applications to select certificates to present to web sites and to control release of these certificates.

The SSL protocol provides a way for a client application to authenticate itself to a web site or server. SSL client authentication occurs upon request of the server, and proceeds by providing a certificate and a signature to the server. The client may have more than one certificate that could be used to perform this authentication. The SSL protocol provides a way for the server to indicate which certificate may be useful by listing issuing CAs in one of the SSL protocol messages.

By using a particular certificate for SSL client authentication, the client releases information about itself to the server. This information may include the name and key information contained in the certificate. It also releases the information that the client holds a certificate from a particular CA. This information may be of interest to the company running the server, for example to find users that have certificates from competing companies.

The certificate scope of use extension can be included in certificates to restrict the scope-of-use of the certificate for client authentication; the extension enables the certificate-using application to restrict the release of individual certificates to web sites requesting SSL client authentication.

The certificate scope of use extension policy in Certificate Management System enables you to include a list of name patterns that will match server DNS names where the certificate may be used. It's up to the certificate-using applications to use the values in this extension to filter the list of potential certificates to use for client authentication.

Unlike some of the other policy modules, Certificate Management System does not create an instance of the certificate scope of use extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the CertificateScopeOfUseExt module and configure it. For instructions, see section "Step 4. Add New Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of CertificateScopeOfUseExt

In the CMS configuration file, the CertificateScopeOfUseExt module is identified as <subsystem>.Policy.impl.CertificateScopeOfUseExt.class=
com.netscape.certsrv.policy.CertificateScopeOfUseExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as CertificateScopeOfUseExt. Figure 4-7 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-7    Parameters defined in the CertificateScopeOfUseExt module


The configuration shown in Figure 4-7 creates a policy rule named CertScopeOfUseExtForClientCert, which enforces a rule that the server should set the certificate scope of use extension in client certificates only.

Table 4-7 gives details about each of these parameters.


Table 4-7    Description of parameters defined in the CertificateScopeOfUseExt module  

Parameter

Description

enable  

Specifies whether the rule is enabled or disabled.

  • Check the box to enable the rule (default). If you enable the rule and set the remaining parameters correctly, the server adds the certificate scope of use extension to certificates specified by the predicate parameter.

  • Uncheck the box to disable the rule. If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numEntries  

Specifies the total number of sites to be contained or allowed in the extension.

By default, this field is set to 3 and the UI shows fields for configuring three sites. You can change the total number of sites by changing the value assigned to this parameter; there's no restriction on the total number of sites you can include in the extension.

Note that each site has its own set of configuration parameters and you must specify appropriate values for each of those parameters; otherwise the policy rule will return an error. 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 numEntries parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no sites can be contained in the extension.

  • n specifies the total number of sites to be included in the extension; it must be an integer greater than zero. The default is 3.

Example: 2  

entry<n>_name_type  

Specifies the general-name type for the site that you want to include in the extension.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName.

  • Select rfc822Name if the site is an Internet mail address.

  • Select directoryName if the site is an X.500 directory name.

  • Select dNSName if the site is a DNS name (default).

  • Select ediPartyName if the site is a EDI party name.

  • Select URL if the site is a uniform resource identifier.

  • Select iPAddress if the site is an IP address.

  • Select OID if the site is an object identifier.

  • Select otherName if the site is in any other name form.

Example: URL  

entry<n>_name  

Specifies the general-name value for the site you want to include in the extension.

Permissible values: Depends on the general-name type you selected in the entry<n>_name_type field.

  • If you selected 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, webSite@siroe.com.

  • If you selected 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=corpDirectory, OU=IS, O=Siroe.com, C=US.

  • If you selected 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, webSite.siroe.com.

 

 
  • If you selected ediPartyName, the value must be an IA5String. For example, Siroe Corporation.

  • If you selected URL, the value must be a non-relative URI, including both a scheme (for example, http) and a fully qualified domain name or IP address of the host. For example, http://webSite.siroe.com.

  • If you selected iPAddress, the value must be a valid IP address (IPv4 or IPv6) 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 you selected OID, the value must be a unique, valid OID specified in 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 Identifiers" for information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99.

  • If you selected otherName, the value must be the absolute path to the file that contains the base-64 encoded string for the site. For example, /usr/netscape/server4/ext/aia/othername.txt.

 

entry<n>_port_
number  

Specifies the port number.

Example: 8888  



CRLDistributionPointsExt Plug-in Module


The CRLDistributionPointsExt plug-in module implements the CRL distribution points extension policy. This policy enables you to configure Certificate Management System to add the CRL Distribution Points Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. This extension, when present in a certificate, identifies one or more locations from where the application that is validating the certificate can obtain the CRL information (to verify the revocation status of the certificate).

For general guidelines on setting the CRL distribution points extension in certificates, see "cRLDistributionPoints".

The CRL distribution points extension policy in Certificate Management System enables you to specify pointers to one or more CRL locations. The pointers can be in these forms: the name of the X.500 directory that stores the CRL, the URI to the location that contains the CRL, or both.

Note that in the current implementation, the policy supports only two name forms for distribution points, X.500 Directory Name and URI; URIs described in this document support two CRL retrieval mechanisms, LDAP-based and HTTP-based. Optionally, each distribution point may contain a set of reason flags, indicating what revocation reasons are covered by the CRL at that location. Also, the distribution point location can be relative to the location of the issuer. In this last case, the issuerName and issuerType parameters should be included to give the location of the issuer.

You can modify the policy to support any name form by making appropriate changes to the sample code provided for this purpose. The sample code is located here: <server_root>/cms_sdk/cms_jdk/samples/policies

During installation, Certificate Management System automatically creates an instance of the CRL distribution points extension policy. See "CRLDistributionPointsExt Rule".


Configuration Parameters of CRLDistributionPointsExt

In the CMS configuration file, the CRLDistributionPointsExt module is identified as <subsystem>.Policy.impl.CRLDistributionPointsExt.class=
com.netscape.certsrv.policy.CRLDistributionPointsExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as CRLDistributionPointsExt. Figure 4-8 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-8    Description of parameters defined in the CRLDistributionPointsExt module


The configuration shown in Figure 4-8 creates a policy rule named CRLDistPtsExtForRouterCert, which enforces a rule that the server should set the CRL distribution point extension in router certificates; the CRL location is a X.500 directory.

Table 4-8 gives details about each of these parameters.


Table 4-8    Description of parameters defined in the CRLDistributionPointsExt module  

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 adds the CRL distribution points extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==CEP-Request  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numPoints  

Specifies the total number of CRL distribution points to be contained or allowed in the extension.

By default, this field is set to 3 and the UI shows fields for configuring three distribution points. You can change the total number of distribution points by changing the value assigned to this parameter; there's no restriction on the total number of distribution points you can include in the extension.

Note that each distribution point has its own set of configuration parameters and you must specify appropriate values for each of those parameters; otherwise the policy rule will return an error. 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 numPoints parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no distribution points can be contained in the extension.

  • n specifies the total number of distribution points to be included in the extension; it must be an integer greater than zero. The default is 3.

Example: 2  

pointName<n>  

Specifies the name of the CRL distribution point.

Permissible values: Any supported name forms. By default, the name can be in any of the following formats:

  • An X.500 directory name in the RFC 2253 syntax (see http://www.ietf.org/rfc/rfc2253.txt); note that RFC 2253 replaces RFC 1779. For example, the name would look similar to the subject name in a certificate, like this: CN=CA Central, OU=Research Dept, O=Siroe Corp, C=US

  • A URI; for example, it would look similar to this:
    http://testCA.siroe.com:80

  • An RDN which specifies a location relative to the CRL Issuer. In this case, the value of the pointType attribute must be RelativeToIssuer.

 

pointType<n>  

Specifies the type of the CRL distribution point.

Permissible values: DirectoryName, URI, or RelativeToIssuer. The type you select must correspond to the value in the pointName field.

  • Select DirectoryName if the value in the pointName field is an X.500 directory name (default).

  • Select URI if the value in the pointName field is a uniform resource indicator.

  • Select RelativeToIssuer if the value in the pointName field is a location relative to the CRL Issuer.

Example: URI  

reasons<n>  

Specifies revocation reasons covered by the CRL maintained at the distribution point.

Permissible values: A comma-separated list of the following constants.

  • unused

  • keyCompromise

  • cACompromise

  • affiliationChanged

  • superseded

  • cessationOfOperation

  • certificateHold

Example: keyCompromise  

issuerName<n>  

Specifies the name of the issuer that has signed the CRL maintained at distribution point.

Permissible values: Any supported name forms. By default, the name can be in any of the following formats:

  • An X.500 directory name in the RFC 2253 syntax (see http://www.ietf.org/rfc/rfc2253.txt); note that RFC 2253 replaces RFC 1779. For example, the name would look similar to this:
    CN=CA Central, OU=Research Dept, O=Siroe Corp, C=US

  • A URI; for example, it would look similar to this:
    http://testCA.siroe.com:80

 

issuerType<n>  

Specifies the general-name type of the CRL issuer that has signed the CRL maintained at distribution point.

Permissible values: DirectoryName or URI. The value you specify for this parameter must correspond to the value in the issuerName field.

  • Select DirectoryName if the value in the issuerName field is an X.500 directory name (default).

  • Select URI if the value in the issuerName field is a uniform resource indicator.

Example: DirectoryName  


CRLDistributionPointsExt Rule

The policy rule named CRLDistributionPointsExt is an instance of the CRLDistributionPointsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate field is left blank so that the extension gets added to all certificates.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • Other fields are left blank for you to enter the appropriate information.

For details on individual parameters defined in the rule, see Table 4-8. It is important that you review this rule and make the appropriate changes required by your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter. For example, if you want to include different CRL distribution points in different types of certificates, you should create multiple instances of the policy module and configure each instance with the appropriate CRL distribution point and predicate expression.



ExtendedKeyUsageExt Plug-in Module


The ExtendedKeyUsageExt plug-in module implements the extended key usage extension policy. This policy enables you to configure Certificate Management System to add the Extended Key Usage Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension identifies one or more purposes—in addition to or in place of the basic purposes indicated in the key usage extension—for which the certified public key may be used. For example, if the key usage extension identifies a key to be used for signing, the extended key usage extension can further narrow down the usage of the key for signing OCSP responses only or for signing Java applets only. (For information on key usage extension, see "KeyUsageExt Plug-in Module".)

The PKIX standard suggests that organizations can define their own extended key usage purposes, if there's a need. Each key purpose must be identified by an OID, which in turn must be defined in accordance with IANA or ITU-T Rec. X.660 | ISO/IEC/ITU 9834-1. The standard also recommends that the extension may be marked either critical or noncritical—mark the extension critical if you want to restrict the usage of the certificate only for one of the key-usage purposes indicated by the extension; mark the extension noncritical, when you want it to indicate the intended purposes of the key, and not restrict the use of the certificate to the indicated purposes (in this case, validating applications are expected to treat the extension as an advisory field and may use it to identify the key, not its usage purpose).

Table 4-9 lists the usages defined by PKIX for use with the extended key usage extension.


Table 4-9    PKIX usage definitions for the extended key usage extension  

Usage

OID

Server authentication  

1.3.6.1.5.5.7.3.1  

Client authentication  

1.3.6.1.5.5.7.3.2  

Code signing  

1.3.6.1.5.5.7.3.3  

Email  

1.3.6.1.5.5.7.3.4  

IPSec end system  

1.3.6.1.5.5.7.3.5  

IPSec tunnel  

1.3.6.1.5.5.7.3.6  

IPSec user  

1.3.6.1.5.5.7.3.7  

Timestamping  

1.3.6.1.5.5.7.3.8  

Note that Windows 2000TM allows you to encrypt files on the hard disk, a feature known as encrypted file system (EFS), using certificates that contain the Extended Key Usage extension with the following two OIDs:

1.3.6.1.4.1.311.10.3.4 (this OID is for the EFS certificate)

1.3.6.1.4.1.311.10.3.4.1 (this OID is for the EFS recovery certificate)

The EFS recovery certificate is used by a recovery agent when a user loses the private key and the data encrypted with that key needs to be used. Certificate Management System supports the above two OIDs and allows you to issue certificates containing extended key usage extension with these OIDs.

Normal user certificates should be created with only the EFS OID, not the recovery OID.

For general guidelines on setting the extended key usage extension in certificates, see "extKeyUsage".

The extended key usage extension policy in Certificate Management System allows setting of the key usage extension as defined in its X.509 definition. The policy enables you to specify OIDs, that identify key usages, in the extension.

During installation, Certificate Management System automatically creates two instances of the extended key usage extension policy. See "CODESigningExt Rule" and "OCSPSigningExt Rule".


Configuration Parameters of ExtendedKeyUsageExt

In the CMS configuration file, the ExtendedKeyUsageExt module is identified as
<subsystem>.Policy.impl.ExtendedKeyUsageExt.class=com.netscape.
certsrv.policy.ExtendedKeyUsageExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as ExtendedKeyUsageExt. Figure 4-9 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-9    Parameters defined in the ExtendedKeyUsageExt module


The configuration shown in Figure 4-9 creates a policy rule named CodeSigningExt, which enforces a rule that the extended key usage extension should be set in object-signing certificates.

Table 4-10 gives details about each of these parameters.


Table 4-10    Description of parameters defined in the ExtendedKeyUsageExt module  

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 adds the extended key usage extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==codeSignClient  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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.  

numIds  

Specifies the total number of key-usage purposes to be contained or allowed in the extension.

By default, this field is set to 10 and the UI shows fields for configuring ten key-usage purposes. You can change the total number by changing the value assigned to this parameter; there's no restriction on the total number of key-usage purposes you can include in the extension.

Note that for each key-usage purpose, you must specify a valid OID; otherwise the policy rule will return an error. Configuration parameters for each key-usage purposes is distinguished by <n>, which is an integer derived from the value you assign in this field. For example, if you set the numIds parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no key-usage purposes can be contained in the extension.

  • n specifies the total number of key-usage purposes to be included in the extension; it must be an integer greater than zero. The default value is 10.

Example: 1  

id<n>  

Specifies the OID that identifies a key-usage purpose.

Permissible values: A unique, valid OID specified in the dot-separated numeric component notation. Depending on the key-usage purposes, you may choose to use the OIDs designated by PKIX (listed in Table 4-9) or define your own OIDs. If you're defining your own OID, it should be in the registered subtree of IDs reserved for your company's use. 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 Identifiers" for information on allocating private OIDs.

Example: 2.16.840.1.113730.1.99  


CODESigningExt Rule

The rule named CODESigningExt is an instance of the ExtendedKeyUsageExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (HTTP_PARAMS.certType==codeSignClient) so that the extension gets added to object signing certificates only—these certificates are used for signing objects.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The extension contains a single key-usage purpose, which is identified by an OID (id0=1.3.6.1.5.5.7.3.3). As shown in Table 4-9, this OID is designated for code signing.

Note that this policy rule must remain enabled if you want Certificate Management System to issue object signing certificates with the correct extended key usage extension.

For details on individual parameters defined in the rule, see Table 4-10. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.


OCSPSigningExt Rule

The rule named OCSPSigningExt is an instance of the ExtendedKeyUsageExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (HTTP_PARAMS.certType==ocspResponder) so that the extension gets added to an OCSP responder certificate only—the certificate that corresponds to the key an online validation authority uses to sign OCSP responses.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The extension contains a single key-usage purpose, which is identified by an OID (id0=1.3.6.1.5.5.7.3.9).

Note that this policy rule must remain enabled if your PKI setup includes a CA-delegated OCSP responder and you want to issue an OCSP responder certificate to that server; the rule adds the extended key usage extension to an OCSP responder certificate indicating that the associated key can be used for signing OCSP responses.

Here's some background information that will help you understand why you should set this extension in OCSP responder certificates:

The online certificate status protocol (OCSP) enables OCSP-compliant applications to determine the revocation status of a certificate being validated. Certificate Management System supports the OCSP service—you can configure a Certificate Manager to publish CRLs to an online validation authority (also called OCSP responder); for details, see Chapter 21, "Setting Up an OCSP Responder" of CMS Installation and Setup Guide. If you configure Certificate Management System to work with an OCSP responder, OCSP-compliant applications in your PKI setup will be able to do real-time verification of certificates by querying the OCSP responder for their revocation status. Note that these applications will be able to query the OCSP responder only if the certificate being validated includes the authority information access extension indicating the location of the OCSP responder; for information on adding this extension to certificates, see "AuthInfoAccessExt Plug-in Module".

When queried by an application on the status of a certificate, the OCSP responder sends a digitally signed response. To generate the signature, the responder needs to use a key. Because the signature needs to be verified by the application that sought the response, RFC 2560 recommends that the key used for signing an OCSP response must belong to one of the following:

  • The CA that has issued the certificate, the revocation status of which is being requested.

  • A trusted OCSP responder whose public key is trusted by the application that requested the revocation status of the certificate (as a part of validating the certificate).

  • An OCSP responder that has been authorized by the CA (that has issued the certificate being validated) to sign OCSP responses for certificates issued by that CA.

    In this type of deployment, the CA authorizes a responder to sign OCSP responses on its behalf by issuing a specially marked certificate to the responder. This certificate is called the OCSP responder certificate, and it enables OCSP-compliant applications to identify the responder as a CA-designated responder—a responder authorized to sign OCSP responses for all certificates issued by the CA. The special marking that the CA includes in the certificate is the extended key usage extension with a unique value, OCSPSigning. This extension value indicates to OCSP-compliant applications that the key associated with the certificate can be used for signing OCSP responses.

If you want to deploy a CA-delegated OCSP responder, the OCSPSigningExt rule enables you to add the extended key usage extension (with OCSPSigning value) to the OCSP responder certificate. In addition to this extension, the responder's signing certificate should also include the OCSP no check extension. For details, see "OCSPNoCheckExt Plug-in Module".



GenericASN1Ext Plug-in Module


The GenericASN1Ext plug-in module implements the generic ASN.1 extension policy. This policy enables you to configure Certificate Management System to add custom extensions to certificates. Using this policy, you can add as many ASN.1 type based-extensions as required without having to write any code. Further, it eliminates the dependency on the command-line tools for generating base-64 encoded standard extensions from the x.509 extension classes.

The generic extension policy in Certificate Management System accepts custom extensions in the form of object identifiers (OIDs) and values as DER-encoded extension values. That is, for the server to add a custom extension to certificates it issues, you need to first define the extension and then configure the server with extension details.

Similar to a standard extension, you define a custom extension by defining an OID and a ASN.1 structure.

  • The OID must be specified in the dot-separated numeric component notation (for example, 2.5.29.35). Although you can invent your own OIDs for the purposes of evaluating and testing the 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 Identifiers" for information on allocating private OIDs.

  • The ASN.1 structure must be constructed from a sequence of DER-encoded extension values.

The resulting extension would look similar to the way a standard extension appears in certificates (as defined in RFC 2459):

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

In the policy configuration, the extnID field is defined by the oid parameter, the critical field is defined by the critical parameter, and the extnValue field is defined by evaluating the expression in the pattern parameter, which in turn is defined by the attribute parameters. See Table 4-11 for details on individual parameters.

Typically, the application receiving the certificate checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used. When adding your custom extension to certificates, keep in mind that if the extension exists in a certificate and if it is marked critical, the application validating the certificate must be able to interpret the extension, or else it must reject the certificate. Since it's unlikely that all applications will be able to interpret your custom extensions, you should consider marking these extensions noncritical.

Note that each instance of the policy can be configured to add one custom extension only. To configure the server to add multiple custom extensions, create multiple instances of the module, each with a distinct name and appropriate configuration values. Also note that the policy allows you to encode simple (possibly nested) SEQUENCEs. There is no support for CHOICE, SET, or ASN.1 tagging.

During installation, Certificate Management System automatically creates an instance of the generic ASN.1 extension policy. See "GenericASN1Ext Rule".


Configuration Parameters of GenericASN1Ext

In the CMS configuration file, the GenericASN1Ext module is identified as
<subsystem>.Policy.impl.GenericASN1Ext.class=com.netscape.
certsrv.policy.GenericASN1Ext, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as GenericASN1Ext. Figure 4-10 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-10    Parameters defined in the GenericASN1Ext module


The configuration shown in Figure 4-10 defines a custom extension named testGenASN1Ext with OID 2.4.5.99. The extension is non-critical, and it will be added to all certificates issued by the server. The expected dumpasn1 output (see "dumpasn1 Tool" in CMS Command-Line Tools Guide) of the resulting extension, would look like this:

337 30 148: . . . . SEQUENCE {
340 06 3: . . . . . OBJECT IDENTIFIER '2 4 5 99'
345 04 140: . . . . . OCTET STRING, encapsulates {
348 30 137: . . . . . . . SEQUENCE {
351 13 24: . . . . . . . . PrintableString '1st data in 1st sequence'
377 16 24: . . . . . . . . IA5String '2nd data in 1st sequence'
403 13 32: . . . . . . . . PrintableString 'This is 3rd data in 1st
                                    sequence'
437 04 10: . . . . . . . . OCTET STRING   
   : . . . . . . . . . 11 22 33 44 A0 B0 C0 D0 E0 F0
449 30 37: . . . . . . . . SEQUENCE {
451 17 13: . . . . . . . . . UTCTime '000406070000Z'
466 30 8: . . . . . . . . . SEQUENCE {
468 01 1: . . . . . . . . . . BOOLEAN TRUE
471 06 3: . . . . . . . . . . OBJECT IDENTIFIER '2 4 5 100'
   : . . . . . . . . . . }
476 04 10: . . . . . . . . . OCTET STRING
   : . . . . . . . . . 11 22 33 44 A0 B0 C0 D0 E0 F0
   : . . . . . . . . . }
   : . . . . . . . . }
   : . . . . . . . }
   : . . . . . }

Table 4-11 describes the configurable parameters of the generic ASN.1 extension policy module.


Table 4-11    Description of parameters defined in the GenericASN1Ext module  

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 adds the configured extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).

In general, you should make custom extensions noncritical if you want your certificates supported by other applications. (Other applications most likely will not understand your extension.)  

name  

Specifies the name of the extension. The name is displayed when users view the details of a certificate that includes the extension.

Permissible values: A unique name that corresponds to the OID specified by the oid parameter.

Example: myCorp'sExtension  

oid  

Specifies the OID assigned to the extension.

Permissible values: A valid OID specified in dot-separated numeric component notation (see the example). 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 Identifiers" for information on allocating private OIDs.

Example: 1.22.333.444.55.666  

pattern  

Specifies the pattern of the extension.

Permissible values: The pattern can be any sequence of supported ASN.1 type. Rules for formulating the pattern are as follows:

  • Each data component in the pattern must be represented by it's predefined attribute identifier, 0 to 9, and each sequence must be grouped by a pair of curly brackets, {}.

  • Each attribute identifier represented in the pattern must be fully defined in the extension. For example, if you want to include attribute identifier 0, you must specify values for attribure.0.type, attribure.0.source, and attribure.0.value parameters.

No default value is assigned to this parameter.

Example: {{012}34}  

attribute.<n>.type  

Specifies the data type for attribute n, where n is an identifier assigned to identify parameters pertaining to a specific attribute. The value of n can be 0 to 9.

Permissible values: Integer, IA5String, OctetString, PrintableString, UTCtime, OID, or Boolean.

  • Select Integer for extensions that have ASN.1 INTEGER values (default). It's case insensitive and accepts an integer in decimal notation as value.

  • Select IA5String for extensions that have ASN.1 IA5String values. It's case insensitive and accepts any normal string as value.

  • Select OctetString for extensions that have ASN.1 OCTET STRING values. It's case insensitive and the value is dependent on data source. If the data source is Value, the value must be in colon-separated, ASCII hexadecimal encoding notation. If the data source is File, the server reads the attribute value from the file specified.

  • Select VisualString for extensions that have printing character sets of International ASCII.

  • Select PrintableString for extensions that have ASN.1 PrintableString values. It's case insensitive and accepts any normal string as value.

  • Select UTCTime for site-defined extensions that have ASN.1 UTCTime values.

  • Select OID for extensions that have ASN.1 OBJECT IDENTIFIER values.

  • Select Boolean for extensions that have ASN.1 BOOLEAN values. It's case insensitive and accepts true or false as value.

Example: Integer  

attribute.<n>.source  

Specifies the data source for attribute n in the extension, where n is an identifier assigned to identify parameters pertaining to a specific attribute. The value of n can be 0 to 9.

In some cases, it may be preferable to put the value of an attribute in a file, instead of specifying it in the configuration parameters. This may be the case if the value of the attribute is a long text file or octet-string, for example.

Permissible values: Value or File. (The attribute's value parameter is interpreted according to the value specified for this parameter.)

  • Value specifies that the attribute's value parameter is literally the value to be inserted in the extension (default).

  • File specifies that the attribute's value parameter is a fully-qualified pathname of a file containing the value to be inserted in the extension.

Example: Value  

attribute.<n>.value  

Specifies the data value for attribute n, where n is an identifier assigned to identify parameters pertaining to a specific attribute. The value of n can be 0 to 9.

Permissible values: Depends on the data type and source you selected.

  • If the data type is Integer, enter an integer in decimal notation as value. For example, 1234567890.

  • If the data type is IA5String, enter a normal string as value. For example, Test of IA5String.

  • If the data type is OctetString and if the data source is Value, enter the value in colon-separated ASCII hexadecimal encoding notation. For example, 11:22:33:44:A0:B0:C0:D0:E0:F0.
    If data source is File, enter the complete file path, including the filename, in the specified format. When specifying file path in a Window NT system do not use the NT native file separator, the backward slash (\). Use Unix style file separator, the forward slash (/), instead. For example,
    C:/customExt/octet_string_value.txt.

  • If the data type is PrintableString, enter a normal string as value. For example, This_is_a_printable_string.

  • If the data type is UTCTime, enter a date in mm/dd/yy format. For example, April 5, 2000 would be 4/5/00 and October 10, 2001 would be 10/10/01.

  • If the data type is OID, enter a valid OID. For example, 11.33.234.99.

  • If the data type is Boolean, enter true or false as value. For example, true.

 


GenericASN1Ext Rule

The rule named GenericASN1Ext is an instance of the GenericASN1Ext module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate field is left blank so that the extension gets added to all certificates the server issues.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • Other fields are left blank for you to enter the appropriate information.

For details on individual parameters defined in the rule, see Table 4-11. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



IssuerAltNameExt Plug-in Module


The IssuerAltNameExt plug-in module implements the issuer alternative name extension policy. This policy enables you to configure Certificate Management System to add the Issuer Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. This extension enables binding of or associating Internet style identities—such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI)— with the certificate issuer.

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

The issuer alternative name extension policy in Certificate Management System allows setting of the issuer alternative name extension as defined in its X.509 definition. The policy enables you to associate the following alternative identities to a CA, by including them in the extension:

  • An rfc822 name

  • A directory name

  • A DNS name

  • An EDI party name

  • A uniform resource indicator (URI)

  • An IP address

  • An object identifier (OID)

  • Other Name

Unlike some of the other policy modules, Certificate Management System does not create an instance of the issuer alternative name extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the IssuerAltNameExt module and configure it. For instructions, see section "Step 4. Add New Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of IssuerAltNameExt

In the CMS configuration file, the IssuerAltNameExt module is identified as
<subsystem>.Policy.impl.IssuerAltNameExt.class=com.netscape.
certsrv.policy.IssuerAltNameExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as IssuerAltNameExt. Figure 4-11 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-11    Parameters defined in the IssuerAltNameExt module


The configuration shown in Figure 4-11 creates a policy rule named IssuerAltNameExtForCACert, which enforces a rule that the server should set the issuer alternative name extension in CA certificates only.

Table 4-12 gives details about each of these parameters.


Table 4-12    Description of parameters defined in the IssuerAltNameExt module  

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 adds the issuer alternative name extension to all certificates specified by the predicate parameter.

  • If you disable the rule, the server doesn't add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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.  

numGeneralNames  

Specifies the total number of alternative names or identities permitted in the extension. Note that each name has a set of configuration parameters—generalName<n>.generalNameChoice and generalName<n>.generalNameValue—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 numGeneralNames 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 (default).

  • 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 8.

Example: 2  

generalName<n>.generalNameChoice  

Specifies the general-name type for the alternative name you want to include in the extension.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName.

  • Select rfc822Name if the alternative name is an Internet mail address (default).

  • Select directoryName if the alternative name is an X.500 directory name.

  • Select dNSName if the alternative name is a DNS name.

  • Select ediPartyName if the alternative name is a EDI party name.

  • Select URL if the alternative name is a uniform resource locator (URL).

  • Select iPAddress if the alternative name is an IP address.

  • Select OID if the alternative name is an object identifier.

  • Select otherName if the alternative name is in any other name form.

Example: rfc822Name  

generalName<n>.generalNameValue  

Specifies the general-name value for the alternative name you want to include in the extension.

Permissible values: Depends on the general-name type you selected in the generalName<n>.generalNameChoice field.

  • If you selected 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 you selected 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=CA Corp,OU=Research Dept,O=Siroe Corp, C=US.

 

 
  • If you selected dNSName, the value must be a valid domain name in the preferred-name syntax as specified by 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 you selected ediPartyName, the value must be an IA5String. For example, Siroe Corporation.

  • If you selected URL, the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules specified in RFC 1738. 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 you selected iPAddress, the value must be a valid IP address (IPv4 or IPv6) 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 you selected 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 Identifiers" for information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99.

  • If you selected otherName, the value must be the absolute path to the file that contains the base-64 encoded string of the alternative name. For example, /usr/netscape/server4/ext/ian/othername.txt.

 



KeyUsageExt Plug-in Module


The KeyUsageExt plug-in module implements the key usage extension policy. This policy enables you to configure Certificate Management System to add the Key Usage Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension specifies the purposes for which the key contained in a certificate should be used—for example, it specifies whether the key should be used for data signing, key encipherment, or data encipherment—and thus enables you to restrict the usage of a key pair to predetermined purposes.

The key usage extension is a string of boolean bit-flags, each bit identifying the purpose for which a key is to be used. Table 4-13 lists the bits and their designated purposes.


Table 4-13    Key usage extension bits and designated purposes  

Bit

Purpose

0  

digitalSignature  

1  

nonRepudiation  

2  

keyEncipherment  

3  

dataEncipherment  

4  

keyAgreement  

5  

keyCertSign  

6  

cRLSign  

7  

encipherOnly  

8  

decipherOnly  

You can restrict the purposes for which a key pair (and thus the corresponding certificate) should be used by setting the appropriate key-usage bits. For example, if you want to restrict a key pair to be used for digital signature only, when issuing the certificate you would add the key usage extension to the certificate with digital_signature bit (or bit 0) set. For general guidelines on setting the key usage extension in certificates, see "keyUsage".

Note that you can specify which bits in the extension are to be set on both server and client sides:

  • On the server side, you set the bits by modifying the appropriate configuration parameters that are defined in the key usage extension policy.

  • On the client side, bits set in the key usage extension are formed from pre-defined HTTP input variables that can be embedded as hidden values in the enrollment forms. You specify which bits are to be set by adding the appropriate HTTP variables to the enrollment forms. Table 4-14 lists the HTTP input variables that correspond to key usage extension bits.
    Note For all certificates, the key-usage-bits set on the server side (which is governed by the policy) override the ones set on the client side.



    Table 4-14    HTTP input variables for key usage extension bits  

    HTTP input variable

    Key usage extension bit

    digital_signature  

    digitalSignature (bit 0)  

    non_repudiation  

    nonRepudiation (bit 1)  

    key_encipherment  

    keyEncipherment (bit 2)  

    data_encipherment  

    dataEncipherment (bit3)  

    key_agreement  

    keyAgreement (bit4)  

    key_certsign  

    keyCertsign (bit5)  

    crl_sign  

    cRLSign (bit6)  

    encipher_only  

    encipherOnly (bit7)  

    decipher_only  

    decipherOnly (bit8)  

During installation, Certificate Management System automatically creates multiple instances of the key usage extension policy suitable for various types of certificates that you may want the server to issue. The default instances are named as follows:

It is important that you review each policy instance and make the appropriate changes required by your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.

Additionally, as you'll notice in Figure 4-13 through Figure 4-17, the default enrollment forms provided for requesting various types of certificates (see "Enrollment Forms") include the appropriate HTTP input variables that correspond to the key-usage bits. By default only variables that correspond to key-usage bits that need to be set are included in the form.

Typically, you won't have to change the key-usage bit setting by editing the enrollment forms as you can do this easily by making the appropriate changes to the policy instance (bits set on the server side override the ones set on the client side). However, if you want to add new variables on the client side, you can do that too. Be sure to add the new variable in the following format:

<input type="HIDDEN" name="variable_name" value=true>

where, variable_name can be any of the HTTP input variables listed in Table 4-14.

The value of an HTTP input variable corresponding to a key-usage bit must be either true or false; any other value is considered equivalent to false. For example, a value tree would be interpreted as false by the server. Note that values true and false are case insensitive.


Configuration Parameters of KeyUsageExt

In the CMS configuration file, the KeyUsageExt module is identified as
<subsystem>.Policy.impl.KeyUsageExt.class=com.netscape.certsrv.
policy.KeyUsageExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as KeyUsageExt. Figure 4-12 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-12    Parameters defined in the KeyUsageExt module


The configuration shown in Figure 4-12 creates a policy rule named KeyUsageExtForClientCert, which enforces a rule that the server should set the key usage extension (digitalSignature, nonRepudiation, and keyEncipherment bits) in client certificates.

Table 4-15 gives details about each of these parameters.


Table 4-15    Description of parameters defined in the KeyUsageExt module  

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, the server checks the key usage extension bits specified in the remaining fields, and adds the extension with those bits to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the key usage extension-specific bits specified in the policy configuration and in the enrollment forms.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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.  

digitalSignature  

Specifies whether to set the digitalSignature bit (or bit 0) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the digitalSignature bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

nonRepudiation  

Specifies whether to set the nonRepudiation bit (or bit 1) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the nonRepudiation bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

keyEncipherment  

Specifies whether to set the keyEncipherment bit (or bit 2) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the keyEncipherment bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

dataEncipherment  

Specifies whether to set the dataEncipherment bit (or bit 3) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the dataEncipherment bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

keyAgreement  

Specifies whether to set the keyAgreement bit (or bit 4) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the keyAgreement bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

keyCertsign  

Specifies whether to set the keyCertSign bit (or bit 5) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the keyCertsign bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

cRLSign  

Specifies whether to set the cRLSign bit (or bit 6) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the CRLsign bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

encipherOnly  

Specifies whether to set the encipherOnly bit (or bit 7) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the encipherOnly bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 

decipherOnly  

Specifies whether to set the decipherOnly bit (or bit 8) of the key usage extension in certificates specified by the predicate parameter.

Permissible values: true, false, or HTTP_INPUT.

  • Select true if you want the server to set the bit (default).

  • Select false if you don't want the server to set the bit.

  • Select HTTP_INPUT if you want the server to check the certificate request for the HTTP input variable corresponding to the decipherOnly bit and set the bit accordingly. If the variable is set to true, the server sets the bit. If the variable doesn't exist or if it is set to false (or any other value), the server doesn't set the bit.

 


CMCertKeyUsageExt Rule

The policy rule named CMCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in Certificate Manager CA signing certificates; see section "CA Signing Key Pair and Certificate" in Chapter 14, "Managing CMS Keys and Certificates" of CMS Installation and Setup Guide. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (predicate=HTTP_PARAMS.certType==ca) ensures that the rule is applied only to CA signing certificate requests.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The server is configured to set digitalSignature, nonRepudiation, keyCertsign, and cRLSign bits in CA signing certificates. Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form (ManCAEnroll.html) for requesting CA signing certificates (see Figure 4-13).

Figure 4-13    Key usage bit-specific variables in the Certificate Manager enrollment form



RMCertKeyUsageExt Rule

The policy rule named RMCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in Registration Managers' signing certificates; see section "Signing Key Pair and Certificate" in Chapter 14, "Managing CMS Keys and Certificates" of CMS Installation and Setup Guide. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (HTTP_PARAMS.certType==ra) ensures that the rule is applied only to Registration Manager signing certificate requests.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The server is configured to set digitalSignature and nonRepudiation bits in Registration Manager signing certificates. Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form (ManRAEnroll.html) for requesting Registration Manager signing certificates (see Figure 4-14).

Figure 4-14    Key usage bit-specific variables in the Registration Manager enrollment form



ServerCertKeyUsageExt Rule

The policy rule named ServerCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in SSL server certificates. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (HTTP_PARAMS.certType==server) ensures that the rule is applied only to SSL server certificate requests.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The server is configured to set digitalSignature, nonRepudiation, keyEncipherment, and dataEncipherment bits in SSL server certificates. Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form (ManServerEnroll.html) for requesting SSL server certificates (see Figure 4-15).

Figure 4-15    Key usage bit-specific variables in the SSL server certificate enrollment form



ClientCertKeyUsageExt Rule

The policy rule named ClientCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in SSL client certificates. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (HTTP_PARAMS.certType==client) ensures that the rule is applied only to SSL client certificate requests.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The server is configured to set digitalSignature, nonRepudiation, and keyEncipherment key-usage bits in SSL client certificates.

Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form for requesting SSL client certificates. Figure 4-16 shows the default directory-based enrollment form for end users with the information related to the key usage extension variables highlighted—it shows three of the total number of variables listed in Table 4-14. Note that by default three key-usage bits—digitalSignature, nonRepudiation, and keyEncipherment—are enabled and the remaining bits are disabled.

Additionally, also notice the HTTP variables for the Netscape certificate type extension: the values indicate that the certificate is meant for S/MIME and SSL client authentication use only. (For details on Netscape certificate type extension, see "NSCertTypeExt Plug-in Module".)

Figure 4-16    Key usage extension bits in the directory-based enrollment form


Keep in mind that for requesting client certificates, there are many enrollment forms. You may be using a combination of them:

  • Certificate-based enrollment forms (CertBasedDualEnroll.html, CertBasedEncryptionEnroll.html, or CertBasedSingleEnroll.html)

  • Directory-based enrollment form (DirUserEnroll.html)

  • Directory- and PIN-based enrollment form (DirPinUserEnroll.html)

  • Manual enrollment form (ManUserEnroll.html)

  • NIS-based enrollment form (NISEnroll.html)

  • Portal enrollment form (PortalEnrollment.html)

For details about these forms, see "Enrollment Forms".

Each of these forms embed HTTP input variables (for key-usage bits) that are considered appropriate for the certificate being requested using that form. If you want, you may create additional instances of the key usage extension policy, one each for each client certificate enrollment form and configure these instances as appropriate. Be sure to use the correct predicate expression to distinguish the certificates to thus avoid setting incorrect bits.


ObjSignCertKeyUsageExt Rule

The policy rule named ObjSignCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in object signing certificates. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (predicate=HTTP_PARAMS.certType==objSignClient) ensures that the rule is applied to only object signing certificate requests.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The server is configured to set digitalSignature and keyCertsign bits in object-signing certificates. Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form (ManObjSignEnroll.html) for requesting object-signing certificates (see Figure 4-17).

Figure 4-17    Key usage extension bits in the object signing certificate enrollment form



CRLSignCertKeyUsageExt

The policy rule named CrlSignCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in a CRL signing certificate. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression (predicate=HTTP_PARAMS.certType==caCrlSigning) ensures that the rule is applied to only CRL signing certificate requests.

  • The server is configured to set the cRLSign bit in CRL signing certificates.



NameConstraintsExt Plug-in Module

The NameConstraintsExt plug-in module implements the name constraints extension policy. This policy enables you to configure Certificate Management System to add the Name Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used in CA certificates to indicate a name space within which subject names or subject alternative names in subsequent certificates in a certification path or chain should be located.

Various standards describe how the name constraints extension should be processed during certificate verification. It's beyond the scope of this document to explain this. For general guidelines on setting the name constraints extension in certificates, see "nameConstraints".

The policy implemented in Certificate Management System allows setting of the name constraints extension in any form as defined in its X.509 definition; the policy enables you to specify the number of subtrees permitted and excluded in the extension. It is up to applications to process the extension as described in the standards.

During installation, Certificate Management System automatically creates an instance of the name constraints extension policy. See "NameConstraintsExt Rule".


Configuration Parameters of NameConstraintsExt

In the CMS configuration file, the NameConstraintsExt module is identified as
ca.Policy.impl.NameConstraintsExt.class=com.netscape.certsrv.
policy.NameConstraintsExt.

In the CMS window, the module is identified as NameConstraintsExt. Figure 4-18 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-18    Parameters defined in the NameConstraintsExt module


The configuration shown in Figure 4-18 creates a policy rule named NameConsExtForCACert, which enforces a rule that the server should set the name constraints extension as a critical extension in CA certificates.

Table 4-16 gives details about each of these parameters.


Table 4-16    Description of parameters defined in the NameConstraintsExt module  

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 adds the name constraints extension to all certificates specified by the predicate parameter.

  • If you disable the rule, the server doesn't add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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.  

numPermittedSubtrees  

Specifies the total number of subtrees to be permitted in the extension. Note that each permitted subtree has a set of configuration parameters and you must specify appropriate values for each of these parameters; otherwise the policy rule will return an error.

You can change the total number of permitted subtrees by changing the value in this field; there's no restriction on the total number of permitted subtrees 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 numPermittedSubtrees parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no permitted subtrees can be contained in the extension.

  • n specifies the total number of permitted subtrees to be included in the extension; it must be an integer greater than zero. The default value is 8.

Example: 2  

numExcludedSubtrees  

Specifies the total number of subtrees to be excluded in the extension. Note that each excluded subtree has a set of configuration parameters and you must specify appropriate values for each of these parameters; otherwise the policy rule will return an error.

You can change the total number of excluded subtrees by changing the value in this field; there's no restriction on the total number of excluded subtrees 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 numExcludedSubtrees parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no excluded subtrees can be contained in the extension.

  • n specifies the total number of excluded subtrees to be included in the extension; it must be an integer greater than zero. The default value is 8.

Example: 2  

permittedSubtrees<n>.
base.generalNameChoice  

Specifies the general-name type for the permitted subtree you want to include in the extension.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URI, iPAddress, registeredID, or otherName.

  • Select rfc822Name if the subtree is an Internet mail address (default).

  • Select directoryName if the subtree is an X.500 directory name.

  • Select dNSName if the subtree is a DNS name.

  • Select ediPartyName if the subtree is a EDI party name.

  • Select URL if the subtree is a uniform resource locator.

  • Select iPAddress if the subtree is an IP address.

  • Select OID if the subtree is an object identifier.

  • Select otherName if the subtree is in any other name form.

Example: directoryName  

permittedSubtrees<n>.
base.generalNameValue  

Specifies the general-name value for the permitted subtree you want to include in the extension.

Permissible values: Depends on the general-name type you selected in the permittedSubtrees<n>.base.generalNameChoice field.

  • If you selected 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 you selected 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=SubCA, OU=Research Dept, O=SiroeCorp, C=US.

  • If you selected dNSName, the value must be a valid domain name in the preferred-name syntax as specified by 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 you selected ediPartyName, the value must be a IA5String. For example, Siroe Corporation.

  • If you selected URL, the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules specified in RFC 1738. 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 you selected iPAddress, the value must be a valid IP address (IPv4 or IPv6) specified in the 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 you selected OID, the value must be a unique, valid OID specified in 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 Identifiers" for information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99.

  • If you selected otherName, the value must be the absolute path to the file that contains the base-64 encoded string of the subtree. For example, /usr/netscape/server4/ext/nc/othername.txt.

 

permittedSubtrees<n>.
min  

Specifies the minimum number of permitted subtrees.

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension.

  • 0 specifies that the minimum number of subtrees is zero (default).

  • n must be an integer that is greater than zero. It specifies at the most n subtrees are allowed.

Example: 0  

permittedSubtrees<n>.
max  

Specifies the maximum number of permitted subtrees.

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension (default).

  • 0 specifies that the maximum number of subtrees is zero.

  • n must be an integer that is greater than zero. It specifies at the most n subtrees are allowed.

Example: 1  

excludedSubtrees<n>.
base.generalNameChoice  

Specifies the general-name type for the excluded subtree you want to include in the extension.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName.

  • Select rfc822Name if the subtree is an Internet mail address.

  • Select directoryName if the subtree is an X.500 directory name.

  • Select dNSName if the subtree is a DNS name.

  • Select ediPartyName if the subtree is a EDI party name.

  • Select URL if the subtree is a uniform resource locator.

  • Select iPAddress if the subtree is an IP address.

  • Select OID if the subtree is an object identifier.

  • Select otherName if the subtree is in any other name form.

Example: OID  

excludedSubtrees<n>.
base.generalNameValue  

Specifies the general-name value for the excluded subtree you want to include in the extension.

Permissible values: Depends on the general-name type you selected in the excludedSubtrees<n>.base.generalNameChoice field.

  • If you selected 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 you selected 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=SubCA,OU=Research Dept,O=Siroe Corp,C=US.

  • If you selected dNSName, the value must be a valid domain name in the preferred-name syntax as specified by 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 you selected ediPartyName, the value must be an IA5String. For example, Siroe Corporation.

  • If you selected URL, the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules specified in RFC 1738. 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 you selected iPAddress, the value must be a valid IP address (IPv4 or IPv6) specified in the 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 you selected OID, the value must be a unique, valid OID specified in dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99.

 

 
  • If you selected otherName, the value must be the absolute path to the file that contains the base-64 encoded string of the subtree. For example, /usr/netscape/server4/ext/nc/othername.txt.

 

excludedSubtrees<n>.
min  

Specifies the minimum number of excluded subtrees.

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension.

  • 0 specifies that the minimum number of subtrees is zero (default).

  • n must be an integer that is greater than zero. It specifies at the most n subtrees are allowed.

Example: 0  

excludedSubtrees<n>.
max  

Specifies the maximum number of excluded subtrees.

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension (default).

  • 0 specifies that the maximum number of subtrees is zero.

  • n must be an integer that is greater than zero. It specifies at the most n subtrees are allowed.

Example: 1  


NameConstraintsExt Rule

The policy rule named NameConstraintsExt is an instance of the NameConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ca) so that the extension gets added to CA certificates only.

  • The extension is marked critical (to comply with the PKIX recommendation).

  • The total number of permitted subtrees to be contained in the extension is set to 3 (numPermittedSubtrees=3).

  • The total number of excluded subtrees to be contained in the extension is set to 3 (numExcludedSubtrees=3).

  • The maximum number of permitted subtrees is set to -1 (permittedSubtrees<n>.max=-1) and the minimum number of permitted subtrees is set to 0 (permittedSubtrees<n>.min=0).

  • The maximum number of excluded subtrees is set to -1 (excludedSubtrees<n>.max=-1) and the minimum number of excluded subtrees is set to 0 (excludedSubtrees<n>.min=0).

  • The general name type and value fields for each subtree are left blank for you to select or enter the appropriate values.

For details on individual parameters defined in the rule, see Table 4-16. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



NSCCommentExt Plug-in Module


The NSCCommentExt plug-in module implements the Netscape certificate comment extension policy. This policy enables you to configure Certificate Management System to add the Netscape Certificate Comment Extension (see http://www.netscape.com/eng/security/cert-exts.html) to certificates. The extension can be used to include textual comments in certificates. Applications that are capable of interpreting the comment may display it to a relying party when the certificate is used or viewed.

For general guidelines on setting the Netscape certificate comment extension, see "netscape-comment".

The Netscape certificate comment extension policy in Certificate Management System allows you to specify a textual statement or a comment to be included in certificates. You may choose to directly embed the text in the certificate itself or point to the file that contains the statement.

During installation, Certificate Management System automatically creates an instance of the Netscape certificate comment extension policy. See "NSCCommentExt Rule".


Configuration Parameters of NSCCommentExt

In the CMS configuration file, the NSCCommentExt module is identified as
<subsystem>.Policy.impl.NSCCommentExt.class=com.netscape.
certsrv.policy.NSCCommentExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as NSCCommentExt. Figure 4-19 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-19    Parameters defined in the NSCCommentExt module


The configuration shown in Figure 4-19 creates a policy rule named NetscapeCommentExtForClientCert, which enforces a rule that the server should set the Netscape certificate comment extension in client certificates.

Table 4-17 provides details for each of these parameters.


Table 4-17    Description of parameters defined in the NSCCommentExt module  

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 adds the Netscape certificate comment extension to certificates specified by the predicate parameter. If you enable the policy without specifying values in displayText and commentfile fields, the server puts an empty string in the comment extension.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

inputType  

Specifies whether to embed a textual statement or to include a pointer to file that contains the textual statement in certificates. The extension value is interpreted according to the value specified for this parameter.

You should consider putting the textual statement in a file because certain applications may not have the capability to display the text embedded in certificates. Also, embedding a textual statement in a certificate increases its size. If you're using smart cards for generating and storing certificates, you may not want to embed textual statements in certificates because on a smart card the memory for a certificate may be limited.

Permissible values: Text or File.

  • Text specifies that the textual statement—the value of the displayText field— should be inserted in the extension (default).

  • File specifies that the path to the file that contains the textual statement—the value of the commentfile field—should be inserted in the extension.

Example: File  

displayText  

Specifies the textual statement that should be included in certificates. If you want to embed a textual statement (for example, your company's legal notice) in certificates, then add that statement here. The text you enter here will be displayed to a relying party when the certificate is used or viewed.

Permissible values: A string with up to 200 characters.

Example: SiroeCorp's CPS incorp. by reference liab. ltd.
(c)99 SiroeCorp  

commentfile  

Specifies the path to the file that contains the textual statement that should be included in certificates; be sure to include the complete path, including the filename. Note that the existence of the file is not checked at the time of policy configuration. The filename will be checked when the policy is applied to a request.

Example: C:\CApolicies\UserCertpolicy.txt  


NSCCommentExt Rule

The policy rule named NSCCommentExt is an instance of the NSCCommentExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate field is left blank so that the extension gets added to all certificates.

  • The extension is marked noncritical.

  • The textual statement is to be embedded in certificates (inputType=Text).

  • The displayText and commentfile fields are left blank for you to enter the appropriate information.

For details on individual parameters defined in the rule, see Table 4-17. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



NSCertTypeExt Plug-in Module


The NSCertTypeExt plug-in module implements the Netscape certificate type extension policy. This policy enables you to configure Certificate Management System to add the Netscape Certificate Type extension to certificates. The extension identifies the certificate type—for example, it identifies whether the certificate is a CA certificate, server SSL certificate, client SSL certificate, object signing certificate, or S/MIME certificate—and thus enables you to restrict the usage of a certificate to predetermined purposes.

  • If the extension exists in a certificate, it limits the uses of the certificate to those specified (it limits the applications for a certificate).

  • If the extension is not present, the certificate can be used for all applications except object signing.

The Netscape certificate type extension is a string of boolean bit-flags, each bit identifying the purpose for which a certificate to be used. Table 4-18 lists the bits and their designated purposes. The extension has no default value.


Table 4-18    Netscape certificate type extension bits and designated purposes  

Bit

Purpose

Description

0  

SSL Client  

Specifies that the certificate can be used by clients for authentication during SSL connections.  

1  

SSL Server  

Specifies that the certificate can be used by servers for authentication during SSL connections.  

2  

S/MIME  

Specifies that the certificate can be used to send secure email messages.  

3  

Object Signing  

Specifies that the certificate can be used for signing objects such as Java applets and plug-ins.  

4  

Reserved  

This bit is reserved for future use.  

5  

SSL CA  

Specifies that the certificate can be used by a CA to issue certificates for SSL connections.  

6  

S/MIME CA  

Specifies that the certificate can be used by a CA to issue certificates for secure email.  

7  

Object Signing CA  

Specifies that the certificate can be used by a CA to issue certificates for object signing.  

The Netscape certificate type extension policy has been implemented in such a way that it enables you to set the appropriate certificate-type bits for certificates being issued by Certificate Management System. This way, you can restrict the purposes for which a certificate should be used by adding the extension, with the appropriate bits set, to the certificate at the time of issuance. For example, if you want to restrict a certificate to be used for SSL client authentication only, when issuing the certificate you would add the Netscape certificate type extension to the certificate with ssl_client (bit 0) set. For general guidelines on setting the Netscape certificate type extension, see "netscape-cert-type".

In the current implementation, you can specify whether to add the extension to certificates on the server side and which bits in the extension are to be set on the client side—you specify whether to add the extension by enabling the Netscape certificate type extension policy and which bits are to be set by adding the appropriate HTTP variables to the enrollment forms.

Bits set in the Netscape certificate type extension are formed from pre-defined input variables that you can embed as hidden values in the default enrollment forms (see "Enrollment Forms"). Table 4-19 lists the HTTP input variables that correspond to Netscape certificate type extension bits.


Table 4-19    HTTP input variables for Netscape certificate type extension bits  

HTTP input variable

Netscape certificate type extension bit

ssl_client  

SSL Client (bit 0)  

ssl_server  

SSL Server (bit 1)  

email  

S/MIME (bit 2)  

object_signing  

Object Signing (bit 3)  

 

Reserved for future use (bit 4)  

ssl_ca  

SSL CA (bit 5)  

email_ca  

S/MIME CA (bit 6)  

object_signing_ca  

Object Signing CA (bit 7)  

During installation, Certificate Management System automatically creates an instance of the Netscape certificate type extension policy for the various types of certificates that you may want the server to issue. See "NSCertTypeExt Rule".

Additionally, the default enrollment forms—the directory-based, directory- and PIN-based, manual, Kerberos server-based, and NIS server-based enrollment forms—for various types of certificates also include the appropriate HTTP input variables corresponding to Netscape certificate type extension bits. For details about these forms, see "Enrollment Forms".

Figure 4-20 shows the default directory-based enrollment form for end users with HTTP input variables specific to Netscape certificate type extension highlighted; it shows two of the total number of variables listed in Table 4-19, ssl_client and email, indicating that these bits be set in certificates requested using this form.

Figure 4-20    Netscape certificate type extension-specific variables in enrollment forms


Note that the default enrollment forms embed variables that are considered appropriate for the type of certificate, such as client, server, or CA, that can be requested using the form. For example, the server enrollment form embeds the ssl_server variable, whereas the subordinate CA (Certificate Manager) enrollment form embeds the ssl_client, email_ca, ssl_ca and object_signing_ca variables.

In general, the forms are set up so that you don't have to make any modifications. However, if there is a need to modify the bit settings, be sure to add or remove the corresponding variable. Also, when adding a new variable, make sure that the HTML input format is as follows:

<input type="HIDDEN" value="true" name="variable_name">

where variable_name can be any of the variables listed in Table 4-19.


Configuration Parameters of NSCertTypeExt

In the CMS configuration file, the NSCertTypeExt module is identified as
<subsystem>.Policy.impl.NSCertTypeExt.class=com.netscape.
certsrv.policy.NSCertTypeExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as NSCertTypeExt. Figure 4-21 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-21    Parameters defined in the NSCertTypeExt module


The configuration shown in Figure 4-21 creates a policy rule named NetscapeCertTypeExtForClientCert, which enforces a rule that the server should set the Netscape certificate type extension in client certificates.

Table 4-20 gives details about each of these parameters.


Table 4-20    Description of parameters defined in the NSCertTypeExt module  

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, be sure to review the enrollment forms for Netscape certificate type extension-specific variables and to set the remaining parameters of this policy correctly. If the bits are unspecified in the enrollment form, the server checks the value assigned to the setDefaultBits parameter. If it is unchecked (false), the server does not set the extension.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the Netscape certificate type extension-specific HTTP input values in the certificate request and the status of the setDefaultBits parameter.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

setDefaultBits  

Specifies whether to set the Netscape certificate type extension with default bits in certificates specified by the predicate expression.

  • Check the box the if you want the server to add the extension, with default bits, to certificates. If you check the box and if no bits are requested from the HTTP input, the server adds the Netscape certificate type extension to certificates with the following bits set:
    - ssl client (bit 0)
    - email (bit 2)

  • Uncheck the box if you don't want the server to add the extension with default bits. If you uncheck the box and if no bits are requested from the HTTP input, the server does not add the extension to certificates.

 


NSCertTypeExt Rule

The policy rule named NSCertTypeExt is an instance of the NSCertTypeExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set so that the extension gets added to all certificates except the ones issued to routers (predicate=HTTP_PARAMS.certType!=CEP-Request).

  • The server sets the default bits if the bits are unspecified in the enrollment form.

For details on individual parameters defined in the rule, see Table 4-20. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



OCSPNoCheckExt Plug-in Module


The OCSPNoCheckExt plug-in module implements the OCSP no check extension policy. This policy enables you to configure Certificate Management System to add the OCSP No Check Extension defined in X.509 and PKIX standard RFC 2560 (see http://www.ietf.org/rfc/rfc2560.txt) to certificates. The extension, which should be used in OCSP responder certificates only, indicates how OCSP-compliant applications can verify the revocation status of the certificate an authorized OCSP responder uses to sign OCSP responses.

The online certificate status protocol (OCSP) enables OCSP-compliant applications to determine the revocation status of a certificate being validated. Certificate Management System supports the OCSP service—you can configure a Certificate Manager to publish CRLs to an online validation authority, also called OCSP responder (see Chapter 21, "Setting Up an OCSP Responder" of CMS Installation and Setup Guide). If you configure Certificate Management System to work with an OCSP responder, OCSP-compliant applications in your PKI setup will be able to do real-time verification of certificates by querying the OCSP responder for their revocation status. Note that these applications will be able to query the OCSP responder only if the certificate being validated includes the authority information access extension indicating the location of the OCSP responder; for information on adding this extension to certificates, see "AuthInfoAccessExt Plug-in Module".

When queried by an application on the status of a certificate, the OCSP responder sends a digitally signed response. For the signature, the responder uses the key pair designated for signing OCSP responses. Usually, the CA issues an OCSP responder certificate to the responder, which enables applications to identify it as a CA-designated responder. The CA issues this certificate with an extended key usage extension with a unique value, which indicates that the key associated with the certificate can be used for signing OCSP responses. For details on this extension, see "OCSPSigningExt Rule".

When an OCSP-compliant application receives a signed response, as a part of validating the signature, the application needs to verify that the responder's certificate has not been revoked. RFC 2560 recommends three ways in which a CA may indicate the revocation status of an OCSP responder certificate. One of them is that the CA issue the OCSP responder a certificate with the OCSP no check extension, which indicates that the certificate can be trusted by the clients for its lifetime. The OCSP no check policy of Certificate Management System implements this method and enables you to set the OCSP no check extension in OCSP responder certificates.

Because OCSP-compliant applications don't check for the revocation status of the OCSP responder certificate (containing the OCSP no check extension), when issuing these types of certificates, you should consider issuing them with a short validity period (and renew them frequently). Note that the OCSP no check extension policy only adds the extension to a certificate; it doesn't control the validity period of the certificate. If you want to limit the validity period of these certificates to a short period, you should consider creating an instance of the ValidityConstraints module with the appropriate configuration, for example, set the predicate parameter to HTTP_PARAMS.certType=ocspResponder. For details, see "ValidityConstraints Plug-in Module". If you have agent privileges, you can also specify the required validity period when approving the OCSP responder certificate request in the request queue; the enrollment process for an OCSP responder certificate is manual, and the request gets queued for agent approval.

Before configuring the server to add the OCSP no check extension to OCSP responder certificates, read the general guidelines provided in "OCSPNocheck".

During installation, Certificate Management System automatically creates an instance of the OCSP no check extension policy. See "OCSPNoCheckExt Rule".


Configuration Parameters of OCSPNoCheckExt

In the CMS configuration file, the OCSPNoCheckExt module is identified as
<subsystem>.Policy.impl.OCSPNoCheckExt.class=com.netscape.
certsrv.policy.OCSPNoCheckExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as OCSPNoCheckExt. Figure 4-22 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-22    Parameters defined in the OCSPNoCheckExt module


The configuration shown in Figure 4-22 creates a policy rule named OCSPNoCheckExtForResponderCert, which enforces a rule that the server should set the OCSP no check extension in OCSP responder certificates only.

Table 4-21 provides details for each of these parameters.


Table 4-21    Description of parameters defined in the OCSPNoCheckExt module  

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 adds the OCSP no check extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ocspResponder  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  


OCSPNoCheckExt Rule

The policy rule named OCSPNoCheckExt is an instance of the OCSPNoCheckExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ocspResponder) so that the extension gets added to OCSP responder certificates only.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

For details on individual parameters defined in the rule, see Table 4-21. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



PolicyConstraintsExt Plug-in Module


The PolicyConstraintsExt plug-in module implements the policy constraints extension policy. This policy enables you to configure Certificate Management System to add the Policy Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension, which can be used in CA certificates only, constrains path validation in two ways—either to prohibit policy mapping or to require that each certificate in a path contain an acceptable policy identifier.

The policy constraints extension policy in Certificate Management System allows setting of the policy constraints extension as defined in its X.509 definition. The policy allows you to specify both, requireExplicitPolicy and inhibitPolicyMapping fields. PKIX standard requires that, if present in a CA certificate, the extension must never consist of a null sequence. At least one of the two specified fields must be present. Before configuring the server to add the policy constraints extension to certificates, read the general guidelines provided in "policyConstraints".

During installation, Certificate Management System automatically creates an instance of the policy constraints extension policy. See "PolicyConstraintsExt Rule".


Configuration Parameters of PolicyConstraintsExt

In the CMS configuration file, the PolicyConstraintsExt module is identified as
ca.Policy.impl.PolicyConstraintsExt.class=com.netscape.certsrv.
policy.PolicyConstraintsExt.

In the CMS window, the module is identified as PolicyConstraintsExt. Figure 4-23 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-23    Parameters defined in the PolicyConstraintsExt module


The configuration shown in Figure 4-23 creates a policy rule named PolicyConsExtForCACert, which enforces a rule that the server should set the policy constraints extension in CA certificates only.

Table 4-22 gives details about each of these parameters.


Table 4-22    Description of parameters defined in the PolicyConstraintsExt module  

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 adds the policy constraints extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

reqExplicit
Policy  

Specifies the total number of certificates permitted in the path before an explicit policy is required—that is, the number of CA certificates that can be chained below (subordinate to) the subordinate CA certificate being issued before an acceptable policy is required.

Note that the number you specify affects the number of CA certificates to be used during certificate validation. The chain starts with the end-entity certificate being validated and moving up the chain. (The parameter has no effect if the extension is set in end-entity certificates.)

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension (default).

  • 0 specifies that no subordinate CA certificates are permitted in the path before an explicit policy is required.

  • n must be an integer that is greater than zero. It specifies at the most n subordinate CA certificates are allowed in the path before an explicit policy is required.

Example: 1  

inhibitPolicy
Mapping  

Specifies the total number of certificates permitted in the path before policy mapping is no longer permitted.

Permissible values: -1, 0, or n.

  • -1 specifies that the field should not be set in the extension (default).

  • 0 specifies that no subordinate CA certificates are permitted in the path before policy mapping is no longer permitted.

  • n must be an integer that is greater than zero. It specifies at the most n subordinate CA certificates are allowed in the path before policy mapping is no longer permitted. For example, a value of one indicates that policy mapping may be processed in certificates issued by the subject of this certificate, but not in additional certificates in the path.

Example: -1  


PolicyConstraintsExt Rule

The policy rule named PolicyConstraintsExt is an instance of the PolicyConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is disabled; for the rule to be effective, it must be enabled and configured appropriately.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ca) so that the extension gets added to CA certificates only. PKIX and Federal PKI standards recommend that CA certificates must have this extension and end-entity certificates should have this extension.

  • The extension is marked noncritical.

  • No subordinate CA certificates are permitted in the path before an explicit policy is required (reqExplicitPolicy=0).

  • The inhibitPolicyMapping field is not set in the extension.

For details on individual parameters defined in the rule, see Table 4-22. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



PolicyMappingsExt Plug-in Module


The PolicyMappingsExt plug-in module implements the policy mappings extension policy. This policy enables you to configure Certificate Management System to add the Policy Mappings Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension lists one or more pairs of OIDs, each pair identifying two policy statements of two CAs. The pairing indicates that the corresponding policies of one CA are equivalent to policies of another CA. The extension may be useful in the context of cross-certification.

The PKIX standard suggests that the extension must be marked noncritical and may be supported by CAs and/or applications. If supported, the extension is to be included in CA certificates only. Before configuring the server to add the policy mappings extension to certificates, read the general guidelines provided in "policyMappings".

The policy mappings extension policy in Certificate Management System allows setting of the policy mappings extension as defined in its X.509 definition. The policy allows you to map policy statements of one CA to that of another by pairing the OIDs assigned to their policy statements. (For information on OIDs, see Appendix B "Object Identifiers.") For information on certificate policies, see "CertificatePoliciesExt Plug-in Module".)

Each pair is defined by two parameters, issuerDomainPolicy and subjectDomainPolicy. The pairing indicates that the issuing CA considers the issuerDomainPolicy equivalent to the subjectDomainPolicy of the subject CA. The issuing CA's users may accept an issuerDomainPolicy for certain applications. The policy mapping tells these users which policies associated with the subject CA are equivalent to the policy they accept.

During installation, Certificate Management System automatically creates an instance of the policy mappings extension policy. See "PolicyMappingsExt Rule".


Configuration Parameters of PolicyMappingsExt

In the CMS configuration file, the PolicyMappingsExt module is identified as
ca.Policy.impl.PolicyMappingsExt.class=com.netscape.certsrv.
policy.PolicyMappingsExt.

In the CMS window, the module is identified as PolicyMappingsExt. Figure 4-24 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-24    Parameters defined in the PolicyMappingsExt module


The configuration shown in Figure 4-24 creates a policy rule named PolicyMapExtForCACert, which enforces a rule that the server should set the policy mappings extension in CA certificates only.

Table 4-23 provides details for each of these parameters.


Table 4-23    Description of parameters defined in the PolicyMappingsExt module  

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 adds the policy mappings extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numPolicyMappings  

Specifies the total number of policy mapping (pairs) to be contained or allowed in the extension. Note that each policy mapping represents a pair of policies—specified by policyMap<n>.issuerDomainPolicy and policyMap<n>.subjectDomainPolicy—and each policy in the pair belongs to a specific CA.

You can change the total number of policy pairs by changing the value assigned to this parameter; there's no restriction on the total number of policy pairs you can include in the extension. Each pair is distinguished by <n>, which is an integer derived from the value you assign in this field. For example, if you set the numPolicyMappings parameter to 2, <n> would be 0 and 1.

Permissible values: 0 or n.

  • 0 specifies that no policy pairs can be contained in the extension.

  • n specifies the total number of policy pairs to be included in the extension; it must be a integer greater than zero. The default value is 1.

Example: 2  

policyMap<n>.
issuerDomainPolicy  

Specifies the OID assigned to the policy statement<n> of the issuing CA that you want to map with the policy statement of another CA.

Permissible values: Any valid OID specified in dot-separated numeric component notation (see the example). The OID that you specify should be in the registered subtree of IDs reserved for your company's use. 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 Identifiers" for information on allocating private OIDs.

Example: 1.2.3.4.5  

policyMap<n>.
subjectDomainPolicy  

Specifies the OID assigned to the policy statement<n> of the subject CA that corresponds to the policy statement of the issuing CA.

Permissible values: Any valid OID specified in dot-separated numeric component notation (see the example).

Example: 6.7.8.9.10  


PolicyMappingsExt Rule

The rule named PolicyMappingsExt is an instance of the PolicyMappingsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ca) so that the extension gets added to CA certificates only.

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The number of policy mappings is set to 1 (numPolicyMappings=1) indicating that a pair of policies are to be mapped.

  • The fields for entering the OIDs for policies that are to be mapped are left blank for you to enter the appropriate values.

For details on individual parameters defined in the rule, see Table 4-23. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.



PrivateKeyUsagePeriodExt Plug-in Module


The PrivateKeyUsagePeriodExt plug-in module implements the private key usage period extension policy. This policy enables you to configure Certificate Management System to add the Private Key Usage Period Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension allows the certificate issuer to specify a different validity period for the private key than the one specified for the corresponding certificate. The extension is intended for use with digital signature keys.

The PKIX standard recommends against the use of this extension. The standard also recommends that CAs conforming to the standard must not generate certificates with private key usage period extensions that are marked critical. For general guidelines on setting this extension in certificates, see "privateKeyUsagePeriod".

The private key usage period extension policy in Certificate Management System allows setting of the private key usage period extension as defined in its X.509 definition. The policy enables you to specify values for the notBefore and notAfter components. When included in a certificate, the notBefore and notAfter components define the time before and after which the private key associated with the certificate should not be used to sign objects.


Configuration Parameters of PrivateKeyUsagePeriodExt

In the CMS configuration file, the PrivateKeyUsagePeriodExt module is identified as <subsystem>.Policy.impl.PrivateKeyUsagePeriodExt.class=
com.netscape.certsrv.policy.PrivateKeyUsagePeriodExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as PrivateKeyUsagePeriodExt. Figure 4-25 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-25    Parameters defined in the PrivateKeyUsagePeriodExt module


The configuration shown in Figure 4-25 creates a policy rule named PrivKeyUsagePrdExtForClientCert, which enforces a rule that the server should set the private key usage period extension in client certificates.

Table 4-24 provides details for each of these parameters.


Table 4-24    Description of parameters defined in the PrivateKeyUsagePeriodExt module  

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 adds the private key usage period extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

notBefore  

Specifies the date on which the validity period for the private key associated with the certificate begins.

Permissible values: A valid date specified in the MM/DD/YYYY format.

Example: 12/25/2000  

notAfter  

Specifies the date on which the validity period for the private key associated with the certificate ends.

Permissible values: A valid date specified in the MM/DD/YYYY format.

Example: 12/25/2001  



RemoveBasicConstraintsExt Plug-in Module


The RemoveBasicConstraintsExt plug-in module implements the remove basic constraints extension policy. This policy, if enabled, can detect the presence of Basic Constraints extension in a certificate request and remove it. For details about the Basic Constraints extension, see "BasicConstraintsExt Plug-in Module".

The policy can be useful in certain enrollment scenarios. For example, enrollment requests from customized clients that can generate CRMF requests can include extensions, including the Basic Constraints extension, and the policy can detect the presence of the Basic Constraints extension and remove it.


Configuration Parameters of RemoveBasicConstraintsExt

In the CMS configuration file, the RemoveBasicConstraintsExt module is identified as ca.Policy.impl.RemoveBasicConstraintsExt.class=
com.netscape.certsrv.policy.RemoveBasicConstraintsExt.

In the CMS window, the module is identified as RemoveBasicConstraintsExt. Figure 4-26 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-26    Parameters defined in the RemoveBasicConstraintsExt module


The configuration shown in Figure 4-26 creates a policy rule named RemoveBasicConstraintsExtForClientCerts, which enforces a rule that the Basic Constraints extension be removed from all client certificate requests.

Table 4-25 provides details for each of these parameters.


Table 4-25    Description of parameters defined in the RemoveBasicConstraintsExt module  

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 checks certificate requests for Basic Constraints extension and removes it.

  • If you disable the rule, the server does not check the requests for Basic Constraints extension; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  



SubjectAltNameExt Plug-in Module


The SubjectAltNameExt plug-in module implements the subject alternative name policy. This policy enables you to configure Certificate Management System to add the Subject Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension enables you to bind additional identities—such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI)—to the subject of the certificate.

The standard suggests that if the certificate subject field contains an empty sequence, then the subject alternative name extension must contain the subject's alternative name and that the extension be marked critical. For general guidelines on setting the subject alternate name extension in certificates, see "subjectAltName".

The subject alternative name extension policy in Certificate Management System enables you to include values of certificate-request attributes in the extension. You can include any number of attributes as long as the attribute values conform to any of the supported general-name forms: rfc822Name, X.500 directory name, DNS name, EDI party name, URL, IP address, object identifier, and Other name.

Attributes in a certificate request are filled in by servlets from the HTTP input forms used for request submission. Some attributes, such as passwords typed in the form are not stored in the request. Other attributes regarding the end entity, such as the user ID, are set on the request after successful authentication. The servlets can also set additional attributes related to the certificate content on the request; for example, in automated-enrollment methods, some attributes may be read from the authentication directory and set in the request as authenticated attributes.

If you're using any of the directory-based authentication methods, you can configure Certificate Management System to retrieve values for any string and byte attributes from the directory and set them in the certificate request during authentication—you specify these attributes by entering them in the ldapStringAttributes and ldapByteAttributes fields defined in the automated enrollment modules. For more information, see Table 1-2, Table 1-3, and Table 1-4.

Note that all data related to an end entity is gathered at the servlet level and set on the request before the request is passed to the policy subsystem.

In general, you can configure which attributes should or shouldn't be stored in the request; for example, you can exclude sensitive attributes such as passwords from getting stored in the request with the help of the parameter named dontSaveHttpParams defined in the CMS configuration file. For details on using this parameter, see the description for HTTP_PARAMS in section "JavaScript Used By All Interfaces" of CMS Customization Guide. You can also distinguish the attributes based on their origin—that is, whether they originated from the enrollment form or where added to the request during the authentication process. Authenticated attributes have AUTH_TOKEN as prefix (for example, AUTH_TOKEN.mail) and non-authenticated attributes such as the ones that come from the HTTP input have HTTP_PARAMS as prefix (for example, HTTP_PARAMS.csrRequestorEmail).

If enabled, the subject alternative extension policy checks the certificate request for configured attributes. If the request contains an attribute, the policy reads its value and sets it in the extension. This way, the extension that gets to added to certificates contains all the configured attributes.

During installation, Certificate Management System automatically creates an instance of the subject alternative name extension policy. See "SubjectAltNameExt Rule".


Configuration Parameters of SubjectAltNameExt

In the CMS configuration file, the SubjectAltNameExt module is identified as
<subsystem>.Policy.impl.SubjectAltNameExt.class=com.netscape.
certsrv.policy.SubjectAltNameExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as SubjectAltNameExt. Figure 4-27 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-27    Parameters defined in the SubjectAltNameExt module


The configuration shown in Figure 4-27 creates a policy rule named SubAltNameExtForClientCert, which enforces a rule that the alternative name of the certificate's subject must be derived from the mail attribute of subject's entry in the authentication directory and that the server should set the subject alternative name extension only in client certificates.

Table 4-26 provides details for each of these parameters.


Table 4-26    Description of parameters defined in the SubjectAltNameExt module  

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 adds the subject alternative name extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numGeneralNames  

Specifies the total number of alternative names or identities permitted in the extension. Note that each name has a set of configuration parameters—generalName<n>.requestAttr and generalName<n>.generalNameChoice—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 of this parameter; 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 numGeneralNames 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 8.

Example: 2  

generalName<n>.
requestAttr  

Specifies the request attribute whose value is to be included in the extension. The attribute value must conform to any of the supported general-name types (specified by the generalName<n>.generalNameChoice parameter). If the server finds the attribute in the request, it sets the attribute value in the extension and then adds the extension to certificates specified by the predicate parameter. If you specify multiple attributes and if none of the attributes are present in the request, the server does not add the subject alternative name extension to certificates.

Permissible values: A request attribute included in the certificate request.

Example: AUTH_TOKEN.mail  

generalName<n>.
generalNameChoice  

Specifies the general-name type for the request attribute.

Permissible values: rfc822Name, directoryName, dNSName, ediPartyName, URL, iPAddress, OID, or otherName.

  • Select rfc822Name if the request-attribute value is an Internet mail address in the local-part@domain format (default). For example, jdoe@siroe.com.

  • Select directoryName if the request-attribute value is an X.500 directory name, similar to the subject name in a certificate. For example,
    CN=Jane Doe, OU=Sales Dept, O=Siroe Corp, C=US.

  • Select dNSName if the request-attribute value is a DNS name. For example, corpDirectory.siroe.com.

  • Select ediPartyName if the request-attribute value is a EDI party name. For example, Siroe Corporation.

  • Select URL if the request-attribute value is a non-relative URI that includes both a scheme (for example, http) and a fully qualified domain name or IP address of the host. For example, http://hr.siroe.com.

  • Select iPAddress if the request-attribute value is a valid IP address specified in dot-separated numeric component notation. For example, 128.21.39.40.

  • Select OID if the request-attribute value is a unique, valid OID specified in the dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99.

  • Select otherName if the request-attribute value is the absolute path to the file that contains the base-64 encoded string of the subject alternative name. For example, /usr/netscape/server4/ext/san/othername.txt.

Example: rfc822Name  


SubjectAltNameExt Rule

The policy rule named SubjectAltNameExt is an instance of the SubjectAltNameExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is left blank so that the extension gets added to all certificates the server issues. (PKIX and Federal PKI standards recommend that CA certificates must have this extension and end-entity certificates should have this extension.)

  • The extension is marked noncritical (to comply with the PKIX recommendation).

  • The rule is configured to include at the most three alternative names in the extension (numGeneralNames=3).

  • The first alternative name is the value of the mail attribute in the certificate subject's directory entry (generalName0.requestAttr=AUTH_TOKEN.mail) and the name is in the rfc822Name format (generalName0.generalNameChoice=rfc822Name).

  • The second alternative name is the value of the mailalternateaddress attribute in the certificate subject's directory entry (generalName1.requestAttr=AUTH_TOKEN.mailalternateaddress) and the name is in the rfc822Name format (generalName1.generalNameChoice=rfc822Name).

  • The third alternative name is the value of an HTTP input parameter csrRequestorEmail included in the certificate request (generalName2.requestAttr=HTTP_PARAMS.csrRequestorEmail) and the name is in rfc822Name format (generalName2.generalNameChoice=rfc822Name).

For details on individual parameters defined in the rule, see Table 4-26. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.

Before you edit the default rule, you should read the additional details about the attributes that are set in the default policy rule.

The first two attributes, AUTH_TOKEN.mail and AUTH_TOKEN.mailalternateaddress, are standard LDAP attributes typically used for storing end users' email addresses in an LDAP directory. These attributes enable you to include a user's email address as an alternative name in the certificate. Remember that you need to specify the LDAP attribute for users' email addresses as a part of configuring the server to use a specific directory for authentication—which means for the default rule to set end users' email addresses in the subject alternative name extension, you must ensure the following:

  • The server is configured for directory-based, directory- and PIN-based, or NIS server based (using directory attributes for forming subject names) enrollment; that is, you have created and configured an authentication instance.

  • The ldapStringAttributes parameter in the authentication instance is set to mail or mailalternateaddress, or to both.

The third attribute, HTTP_PARAMS.csrRequestorEmail, is the email component of the subject name in an enrollment request—it is an HTTP input value that gets added to the request when a user uses the manual enrollment form; for details, see "Enrollment Forms".

If you enable the default policy rule, the server automatically checks the certificate request for attributes AUTH_TOKEN.mail, AUTH_TOKEN.mailalternateaddress, and HTTP_PARAMS.csrRequestorEmail. If the server finds any of the attributes, it sets the attribute value in the extension and then adds the extension to certificates specified by the predicate parameter. If none of the attributes are in a request, the server does not add the subject alternative name extension to the certificate.



SubjectDirectoryAttributesExt Plug-in Module


The SubjectDirectoryAttributesExt plug-in module implements the subject directory attributes extension policy. This policy enables you to configure Certificate Management System to add the Subject Directory Attributes Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to specify any desired directory attribute values for the subject of the certificate.

As per the PKIX standard, inclusion of this extension in certificates is not essential; the standard suggests that the extension may be used in local environments. For general guidelines on setting the subject directory attributes extension, see "subjectDirectoryAttributes".

The subject directory attributes extension policy in Certificate Management System allows you to include up to three directory attributes in the extension. For each attribute that you want to include in the extension, you need to specify the attribute name and its value—the name must be the X.500 directory attribute name itself and the attribute value can be derived from the request or directly entered in the policy configuration as a string value.

The list of directory attributes supported by default are shown as permissible values for the attribute<n>.attributeName parameter explained in Table 4-27. You can extend the list of attributes supported by the policy by defining new X.500 directory attributes. For details on defining new attributes, see "Extending Attribute Support".

Note that, during installation, Certificate Management System does not create an instance of the subject directory attributes extension policy. If you want the server to add this extension to certificates, you must create an instance of the SubjectDirectoryAttributesExt module and configure it. For instructions, see section "Step 4. Add New Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of SubjectDirectoryAttributesExt

In the CMS configuration file, the SubjectDirectoryAttributesExt module is identified as <subsystem>.Policy.impl.SubjectDirectoryAttributesExt.
class=com.netscape.certsrv.policy.SubjectDirectoryAttributesExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as SubjectDirectoryAttributesExt. Figure 4-28 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-28    Parameters defined in the SubjectDirectoryAttributesExt module


The configuration shown in Figure 4-28 creates a policy rule named SubDirAttrForClientCert, which enforces a rule that the server should set the subject directory attributes extension in client certificates.

Table 4-27 provides details for each of these parameters.


Table 4-27    Description of parameters defined in the SubjectDirectoryAttributesExt module  

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 adds the subject directory attributes extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==client AND HTTP_PARAMS.OU==Engineering  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

numAttributes  

Specifies the total number of directory attributes to be contained or allowed in the extension. Note that each attribute has a name (or OID) and value and you must specify appropriate values for both; otherwise the policy rule will return an error.

You can configure the server to include up to three attributes in the extension. By default, this field is set to its maximum value, 3, and the UI shows fields for configuring three attributes. You can change the total number of attributes by changing the value of this parameter. 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 numAttributes parameter to 2, <n> would be 0 and 1.

Permissible values: 1, 2, or 3. The default value is 3.

Example: 1  

attribute<n>.attributeName  

Specifies the name of the directory attribute whose value is to be included in the extension.

Permissible values: TITLE, O, OU, L, E, C, GIVENNAME, DC, UID, CN, UNSTRUCTUREDNAME, GENERATIONQUALIFIER, ST, DNQUALIFIER, SN, MAIL, UNSTRUCTUREDADDRESS, STREET, SERIALNUMBER, and INITIALS. The list may show any additional attributes that you may have added.

Example: TITLE  

attribute<n>.whereToGetValue  

Specifies from where to get the value for the selected directory attribute.

Permissible values: Request Attribute or Fixed Value.

  • Select Request Attribute if you want the server to read the value from the request attribute.

  • Select Fixed Value if you want to specify a fixed value for the attribute.

Note that both the options require you to enter the value for the attribute in the attribute<n>.value field. The server will set the extension with this value in all certificates specified by the predicate parameter.

Example: Fixed Value  

attribute<n>.value  

Specifies the value for the directory attribute to be included in the extension.

Permissible value: A string value for the attribute selected.

Example: Member of Technical Staff  



SubjectKeyIdentifierExt Plug-in Module


The SubjectKeyIdentifierExt plug-in module implements the subject key identifier policy. This policy enables you to configure Certificate Management System to add the Subject Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to identify certificates that contain a particular public key—that is, the extension is used to uniquely identify a certificate from among several that have the same subject name.

Typically, the subject key identifier extension is used in CA certificates as it helps determine which CA key is being certified in a CA certificate. To facilitate chain building, you should consider adding this extension to conforming subordinate CA certificates (subordinate Certificate Managers' CA signing certificates) issued by Certificate Management System. You may also want to consider adding this extension to other or all certificates. For example, if added to end-entity certificates, the extension provides a means for identifying certificates containing the particular public key used in an application. If an end entity has multiple certificates, especially from multiple CAs, the subject key identifier provides a means to quickly identify the set of certificates that contain a particular public key.

For general guidelines on setting the subject key identifier extension, see "subjectKeyIdentifier".

The subject key identifier extension policy in Certificate Management System allows setting of the subject key identifier extension as defined in its X.509 definition. It enables you to specify the method for forming the Key Identifier.

By default, the policy supports three types of methods for deriving the Key Identifier; the default methods for forming the Key Identifier are based on PKIX recommendations as defined in section 4.2.1.2. They are as follows:

  • 20 byte (160 bit) SHA-1 hash of the BIT STRING of Subject Public Key.

  • A type field value of 0100 followed by 60 least significant bits of the SHA-1 hash of the Subject Public Key.

  • 20 byte (160 bit) SHA-1 hash of the Subject Public Key Info. This is how Netscape Communicator generates a Key Identifier (but is not necessary to be compatible with the Communicator).

You can also customize the method for deriving the Key Identifier by subclassing the policy and overriding the following method:

formKeyIdentifier(X509CertInfo certInfo, IRequest req)

For details, check the CMS SDK installed at this location:

<server_root>/cms_sdk/cms_jdk/javadocs

You may also want to check the CMS samples installed here:

<server_root>/cms_sdk/cms_jdk/samples/policies

If enabled, the policy adds a Subject Key Identifier Extension to an enrollment request if the extension does not already exist. If the extension exists in the request, for example from a CRMF request, the policy replaces the extension. In case of manual enrollments, after an agent approves the enrollment request, the policy accepts any Subject Key Identifier Extension that is already there.

During installation, Certificate Management System automatically creates an instance of the subject key identifier extension policy. See "SubjectKeyIdentifierExt Rule".


Configuration Parameters of SubjectKeyIdentifierExt

In the CMS configuration file, the SubjectKeyIdentifierExt module is identified as <subsystem>.Policy.impl.SubjectKeyIdentifierExt.class=
com.netscape.certsrv.policy.SubjectKeyIdentifierExt, where <subsystem> is ca or ra (prefix identifying the subsystem).

In the CMS window, the module is identified as SubjectKeyIdentifierExt. Figure 4-29 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 4-29    Parameters defined in the SubjectKeyIdentifierExt module


The configuration shown in Figure 4-29 creates a policy rule named SubKeyIDExtForAllCert, which enforces a rule that the server should set the subject key identifier extension in all certificates.

Table 4-28 provides details for each of these parameters.


Table 4-28    Description of configuration parameters defined in the SubjectKeyIdentifierExt module  

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 adds the subject key identifier extension to certificates specified by the predicate parameter.

  • If you disable the rule, the server does not add the extension to certificates; it ignores the values in the remaining fields.

 

predicate  

Specifies the predicate expression for this rule. If you want this rule to be applied to all certificate requests, leave the field blank (default). To form a predicate expression, see section "Using Predicates in Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

Example: HTTP_PARAMS.certType==ca  

critical  

Specifies whether the extension should be marked critical or noncritical in certificates specified by the predicate parameter. 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).  

KeyIdentifierType  

Specifies the method for deriving Key Identifier.

Permissible values: SHA1, TypeField, or SpkiSHA1.

  • SHA1 specifies that the key identifier must be derived as a 20 byte (160 bit) SHA-1 hash of the BIT STRING of Subject Public Key (default).

  • TypeField specifies that the key identifier must be derived as a type field value of 0100 followed by 60 least significant bits of the SHA-1 hash of the Subject Public Key.

  • SpkiSHA1 specifies that the key identifier must be derived as a 20 byte (160 bit) SHA-1 hash of the Subject Public Key Info.

Example: SHA1  


SubjectKeyIdentifierExt Rule

The policy rule named SubjectKeyIdentifierExt is an instance of the SubjectKeyIdentifierExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:

  • The rule is enabled.

  • The predicate expression is set (predicate=HTTP_PARAMS.certType==ca) so that the extension gets added to CA certificates only. (PKIX and Federal PKI standards recommend that CA certificates must have this extension and end-entity certificates should have this extension.)

  • The key identifier is a 20 byte (160 bit) SHA-1 hash of the BIT STRING of Subject Public Key (KeyIdentifierType=SHA1).

For details on individual parameters defined in the rule, see Table 4-28. It is important that you review this rule and make the appropriate changes required by your PKI setup. For example, if you're planning to issue multiple certificates to an end entity and want to assist applications in identifying the appropriate end-entity certificate, you should consider modifying the predicate expression to add this extension to all end-entity certificates. For instructions, see section "Step 2. Modify Existing Policy Rules" in Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide. For instructions on adding additional instances, see section "Step 4. Add New Policy Rules" in the same chapter.


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated April 02, 2001