Chapter 15 Introduction to Policy

You can configure the main subsystems of Netscape Certificate Management System (CMS)--the Certificate Manager, Registration Manager, and Data Recovery Manager--to apply certain organizational policies on an end entity's certificate enrollment and management requests before servicing them. For example, some of the policies you might want a Certificate Manager to impose on these requests may include setting a minimum and maximum limit on validity period and key length of certificates, setting extensions based on the end entity's role within an organization, setting signing algorithms, and so on.

• What Is Policy?
• Policy Rules
• Policy Processor
• Built-in Policy Plug-in Modules

• A Certificate Manager's policy can include rules for evaluating certificate formulation, signing, renewal, and revocation requests. For example, you can configure a Certificate Manager's policy to impose restrictions on validity length, key type, key length, subject name, extensions, and signing algorithm during certificate issuance.
• A Registration Manager's policy can include rules for verifying incoming certificate issuance, renewal, and revocation requests from end entities in order to formulate the certificate content before forwarding the requests to a Certificate Manager for signing. For example, you can configure a Registration Manager's policy to impose restrictions on validity period, key length, subject name, and extensions. In general, policies for Registration Manager are largely the same as for Certificate Manager.
• A Data Recovery Manager's policy can include rules for verifying users' encryption private key archival and recovery requests.

• Screen the request for specific content, and modify, reject, or defer (for agent approval) it accordingly. For example, the request might be checked for the inclusion of organizational constraints, such as key algorithm, key size, validity period, or a particular signing algorithm; if it did not meet the requirement, the subsystem would modify the request or return an error, depending on the severity of the problem.
• Set common attributes, such as extensions for user and server certificate requests.

• Validate the request content by comparing it with configured criteria; reject, modify, or defer (for agent approval) the request if any of the request parameters are invalid.
• Build certificate content--for example, set common extensions and the validity period.
• Enforce organizational constraints, such as subject name, key algorithm, key size, and validity period.
• Determine whether the private key should be archived.

Certificate Management System supports distinct policy rules for each of the operations that end entities perform--certificate enrollment, renewal, and revocation, and key archival and recovery. Consequently, there are five broad categories of policies, corresponding to these types of operations:

• Enrollment policies
• Renewal policies
• Revocation policies
• Key archival policies
• Key recovery policies

You can use predicates in a policy rule. A predicate indicates whether the rule that contains the predicate applies to a request. If you specify a predicate as part of the rule configuration, the policy rule applies that predicate based on request attributes to determine whether the rule is applicable for a request.

You form an expression using an attribute, its value, and one or more of the operators listed in Table 15.1. For a list of attributes, see "Attributes for Predicates".

• PrimitiveExpression is equal to: Attribute op Value

where

Attribute can be a string

op can be any of these operators: == or !=

Value can be a string

• AndExpression is equal to: Expression AND Expression
• OrExpression is equal to: Expression OR Expression

certType == client AND ou == Engineering

certType == server AND o == Netscape OR certType == ca

Attributes for Predicates

Attributes for predicates can come from any of the following:

• Input form--that is, the HTML form that end entities use for submitting certificate requests.
• Authentication token--what the authentication subsystem returns after successfully authenticating an end entity.
• A service--for example, a Certificate Manager, Registration Manager, or Data Recovery Manager service can add certain attributes to the end-entity request.
• Policy processor--what the policy subsystem returns after subjecting the end-entity request to policy checking.

• PolicyResult.REJECTED (indicates that the request failed the rule)
• PolicyResult.DEFERRED (indicates that the request requires agent approval)
• PolicyResult.ACCEPTED (indicates that the request passed the rule)

1. If the request failed any policy rule (that is, if any of the policy rules returned a PolicyResult.REJECTED value), the processor rejects the request. The rule that rejected the request sets appropriate error messages on the request.
2. If at least one of the policy rules requires agent approval for the request (that is, if any of the policy rules returned a PolicyResult.DEFERRED value), the processor stores the request in the request queue for agent approval.
3. If the request passes all the policy rules (that is, all policy rules returned a PolicyResult.ACCEPTED value), the request gets serviced--for example the certificate is issued or renewed.

• Constraints-Specific Policy Plug-in Modules
• Extension-Specific Policy Plug-in Modules

Constraints-specific policy plug-in modules help you define rules or constraints that Certificate Management System must use to evaluate an incoming request. Table 15.3 lists the constraints-specific policy plug-in modules provided out of the box. You can use these modules, as applicable, for defining the required policy rules for your Certificate Manager or Registration Manager; no plug-ins are provided for the Data Recovery Manager.

