Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling CMS Instances
Chapter 5: Starting and Stopping CMS Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Authentication Modules for End-Entity Enrollment
Chapter 11: Using the PIN Generator Tool
Chapter 12: Configuring Authentication for End Users
Chapter 13: Developing Custom Authentication Modules
PART 5: Job Scheduling and Notification
Chapter 14: Introduction to Job Scheduling and Notifications
Chapter 15: Configuring Schedulable Jobs
PART 6: Policies
Chapter 16: Introduction to Policy
Chapter 17: Constraints-Specific Policy Modules
Chapter 18: Extension-Specific Policy Modules
Chapter 19: Configuring a Subsystem's Policies
PART 7: Publishing
Chapter 20: Introduction to Publishing Certificates and CRLs
Chapter 21: Modules for Publishing Certificates and CRLs
Chapter 22: Configuring a Certificate Manager for Publishing
PART 8: Agent and End-Entity Interfaces
Chapter 23: Introduction to End-Entity and Agent Interfaces
Chapter 24: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 25: Introduction to Logs
Chapter 26: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 27: Issuing and Managing End-Entity Certificates
Chapter 28: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Netscape Certificate Management System Administrator's Guide: Extension-Specific Policy Modules
Previous Next Contents Index Bookshelf


Chapter 18 Extension-Specific Policy Modules

Certificate Management System comes with a set of extension-specific policy plug-in modules that enable you to add X.509 certificate extensions to the 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:


Certificate Extensions
Since its initial publication, the X.509 standard for certificate formats has been amended to include additional information within a certificate. Version 3, the latest version, allows you to add additional information as certificate extensions. For example, Netscape applications (Netscape Navigator 3.0 or higher, and Enterprise Server 2.01 or higher) support an extension that specifies the type of certificate issued (such as client, server, or object signing).