The default revocation policy applies to end-entity certificate revocation. The policy enforces a rule that only currently valid certificates can be revoked; an expired certificate cannot be revoked. The policy also looks at the revocation reason specified in the revocation form and sets the appropriate CRLReason extension.

The plug-in module provided for the default revocation policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.DefaultRevocation.class=com.netscape .certsrv.policy.DefaultRevocation

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

DefaultRevocation

Figure 15.1 shows how the configurable parameters pertaining to the DefaultRevocation policy plug-in implementation are displayed in the CMS window.

Table 15.4 gives details about each of these parameters.

Table 15.4 Configurable parameters for the default revocation policy and their values

Parameter name	Description
enable	Specifies whether the rule is enabled or disabled. To enable the rule, enter true; to disable the rule, enter false. By default, the rule is enabled. Permissible values: Either of the following: true false Object type: String
predicate	Specifies the predicate expression for this rule. If you want the rule to be applied to all certificate requests, leave the field blank. By default, the rule is applied to all certificate requests. Example: certType==client Permissible values: See "Using Predicates in Policy Rules". Object type: String

The DSA key constraints policy applies to end-entity certificate enrollment and renewal requests. The policy imposes constraints on the following:

• The minimum and maximum sizes for keys
• The exponent sizes

The plug-in module provided for the DSA key constraints policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.DSAKeyConstraints.class=com.netscape .certsrv.policy.DSAKeyConstraints

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

DSAKeyConstraints

Figure 15.2 shows how the configurable parameters pertaining to the DSAKeyConstraints policy plug-in implementation are displayed in the CMS window.

The key algorithm constraints policy applies to end-entity certificate enrollment and renewal requests. The policy restricts the key algorithm requested to one of the algorithms, such as RSA or DSA, supported by Certificate Management System. In other words, this policy allows you to set restrictions on the types of public keys certified by Certificate Management System.

The plug-in module provided for the key algorithm constraints policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.KeyAlgorithmConstraints.class=com.
netscape.certsrv.policy.KeyAlgorithmConstraints

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

KeyAlgorithmConstraints

Figure 15.3 shows how the configurable parameters pertaining to the KeyAlgorithmConstraints policy plug-in implementation are displayed in the CMS window.

The renewal validity constraints policy applies to end-entity certificate renewals. It governs the formulation of content in the renewed certificate based on the currently issued certificate. The policy enforces the following rules:

• The number of days before expiration that a currently active certificate can be renewed.
• The new validity period for the renewed certificate, starting from the end of the period in the old certificate.

• The number of days before expiration that end entities can renew their currently active or valid certificates. For example, you may want to enforce a policy that prevents end entities from renewing their certificates any earlier than 15 days before expiration.
• The validity period of the renewed certificate. For example, you may want to enforce a policy that sets the validity period of renewed certificates to a minimum of 180 days; the renewal period starts from the ending period in the certificate presented for renewal.

The plug-in module provided for the renewal validity constraints policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.RenewalValidityConstraints.class=com .netscape.certsrv.policy.RenewalValidityConstraints

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

RenewalValidityConstraints

Figure 15.4 shows how the configurable parameters pertaining to the RenewalValityConstraints policy plug-in implementation are displayed in the CMS window.

Table 15.7 gives details about each of these parameters.

Table 15.7 Configurable parameters for the renewal validity constraints policy and their values

Parameter name	Description
minValidity	Specifies the minimum validity period, in days, for renewed certificates. The default value is 180 days. Example: 60 Permissible values: As applicable Object type: Integer
maxValidity	Specifies the maximum validity period, in days, for renewed certificates. The default value is 730 days. Example: 180 Permissible values: As applicable Object type: Integer
renewalInterval	Specifies how many days before its expiration that a certificate can be renewed. The default value is 15 days. Example: 15 Permissible values: As applicable Object type: Integer
enable	Specifies whether the rule is enabled or disabled. To enable the rule, enter true; to disable the rule, enter false. By default, the rule is enabled. Example: true Permissible values: Either of the following: true false Object type: String
predicate	Specifies the predicate expression for this rule. If you want the rule to be applied to all certificate requests, leave the field blank. By default, the rule is applied to all certificate requests. Example: certType==client Permissible values: See "Using Predicates in Policy Rules". Object type: String

The RSA key constraints policy applies to end-entity certificate enrollment and renewal requests. The policy imposes constraints on the following:

• The minimum and maximum sizes for keys
• The exponent sizes

The plug-in module provided for the RSA key constraints policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.RSAKeyConstraints.class=com.netscape .certsrv.policy.RSAKeyConstraints

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

RSAKeyConstraints

Figure 15.5 shows how the configurable parameters pertaining to the RSAKeyConstraints policy plug-in implementation are displayed in the CMS window.

The validity constraints policy applies to end-entity certificate enrollment requests. The policy enforces minimum and maximum validity periods for certificates and changes them if the policy is not met. Specifically, the policy imposes constraints on the following:

• The duration of a certificate's validity period (based on supported minimum and maximum validity periods).
• The lead and lag time for the beginning date and time (the notBefore and notAfter attributes in certificate requests) for the validity period; how far back into the front or back the notBefore date could go in minutes.

It can be useful to restrict the length of the validity period for certificates issued by Certificate Management System. For example, if you want users to renew their certificates at least once a year, you can set the maximum validity period to one year. If you want to limit the frequency of certificate renewals to keep down administrative costs, you can set the minimum validity period to six months.

The plug-in module provided for the validity constraints policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.ValidityConstraints.class=com.
netscape.certsrv.policy.ValidityConstraints

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

ValidityConstraints

Figure 15.6 shows how configurable parameters pertaining to the ValidityConstraints policy plug-in implementation are displayed in the CMS window.

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 authority key identifier extension policy plug-in implementation is based on the Authority Key Identifier extension. This extension identifies the public key that corresponds to the private key used by a CA to sign certificates.

The plug-in module provided for the authority key identifier extension policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.AuthorityKeyIdentifierExt.class=com. netscape.certsrv.policy.AuthorityKeyIdExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

AuthorityKeyIdentifierExt

Figure 15.7 shows how the configurable parameters pertaining to the AuthKeyIDExt policy plug-in implementation are displayed in the CMS window.