The extensions defined for X.509 v3 certificates enable you to associate additional attributes with users or public keys and manage the certification hierarchy. The Internet X.509 Public Key Infrastructure Certificate and CRL Profile (see http://www.ietf.org/rfc/rfc2459.txt) recommends a set of extensions to be used in Internet certificates (and standard locations for certificate or CA information). These extensions are called standard extensions.

The standard also suggests that you can define your own extensions and include them in certificates you issue. These extensions are called private, proprietary, or custom extensions and they carry information unique to your organization or business. Keep in mind that applications may not able to validate certificates that contain private, critical extensions, thus preventing the use of these certificates in a general context.

Note Some explanations in this chapter make reference to Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules (DER). These are specified in the CCITT Recommendations X.208 and X.209. For a quick summary of ASN.1 and DER, see A Layman's Guide to a Subset of ASN.1, BER, and DER, which is available at RSA Laboratories' web site (http://www.rsa.com).

Structure of Certificate Extensions

In RFC 2459, an X.509 certificate extension is defined as follows:

Extension ::= SEQUENCE {

Which means, a certificate extension consists of the following:

Examples of standard extensions defined in the X.509 v3 standard include the following:

Note that not all applications support certificates with version 3 extensions. Applications that do support these extensions may not be able to interpret some or all of these specific extensions.

Sample Certificate Extensions

The following is an example of the section of a certificate containing X.509 v3 extensions. (Certificate Management System can display certificates in human-readable format, as shown here.) As shown in the example, certificate extensions appear in sequence and only one instance of a particular extension may appear in a particular certificate; for example, a certificate may contain only one subject key identifier extension. Note that certificates that support these extensions have the version 0x2 (which corresponds to version 3).

Certificate:
Data:
Version: v3 (0x2)
...
Extensions:
Identifier: Certificate Type
Critical: no
Certified Usage:
SSL CA
Identifier: Subject Key Identifier
Critical: no
Value:
2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad
Identifier: Authority Key Identifier
Critical: no
Key Identifier:
2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad

Object Identifier

An object identifier (OID) is a string of numbers identifying a unique object, for example, a certificate extension or a company's certificate practice statement. For general information on OIDs, see the information at this URL:

http://www.alvestrand.no/objectid/

OIDs are controlled by the International Standards Organization (ISO) registration authority. In some cases, this authority is delegated by ISO to regional registration authorities. For example, in the United States, the American National Standards Institute (ANSI) manages this registration.

Registration of Object Identifiers

To promote interoperatability, the PKIX standard recommends that all objects (such as extensions and policy statements) that appear in certificates that will be used in networks shared by other organizations should be included in the form of OIDs. If you plan to issue certificates that will be used in such networks, you should register your object identifier prefixes with the appropriate registration authority. For example, assume you want to add a custom extension that points to a certificate practice statement (CPS) of your company. To implement this, you need to compose the policy statement you want to include in the extension, define an OID for the policy statement, and configure Certificate Management System with the OID so that it can add that to the certificate it issues.

The use of an OID registered to another organization or the failure to register an OID may carry legal consequences, depending on context. Registration may be subject to fees. For more information, you should contact the appropriate registration authority.

To define or assign OIDs for your objects, you must know your company's arc, which is an OID for a private enterprise. If your company doesn't have an arc, it needs to get one. This URL contains information on registering for a company arc:

http://www.isi.edu/cgi-bin/iana/enterprise.pl

To understand why you need to have a company arc, check the information at this site:

http://www.alvestrand.no/objectid/2.16.840.1.113730.1.13.html

The site contains information on Netscape-defined OID for an extension named Netscape Certificate Comment. Note that the OID assigned to this extension is hierarchical and it includes the Netscape company arc, which is 2.16.840.1.113730. Every OID Netscape owns has this prefix.

When determining whether to add 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 (including the optional qualifiers, if any), or else it must reject the certificate. Since it's unlikely that all applications will be able to interpret your company's extensions (embedded in the form of OIDs), the PKIX standard recommends that the extension be always marked noncritical. For general guidelines on setting extensions in certificates, see "Certificate Extensions" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.


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 18.1) lists all the modules that are registered with a CMS instance.

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 "Certificate Extensions" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

Figure 18.1 Extension policy modules registered with a Certificate Manager

Table 18.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:

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 "Policy Processor"). 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 18.1 Default extension-specific policy plug-in modules

Plug-in module
Function
AuthInfoAccessExt
Adds the Authority Information Access extension to certificates. For details, see "Authority Information Access Extension Policy".
AuthorityKeyIdentifierExt
Adds the Authority Key Identifier extension to certificates. For details, see "Authority Key Identifier Extension Policy".
BasicConstraintsExt
Adds the Basic Constraints extension to certificates. For details, see "Basic Constraints Extension Policy".
CertificatePoliciesExt
Adds the Certificate Policies extension to certificates. For details, see "Certificate Policies Extension Policy".
CertificateRenewalWindowExt
Adds the Certificate Renewal Window extension to certificates. For details, see "Certificate Renewal Window Extension Policy".
CertificateScopeOfUseExt
Adds the Certificate Scope of Use extension to certificates. For details, see "Certificate Scope of Use Extension Policy".
CRLDistributionPointsExt
Adds the CRL Distribution Points extension to certificates. For details, see "CRL Distribution Points Extension Policy".
ExtendedKeyUsageExt
Adds the Extended Key Usage extension to certificates. For details, see "Extended Key Usage Extension Policy".
GenericASN1Ext
Adds ASN.1 type custom extension to certificates. For details, see "Generic ASN.1 Extension Policy".
IssuerAltNameExt
Adds the Issuer Alternative Name extension to certificates. For details, see "Issuer Alternative Name Extension Policy".
KeyUsageExt
Adds the Key Usage extension to certificates. For details, see "Key Usage Extension Policy".
NameConstraintsExt
Adds the Name Constraints extension to certificates. For details, see "Name Constraints Extension Policy".
NSCCommentExt
Adds the Netscape Certificate Comment extension to certificates. For details, see "Netscape Certificate Comment Extension Policy".
NSCertTypeExt
Adds the Netscape Certificate Type extension to certificates. For details, see "Netscape Certificate Type Extension Policy".
OCSPNoCheckExt
Adds the OCSP No Check extension to certificates. For details, see "OCSP No Check Extension Policy".
PolicyConstraintsExt
Adds the Policy Constraints extension to certificates. For details, see "Policy Constraints Extension Policy".
PolicyMappingsExt
Adds the Policy Mappings extension to certificates. For details, see "Policy Mappings Extension Policy".
PrivateKeyUsagePeriodExt
Adds the Private Key Usage Period extension to certificates. For details, see "Private Key Usage Period Extension Policy".
SubjectAltNameExt
Adds the Subject Alternative Name extension to certificates. For details, see "Subject Alternative Name Extension Policy".
SubjectDirectoryAttributesExt
Adds a Subject Directory Attributes extension to certificates. For details, see "Subject Directory Attributes Extension Policy".
SubjectKeyIdentifierExt
Adds the Subject Key Identifier extension to certificates. For details, see "Subject Key Identifier Extension Policy".

As indicated in Table 18.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:

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/sdkdocs

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/samples/policy and
<server_root>/cms_sdk/samples/exttools

For instructions to configure a Certificate Manager and Registration Manager to use one or more of the policy modules, see "Configuring a Subsystem's Policies".


Authority Information Access Extension Policy
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 the application validating the 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 the CA; the CRL Distribution Points extension explained in "CRL Distribution Points Extension Policy" 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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 two access methods:

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 "Supported Methods for Verifying Revocation Status of Certificates".

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.

Unlike some of the other policy modules, Certificate Management System does not create an instance of the AuthInfoAccessExt module during installation. If you want the server to add this extension to certificates, you must create an instance of the said module and configure it. For instructions, see "Step 4. Add New Policy Rules").