The basic constraints extension policy plug-in implementation is based on the Basic Constraints extension defined in X.509 and PKIX standard rfc 2459 (see http://www.ietf.org/rfc/rfc2459.txt). This 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.

If enabled, this policy adds the basic constraints extension to all certificates being issued, unless specified otherwise by the predicate expression. To add the extension to subordinate CA certificates only, you must configure the predicate expression to be certType==ca.

The plug-in module provided for the basic constraints extension policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.BasicConstraintsExt.class=com.
netscape.certsrv.policy.BasicConstraintsExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

BasicConstraintsExt

Figure 15.8 shows how the configurable parameters pertaining to the BasicConstraintsExt policy plug-in implementation are displayed in the CMS window.

The CRL distribution point extension policy plug-in implementation is based on the CRL Distribution Point extension. If enabled, this policy inserts a CRLDistributionPoint extension into each certificate being issued, unless the predicate expression specifies otherwise. Essentially, the extension identifies one or more CRL distribution points or locations where the CRL for the certificate (that includes the extension) can be obtained. For information on configuring a Certificate Manager to publish CRLs to different distribution points, see "CRL Issuing Points".

The plug-in module provided for the CRL distribution point extension policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.CRLDistributionPointsExt.class=com.
netscape.certsrv.policy.CRLDistributionPointsExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

CRLDistributionPointsExt

Table 15.13 gives details about each of the configurable parameters pertaining to the CRLDistributionPointsExt policy plug-in implementation.

If you configure the CRL distribution point policy to contain more than two distribution points, you should add the configuration parameters pertaining to the remaining distribution points to the configuration file. The parameters you're required to add include the following:

• <subsystem>.Policy.rule.CRLDistributionPoints.pointName<x>
• <subsystem>.Policy.rule.CRLDistributionPoints.pointType<x>
• <subsystem>.Policy.rule.CRLDistributionPoints.reasons<x>
• <subsystem>.Policy.rule.CRLDistributionPoints.issuerName<x>
• <subsystem>.Policy.rule.CRLDistributionPoints.issuerType<x>

1. Stop the CMS instance; see "Stopping Certificate Management System".
2. Open the configuration file in a text editor; to locate the file, see "Locating the Configuration File".
3. Add the configuration parameters to the file; see the configuration sample at the end of this procedure.
4. Save your changes, and close the configuration file.
5. Start the CMS instance; see "Starting Certificate Management System".

• The first distribution point (point 0) has no reason flags or issuer name.
• The second distribution point (point 1) has a directory (distinguished) name.
• The third distribution point (point 2) name is relative to the location of the CRL issuer, which is also given as a directory name.
• The second and third distribution points are differentiated by their reasons.

ca.Policy.rule.CRLDistributionPoints.numPoints=3

ca.Policy.rule.CRLDistributionPoints.pointName0=

	http://ca.somecorp.com/get/your/crls/here/

ca.Policy.rule.CRLDistributionPoints.pointType0=URI

ca.Policy.rule.CRLDistributionPoints.pointName1=

	CN=CRLCentral,OU=Research Dept.,O=CertCorp,C=US

ca.Policy.rule.CRLDistributionPoints.pointType1=DirectoryName

ca.Policy.rule.CRLDistributionPoints.reasons1=

	keyCompromise,cACompromise

ca.Policy.rule.CRLDistributionPoints.pointName2=CN=SubCN

ca.Policy.rule.CRLDistributionPoints.pointType2=

	RelativeToIssuer

ca.Policy.rule.CRLDistributionPoints.reasons2=

	superseded,cessationOfOperation

ca.Policy.rule.CRLDistributionPoints.issuerName2=

	OU=Research Dept.,O=CertCorp,C=US

ca.Policy.rule.CRLDistributionPoints.issuerType2=DirectoryName

The key usage extension policy plug-in implementation is based on the Key Usage extension. This extension specifies for what purposes the key contained in the certificate should be used: whether the key should be used for data signing, key encipherment, or data encipherment. You can use this extension to restrict the usage of a key pair (or certificate). For example, you can restrict a certificate to be used for digital signature only.

• digital_signature (bit 0)
• non_repudiation (bit 1)
• key_encipherment (bit 2)
• data_encipherment (bit 3)
• key_agreement (bit 4)
• key_certsign (bit 5)
• crl_sign (bit 6)
• encipher_only (bit 7)
• decipher_only (bit 8)

The plug-in module provided for the key usage extension policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.KeyUsageExt.class=com.netscape.
certsrv.policy.KeyUsageExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

KeyUsageExt

Figure 15.10 shows how the configurable parameters pertaining to the KeyUsageExt policy plug-in implementation are displayed in the CMS window.

The Netscape certificate type extension policy plug-in implementation is based on the Netscape Certificate Type extension. You can use this policy to limit the applications for a certificate. In other words, the extension identifies the type of certificate; for example, it identifies whether the certificate is a CA certificate, server SSL certificate, client SSL certificate, object signing certificate, or S/MIME certificate.

• If the extension exists in a certificate, it limits the uses of the certificate to those specified.
• If the extension is not present, the certificate can be used for all applications except object signing.

• ssl_client (bit 0)
• ssl_server (bit 1)
• email (bit 2)
• object_signing (bit 3)
• Reserved for future use (bit 4)
• ssl_ca (bit 5)
• email_ca (bit 6)
• object_signing_ca (bit 7)

The plug-in module provided for the Netscape certificate type extension policy is identified as follows:

• In the configuration file, the implementation for this module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.NSCertTypeExt.class=com.netscape.
certsrv.policy.NSCertTypeExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

NSCertTypeExt

Figure 15.12 shows how the configurable parameters pertaining to the NSCertTypeExt policy plug-in implementation are displayed in the CMS window.

The SubjectAltNameExt policy plug-in implementation is based on the Subject Alternate Name extension. If enabled, this policy checks the certificate request for a mail attribute, and if it is present, adds the subject alternate name extension to the certificate being issued. Both the built-in directory-based authentication modules can obtain a mail attribute from the authentication directory and set that attribute in the certificate request. For more information on the mail attribute, see the description for the ldapAttributes parameter in Table 9.1 and Table 9.2.

The plug-in provided for the subject alternate name extension policy is identified as follows:

• In the configuration file, CMS.cfg, the implementation for this policy plug-in module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.SubjectAltNameExt.class=com.netscape .certsrv.policy.SubjectAltNameExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this policy plug-in module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

SubjectAltNameExt

Table 15.16 provides details for the configurable parameters pertaining to the SubjectAltNameExt policy plug-in implementation.

The SubjectKeyIDExt policy plug-in implementation is based on the Subject Key Identifier extension. This extension provides a means of identifying certificates that contain a particular public key. In other words, this extension is used to uniquely identify a certificate from among several that have the same subject name.

The plug-in provided for the subject key identifier extension policy is identified as follows:

• In the configuration file, CMS.cfg, the implementation for this policy plug-in module is identified as follows; you can find it in the Policy section:

<subsystem>.Policy.impl.SubjectKeyIdentifierExt.class=com.
netscape.certsrv.policy.SubjectKeyIdExt

where <subsystem> indicates ca or ra (prefix identifying the subsystem)

• In the CMS window, the implementation for this policy plug-in module is identified as follows; you can find it in the Policy Plugin Registration tab of the corresponding subsystem:

SubjectKeyIdentifierExt

Figure 15.13 shows how the configurable parameters pertaining to the SubjectKeyIDExt policy plug-in implementation are displayed in the CMS window.