AuthInfoAccessExt Module

The Java class that implements the authority information access extension policy is as follows:

com.netscape.certsrv.policy.AuthInfoAccessExt

Figure 18.2 shows how the configurable parameters for the AuthInfoAccessExt module are displayed in the CMS window.

Figure 18.2 Parameters defined in the AuthInfoAccessExt module

The configuration shown in Figure 18.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 18.2 gives details about the configurable parameters defined in the AuthInfoAccessExt module.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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:

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.

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.








Authority Key Identifier Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 "Subject Key Identifier Extension Policy".

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:

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

AuthorityKeyIdentifierExt Module

The Java class that implements the authority key identifier extension policy is as follows:

com.netscape.certsrv.policy.AuthorityKeyIdentifierExt

Figure 18.3 shows how the configurable parameters for the AuthorityKeyIdentifierExt module are displayed in the CMS window.

Figure 18.3 Parameters defined in the AuthorityKeyIdentifierExt module

The configuration shown in Figure 18.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 18.3 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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:

For details on individual parameters defined in the rule, see Table 18.3. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Basic Constraints Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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".

BasicConstraintsExt Module

The Java class that implements the basic constraints extension policy is as follows:

com.netscape.certsrv.policy.BasicConstraintsExt

Figure 18.4 shows how the configurable parameters for the BasicConstraintsExt module are displayed in the CMS window.

Figure 18.4 Parameters defined in the BasicConstraintsExt module

The configuration shown in Figure 18.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 18.4 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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

Example: 2

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.

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:

For details on individual parameters defined in the rule, see Table 18.4. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Certificate Policies Extension Policy
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 "Object Identifier". 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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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

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

CertificatePoliciesExt Module

The Java class that implements the certificate policies extension policy is as follows:

com.netscape.certsrv.policy.CertificatePoliciesExt

Figure 18.5 shows how the configurable parameters for the CertificatePoliciesExt module are displayed in the CMS window.

Figure 18.5 Parameters defined in the CertificatePoliciesExt module

The configuration shown in Figure 18.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 18.5 gives details about each of these parameters.

Table 18.5 Description of parameters defined in the CertificatePoliciesExt module

Parameter
Description
enable
Specifies whether the rule is enabled or disabled.

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 "Using Predicates in Policy Rules".

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 "Object Identifier" 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

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


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

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:

For details on individual parameters defined in the rule, see Table 18.5. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules". 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.


Certificate Renewal Window Extension Policy
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 "Authentication of End Users During Certificate Renewal".

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:

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 (see "Step 4. Add New Policy Rules").

CertificateRenewalWindowExt Module

The Java class that implements the certificate renewal window extension policy is as follows:

com.netscape.certsrv.policy.CertificateRenewalWindowExt

Figure 18.6 shows how the configurable parameters for the CertificateRenewalWindowExt module are displayed in the CMS window.

Figure 18.6 Parameters defined in the CertificateRenewalWindowExt module

The configuration shown in Figure 18.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 18.6 gives details about each of these parameters.

Table 18.6 Description of parameters defined in the CertificateRenewalWindowExt module

Parameter
Description
enable
Specifies whether the rule is enabled or disabled.

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 "Using Predicates in Policy Rules".

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.

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.

Example: 705D


Certificate Scope of Use Extension Policy
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 (see "Step 4. Add New Policy Rules").

CertificateScopeOfUseExt Module

The Java class that implements the certificate scope of use extension policy is as follows:

com.netscape.certsrv.policy.CertificateScopeOfUseExt

Figure 18.7 shows how the configurable parameters for the CertificateScopeOfUseExt module are displayed in the CMS window.

Figure 18.7 Parameters defined in the CertificateScopeOfUseExt module

The configuration shown in Figure 18.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 18.7 gives details about each of these parameters.

Table 18.7 Description of parameters defined in the CertificateScopeOfUseExt module

Parameter
Description
enable
Specifies whether the rule is enabled or disabled.

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 "Using Predicates in Policy Rules".

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.

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.

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.








entry<n>_port_
number

Specifies the port number.

Example: 8888


CRL Distribution Points Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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/samples/policy/CRLDistributionPoints

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

CRLDistributionPointsExt Module

The Java class that implements the CRL distribution points extension policy is as follows:

com.netscape.certsrv.policy.CRLDistributionPointsExt

Figure 18.8 shows how the configurable parameters for the CRLDistributionPointsExt module are displayed in the CMS window.

Figure 18.8 Description of parameters defined in the CRLDistributionPointsExt module

The configuration shown in Figure 18.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 18.8 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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:

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.

Example: URI

pointType<n>
Specifies the general-name type for the CRL distribution point that you want to include in the extension. (The types defined here correspond to the general-name forms explained in "General-Name Forms".)

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

Example: directoryName

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

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

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:

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.

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:

For details on individual parameters defined in the rule, see Table 18.8. It is important that you review this rule and make the appropriate changes required by your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules". 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.


Extended Key Usage Extension Policy
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 "Key Usage Extension Policy".)

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 18.9 lists the usages defined by PKIX for use with the extended key usage extension.

Table 18.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

For general guidelines on setting the extended key usage extension in certificates, see "extKeyUsage" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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".

ExtendedKeyUsageExt Module

The Java class that implements the extended key usage extension policy is as follows:

com.netscape.certsrv.policy.ExtendedKeyUsageExt

Figure 18.9 shows how the configurable parameters for the ExtendedKeyUsageExt module are displayed in the CMS window.

Figure 18.9 Parameters defined in the ExtendedKeyUsageExt module

The configuration shown in Figure 18.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 18.10 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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 18.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 "Object Identifier" 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:

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 18.10. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".

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:

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 "Publishing of CRLs to an Online Validation Authority". 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 "Authority Information Access Extension Policy".

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:

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 "OCSP No Check Extension Policy".


Generic ASN.1 Extension Policy
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 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 18.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".

GenericASN1Ext Module

The Java class that implements the generic extension policy is as follows:

com.netscape.certsrv.policy.GenericASN1Ext

Figure 18.10 shows how the configurable parameters for the GenericASN1Ext module are displayed in the CMS window.

Figure 18.10 Parameters defined in the GenericASN1Ext module

The configuration shown in Figure 18.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") 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 18.11 describes the configurable parameters of the generic ASN.1 extension policy module.

Table 18.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).

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 "Using Predicates in Policy Rules".

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 "Object Identifier" 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:
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.

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

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.

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:

For details on individual parameters defined in the rule, see Table 18.11. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Issuer Alternative Name Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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:

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 (see "Step 4. Add New Policy Rules").

IssuerAltNameExt Module

The Java class that implements the issuer alternative name extension policy is as follows:

com.netscape.certsrv.policy.IssuerAltNameExt

Figure 18.11 shows how the configurable parameters for the IssuerAltNameExt module are displayed in the CMS window.

Figure 18.11 Parameters defined in the IssuerAltNameExt module

The configuration shown in Figure 18.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 18.12 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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.

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.








Key Usage Extension Policy
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 18.13 lists the bits and their designated purposes.

Table 18.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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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

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 18.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 "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".

Additionally, as you'll notice in Figure 18.13 through Figure 18.17, the default enrollment forms provided for requesting various types of certificates (see "Forms for Certificate Enrollment") 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 18.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.

KeyUsageExt Module

The Java class that implements the key usage extension policy is as follows:

com.netscape.certsrv.policy.KeyUsageExt

Figure 18.12 shows how the configurable parameters for the KeyUsageExt module are displayed in the CMS window.

Figure 18.12 Parameters defined in the KeyUsageExt module

The configuration shown in Figure 18.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 18.15 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 "Certificate Manager's Key Pairs and Certificates". By default, the rule is configured as follows:

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 "Registration Manager's Key Pairs and Certificates". By default, the rule is configured as follows:

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:

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:

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 18.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 18.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 "Netscape Certificate Type Extension Policy".)

Figure 18.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:

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:


Name Constraints Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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".

NameConstraintsExt Module

The Java class that implements the name constraints extension policy is as follows:

com.netscape.certsrv.policy.NameConstraintsExt

Figure 18.18 shows how the configurable parameters for the NameConstraintsExt module are displayed in the CMS window.

Figure 18.18 Parameters defined in the NameConstraintsExt module

The configuration shown in Figure 18.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 18.16 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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.

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.

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.








permittedSubtrees<n>.
min

Specifies the minimum number of permitted subtrees.

Permissible values: -1, 0, or n.

Example: 0

permittedSubtrees<n>.
max

Specifies the maximum number of permitted subtrees.

Permissible values: -1, 0, or n.

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.

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.








excludedSubtrees<n>.
min

Specifies the minimum number of excluded subtrees.

Permissible values: -1, 0, or n.

Example: 0

excludedSubtrees<n>.
max

Specifies the maximum number of excluded subtrees.

Permissible values: -1, 0, or n.

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:

For details on individual parameters defined in the rule, see Table 18.16. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Netscape Certificate Comment Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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".

NSCCommentExt Module

The Java class that implements the Netscape certificate comment extension policy is as follows:

com.netscape.certsrv.policy.NSCCommentExt

Figure 18.19 shows how the configurable parameters for the NSCCommentExt module are displayed in the CMS window.

Figure 18.19 Parameters defined in the NSCCommentExt module

The configuration shown in Figure 18.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 18.17 provides details for each of these parameters.

Table 18.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).

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 "Using Predicates in Policy Rules".

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.

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:

For details on individual parameters defined in the rule, see Table 18.17. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Netscape Certificate Type Extension Policy
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.

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 18.18 lists the bits and their designated purposes. The extension has no default value.

Table 18.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 Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 "Forms for Certificate Enrollment"). Table 18.19 lists the HTTP input variables that correspond to Netscape certificate type extension bits.

Table 18.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 "Forms for Certificate Enrollment".

Figure 18.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 18.19, ssl_client and email, indicating that these bits be set in certificates requested using this form.

Figure 18.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 18.19.

NSCertTypeExt Module

The Java class that implements the Netscape certificate type extension policy is as follows:

com.netscape.certsrv.policy.NSCertTypeExt

Figure 18.21 shows how the configurable parameters for the NSCertTypeExt module are displayed in the CMS window.

Figure 18.21 Parameters defined in the NSCertTypeExt module

The configuration shown in Figure 18.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 18.20 gives details about each of these parameters.

Table 18.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).

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 "Using Predicates in Policy Rules".

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.

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:

For details on individual parameters defined in the rule, see Table 18.20. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


OCSP No Check Extension Policy
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 "Supported Methods for Verifying Revocation Status of Certificates". 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 "Authority Information Access Extension Policy".

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 "Validity Constraints Policy". 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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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

OCSPNoCheck Module

The Java class that implements the OCSP no check extension policy is as follows:

com.netscape.certsrv.policy.OCSPNoCheckExt

Figure 18.22 shows how the configurable parameters for the OCSPNoCheckExt module are displayed in the CMS window.

Figure 18.22 Parameters defined in the OCSPNoCheckExt module

The configuration shown in Figure 18.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 18.21 provides details for each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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:

For details on individual parameters defined in the rule, see Table 18.21. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Policy Constraints Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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

PolicyConstraintsExt Module

The Java class that implements the policy constraints extension policy is as follows:

com.netscape.certsrv.policy.PolicyConstraintsExt

Figure 18.23 shows how the configurable parameters for the PolicyConstraintsExt module are displayed in the CMS window.

Figure 18.23 Parameters defined in the PolicyConstraintsExt module

The configuration shown in Figure 18.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 18.22 gives details about each of these parameters.

Table 18.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.

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 "Using Predicates in Policy Rules".

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.

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.

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:

For details on individual parameters defined in the rule, see Table 18.22. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Policy Mappings Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 "Object Identifier". For information on certificate policies, see "Certificate Policies Extension Policy".)

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".

PolicyMappingsExt Module

The Java class that implements the policy mappings extension policy is as follows:

com.netscape.certsrv.policy.PolicyMappingsExt

Figure 18.24 shows how the configurable parameters for the PolicyMappingsExt module are displayed in the CMS window.

Figure 18.24 Parameters defined in the PolicyMappingsExt module

The configuration shown in Figure 18.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 18.23 provides details for each of these parameters.

Table 18.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).

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 "Using Predicates in Policy Rules".

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.

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 "Object Identifier" 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:

For details on individual parameters defined in the rule, see Table 18.23. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".


Private Key Usage Period Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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.

PrivateKeyUsagePeriodExt Module

The Java class that implements the private key usage period extension policy is as follows:

com.netscape.certsrv.policy.PrivateKeyUsagePeriodExt

Figure 18.25 shows how the configurable parameters for the PrivateKeyUsagePeriodExt module are displayed in the CMS window.

Figure 18.25 Parameters defined in the PrivateKeyUsagePeriodExt module

The configuration shown in Figure 18.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 18.24 provides details for each of these parameters.

Table 18.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).

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 "Using Predicates in Policy Rules".

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


Subject Alternative Name Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 10.2, Table 10.3, and Table 10.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 Table 24.9. 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".

SubjectAltNameExt Module

The Java class that implements the subject alternate name extension policy is as follows:

com.netscape.certsrv.policy.SubjectAltNameExt

Figure 18.26 shows how the configurable parameters for the SubjectAltNameExt module are displayed in the CMS window.

Figure 18.26 Parameters defined in the SubjectAltNameExt module

The configuration shown in Figure 18.26 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 18.25 provides details for each of these parameters.

Table 18.25 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.

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 "Using Predicates in Policy Rules".

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.

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.

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:

For details on individual parameters defined in the rule, see Table 18.25. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".

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


Subject Directory Attributes Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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 18.26. 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 "Step 4. Add New Policy Rules".

SubjectDirectoryAttributesExt Module

The Java class that implements the subject directory attributes extension policy is as follows:

com.netscape.certsrv.policy.SubjectDirectoryAttributesExt

Figure 18.27 shows how the configurable parameters for the SubjectDirectoryAttributesExt module are displayed in the CMS window.

Figure 18.27 Parameters defined in the SubjectDirectoryAttributesExt module

The configuration shown in Figure 18.27 creates a policy rule named SubDirAttrForClientCert, which enforces a rule that the server should set the subject directory attributes extension in client certificates.

Table 18.26 provides details for each of these parameters.

Table 18.26 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).

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 "Using Predicates in Policy Rules".

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.

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


Subject Key Identifier Extension Policy
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" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.

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:

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/sdkdocs

You may also want to check the CMS samples installed here:

<server_root>/cms_sdk/samples

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".

SubjectKeyIdentifierExt Module

The Java class that implements the subject key identifier extension policy is as follows:

com.netscape.certsrv.policy.SubjectKeyIdentifierExt

Figure 18.28 shows how the configurable parameters for the SubjectKeyIdentifierExt module are displayed in the CMS window.

Figure 18.28 Parameters defined in the SubjectKeyIdentifierExt module

The configuration shown in Figure 18.28 creates a policy rule named SubKeyIDExtForAllCert, which enforces a rule that the server should set the subject key identifier extension in all certificates.

Table 18.27 provides details for each of these parameters.

Table 18.27 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).

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 "Using Predicates in Policy Rules".

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.

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:

For details on individual parameters defined in the rule, see Table 18.27. 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 "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules".

 

© Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.