Chapter 18   Setting Up Policies


iPlanet Certificate Management Server (CMS) provides a customizable policy framework for its main subsystems, the Certificate Manager, Registration Manager, and Data Recovery Manager. This chapter explains how to configure these subsystems to apply organizational and other policies on incoming certificate and key-related requests.

The chapter has the following sections:

• Introduction to Policy

• Configuring Policy Rules for a Subsystem

• Using JavaScript for Policies

• Managing Policy Plug-in Modules

Introduction to Policy

---

You can configure the main subsystems of iPlanet Certificate Management Server (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.

This section provides an overview of policy in general. Topics include:

• What Is Policy?

• Policy Rules

• Policy Processor

What Is Policy?

Policy refers to a set of rules that Certificate Management System uses to evaluate or verify an incoming request from an end entity and to determine the outcome; the incoming requests that are governed by policies include certificate issuance, certificate renewal, certificate revocation, key archival, and key recovery requests. For example, in the case of a certificate issuance request, the outcome would be the certificate content.

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

Using policies, you can configure Certificate Management System to perform one or more of the following operations on each certificate issuance or management request it receives:

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

Policy Rules

A policy rule refers to a uniquely configured instance of any policy plug-in implementation. For example, you can use the plug-in module provided for setting validity periods on certificates to configure a policy rule that forces validity periods for all client certificates issued by a Certificate Manager to fall within a predetermined range, say between 6 and 24 months. A subsystem's policy configuration can consist of one or more policy rules, each performing one or more of the following operations:

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

Keep in mind that the server applies the rules when processing end-entity requests and after agent approval (for deferred requests).

Types of Policy Rules

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

To facilitate this classification, Certificate Management System supports a parent interface for a generic policy rule and other operation-specific interfaces that extend the parent interface. Check the CMS SDK, available in the form of Java Docs at this location: <server_root>/cms_sdk/cms_jdk/javadocs

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

<server_root>/cms_sdk/cms_jdk/samples/policy

Using Predicates in Policy Rules

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.

The policy predicate is a logical expression. You form the expression using variables and relational operators (AND or OR). For example, you could set up a predicate to put the CRL Distribution Point extension only in SSL client certificates, or set different validity dates for certificates for users in different groups.

The following are sample predicates:

HTTP_PARAMS.certType==client AND HTTP_PARAMS.ou==Engineering

HTTP_PARAMS.certType==server AND HTTP_PARAMS.o==Siroe OR HTTP_PARAMS.certType==ca

Expression Support for Predicates

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

Table 18-1    Predicates in policy: supported comparison and logical operators  

Operator	Description
==	Equal to
!=	Not equal to
AND	Logical operator AND
OR	Logical operator OR

Note that the expression parsing support currently supports only two comparison operators (==, !=) and two relational operators (AND, OR).

Policy expressions are formed with the following rules:

PrimitiveExpression | AndExpression | OrExpression

• 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

In an expression, the AND operator takes precedence over an OR operator. For example, the expression

HTTP_PARAMS.certType==client AND HTTP_PARAMS.ou==Engineering OR HTTP_PARAMS.certType==ca

is interpreted as

(HTTP_PARAMS.certType==client AND HTTP_PARAMS.ou==Engineering) OR HTTP_PARAMS.certType==ca

Certificate Management System evaluates an expression based on the attributes in the request. The attributes 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 also interpret the form content, for example, retrieving the key material out of the KEYGEN or PKCS #10 information and setting the key in the certificate content. They can also set additional attributes related to the certificate content on the request. In general, you can configure which attributes—for example, sensitive attributes such as passwords—should or shouldn't be stored in the request.

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. The policy subsystem applies configured policy rules on the request, determines whether the request needs agent approval, performs constraint- and extension-specific checks on the request attributes, and then formulates the certificate content by adding the appropriate information, such as the validity period and extensions.

The expression queries the request for the attributes, compares the value returned with the value provided in the predicate, and returns a boolean result.

Be aware that if the same name is in a HTTP form input and authentication token (authentication result) the authentication result can override the HTTP form input. For example, if email is in a HTTP input and an authentication module also puts email in the authentication result (that is, authtoken) the email value from the authentication module will override the email value from the HTTP input in the request. A predicate using email in an expression will be evaluated to the value of the authentication instead of the HTTP input value.

The following are sample predicates:

HTTP_PARAMS.certType==client AND HTTP_PARAMS.ou==Engineering

HTTP_PARAMS.certType==server AND HTTP_PARAMS.o==Siroe OR HTTP_PARAMS.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. For example, an extension-based policy can set an appropriate extension in the certificate.

Table 18-2 lists default attributes that are supported by various request object implementations.

Table 18-2    Attributes supported by request object implementations  

Request type	Variable name	Description
Default attributes from an input form:
Enrollment	requestFormat	Specifies the certificate request format. Default values include the following: keygen pkcs10 clientAuth
Enrollment	certType	Specifies the certificate type. Default values include the following: ca (Certificate Manager's CA signing certificate) caCrlSigning (Certificate Manager's CRL signing certificate) CEP-Request (router certificate) client (client certificates) codeSignClient (Object signing certificate - PKCS#10) objSignClient (Object signing certificate - Browser) ocspResponder (OCSP Responder certificate) other ra (Registration Manager's signing certificate) server (SSL server certificate)
Enrollment	doSslAuth	Specifies whether the client is required to do SSL client authentication during enrollment. Default values include the following: on off
Enrollment	certauthEnroll	Specifies whether it is a certificate-based enrollment. Default values include the following: on off
Enrollment	certauthEnrollType	Specifies the number of keys to be generated for a certificate-authenticated enrollment—whether a single signing key, a single encryption key, or dual keys (one for signing and another for encryption) is to be generated. Default values include the following: single encryption dual
Enrollment	cepsubstore	Specifies the name of the CEP service; for example, cep1 and cep2. When setting up multiple CEP services, you can use predicates to differentiate one service for another; see Step 4. Set Up Multiple CEP Services.
Enrollment, Renewal, and Revocation	requestStatus	Specifies when (or the phase in which) a request gets subjected to policy processing: begin specifies that the request be subjected to a policy before it gets queued for agent approval. pending specifies that the request be subjected to a policy after agent approval.
Renewal	requestFormat	Specifies the certificate request format. Default values include the following: clientAuth pkcs10
Default attributes from an authentication token: (Upon successful authentication these attributes go into an enrollment request)
Enrollment	authMgrImplName	Specifies the name of the authentication plug-in module that authenticated the request.
Enrollment	authMgrInstName	Specifies the name of the authentication instance that authenticated the request.

You can define your own attributes for predicates, if there's a need. For example, assume you have two organizational units Sales and Manufacturing and you want to issue client certificates with different validity periods to users in these two units. A quick and easy way to accomplish this would be to define a new attribute for the organizational unit, add the attribute to the enrollment form that the users in these organizational units use for certificate enrollment (so that the server receives it from the HTTP input), and use the attribute in the predicate expression for the validity constraints policy—a policy rule that determines the validity period of certificates the server issues. For details on this policy, check the "ValidityConstraints Plug-in Module" section in Chapter 3, "Constraints Policy Plug-in Modules" of CMS Plug-Ins Guide.

Note that to define a new attribute in any of the HTML forms, all you need to do is to add the following line to the corresponding HTML form:

<input type="HIDDEN" name="attribute_name" value="attribute_value">

Assuming that the new attribute you define for the organizational unit is orgunit, the line you would add to the enrollment form would be:

<input type="HIDDEN" name="orgunit" value="Sales">

To add this line to an enrollment form, you would:

1. Open the corresponding HTML file in a text editor.

2. Locate the section that lists the HTTP input variables.

3. Add this line: <input type="HIDDEN" name="orgunit" value="Sales">

4. Save your changes and close the file.

For the server to use the attribute (to distinguish enrollment requests from users in the Sales unit versus those in the Manufacturing unit) to issue certificates with the appropriate validity periods, you must formulate your predicate expression with the attribute you added. Here's how you do this:

1. Create a new instance of the ValidityConstraints policy plug-in implementation.

2. Enter the appropriate values for all the attributes. Assume you
   • named the instance ValidityRule1

   • set the minimum validity period to 10 days

   • set the maximum validity period to 180 days

   • defined the predicate expression as HTTP_PARAMS.certType==client AND HTTP_PARAMS.orgunit==Sales

     (This expression specifies that the policy be applied to only client certificate requests from users in the organizational unit named Sales.)

   A sample of the resulting configuration entries in the CMS configuration file would be as follows:

   ca.Policy.rule.ValidityRule1.enable=true
   ca.Policy.rule.ValidityRule1.implName=ValidityConstraints
   ca.Policy.rule.ValidityRule1.maxValidity=180
   ca.Policy.rule.ValidityRule1.minValidity=10
   ca.Policy.rule.ValidityRule1.predicate=HTTP_PARAMS.certType==
         client AND HTTP_PARAMS.orgunit==Sales

Now, for setting the validity period in certificates of users who are not in the Sales organization—in this case, this would be Manufacturing—you would create another instance of ValidityConstraints policy rule as before with a different set values.

Assume you

• named the instance ValidityRule1

• set the maximum validity period to 60 days

• set the minimum validity period to 10 days

• defined the predicate expression as HTTP_PARAMS.certType==client AND HTTP_PARAMS.orgunit!=Sales

  (This expression specifies that the policy be applied to only client certificate requests from users who are not in the organizational unit named Sales.)

A sample of the resulting configuration entries in the CMS configuration file would be as follows:

ca.Policy.rule.ValidityRule2.enable=true
ca.Policy.rule.ValidityRule2.implName=ValidityConstraints
ca.Policy.rule.ValidityRule2.maxValidity=60
ca.Policy.rule.ValidityRule2.minValidity=10
ca.Policy.rule.ValidityRule2.predicate=HTTP_PARAMS.certType==
      client AND HTTP_PARAMS.orgunit!=Sales

The new configuration would result in certificates with a validity period of six months for users in the Sales organizational unit and a validity period of three months for users in the Manufacturing unit.

Policy Processor

Each subsystem—the Certificate Manager, Registration Manager, or Data Recovery Manager—has its own policy processor. Each processor subjects an incoming request to the applicable policy rules for that subsystem.

When a subsystem starts up, its policy processor reads the current policy configurations from the configuration file, initializes them, and classifies them based on their type (see Types of Policy Rules). Then, when the subsystem receives an authenticated request, its request processor invokes the policy processor to apply policies on that request. The policy processor applies the rules on the request based on the request type. The policy processor also filters the rules based on predicates (see Using Predicates in Policy Rules).

Note that the policy processor applies only the enabled policy rules, in the order in which they are configured, before determining the final outcome. Each rule the processor executes returns a PolicyResult object. Three return values are possible:

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

After all the policy rules are applied, the processor determines the status of the request (in this order):

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.

Configuring Policy Rules for a Subsystem

---

You can configure the main subsystems of Certificate Management System (CMS)—the Certificate Manager, Registration Manager, and Data Recovery Manager—to apply certain organizational policies on end entities' certificate enrollment, renewal, and revocation requests before servicing them. This section explains how to configure a subsystem to evaluate end-entity requests based on a set of policy rules.

The steps are as follows:

• Step 1. Before You Begin

• Step 2. Modify Existing Policy Rules

• Step 3. Delete Unwanted Policy Rules

• Step 4. Add New Policy Rules

• Step 5. Reorder Policy Rules

• Step 6. Restart the Server

• Step 7. Test Policy Configuration

For information on adding or changing policy-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.

Step 1. Before You Begin

Before configuring a Certificate Manager's or Registration Manager's policy, be sure to do this:

• Refer to the X.509 standard and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to get familiar with certificate content, including extensions.

• Read Chapter 3, "Constraints Policy Plug-in Modules" and Chapter 4, "Certificate Extension Plug-in Modules" of CMS Plug-Ins Guide. Determine the rules that you want to use to govern the generation and formulation of certificates in your PKI setup.

This planning will help you configure a Certificate Manager and Registration Manager with the appropriate policy rules so that your end entities get the right kind of certificate.

Step 2. Modify Existing Policy Rules

You can modify a policy rule by editing its configuration parameter values; you cannot edit the name of a rule. To change the name of a rule, you need to create a new rule exactly like the rule you want to rename, except with a new name, and delete the old rule.

As a part of editing a rule, you can change its status from enabled to disabled or vice versa by checking or unchecking the enable parameter. A subsystem subjects certificate requests only to those rules that are enabled.

During installation, the Certificate Manager and Registration Manager automatically create a set of policy rules (that you would most likely want to use) using the policy modules registered by default. Figure 18-1 shows the policy rules created for a Certificate Manager. The Registration Manager also has a similar list. Table 18-3 summarizes the default rules created for both Certificate Manager and Registration Manager.

After installation, you must verify whether you want to use these rules, check how these rules are configured, and make the appropriate configuration changes. Keep in mind some of these policy rules are essential for the server to process requests. For example, the server won't be able to process certificate-issuance requests if DefaultValidityRule is disabled. Similarly, the server won't be able to process certificate-renewal requests if DefaultRenewalValidityRule is disabled.

If you don't want to use a rule, delete it from the configuration as explained in Step 3. Delete Unwanted Policy Rules; alternatively, you may keep it in the disabled state. If you want to create a new rule, you can do so as explained Step 4. Add New Policy Rules.

Figure 18-1    Default policy rules created for a Certificate Manager

Table 18-3    Default policy rules of a Certificate Manager and Registration Manager  

Policy rule name	Certificate Manager	Registration Manager
KeyAlgRule	Yes	Yes
DSAKeyRule	Yes	Yes
RSAKeyRule	Yes	Yes
DefaultValidityRule	Yes	Yes
RenewalConstranitsRule	Yes	Yes
DefaultRenewalValidityRule	Yes	Yes
RevocationConstranitsRule	Yes	Yes
NSCertTypeExt	Yes	Yes
CMCertKeyUsageExt	Yes	Yes
RMCertKeyUsageExt	Yes	Yes
ClientCertKeyUsageExt	Yes	Yes
ServerCertKeyUsageExt	Yes	Yes
ObjSignCertKeyUsageExt	Yes	Yes
CRLSignCertKeyUsageExt	Yes	Yes
SubjectKeyIdentifierExt	Yes	Yes
CertificatePoliciesExt	Yes	Yes
NSCCommentExt	Yes	Yes
OCSPNoCheckExt	No	No
OCSPSigningExt	Yes	Yes
CODESigningExt	Yes	Yes
GenericASN1Ext	Yes	Yes
CRLDistributionPointsExt	Yes	Yes
SubjectAltNameExt	Yes	Yes
SigningAlgRule	Yes	No
AuthorityKeyIdentifierExt	Yes	No
AuthInfoAccess	Yes	Yes
BasicConstraintsExt	Yes	No
UniqueSubjectName	Yes	No
NameConstraintsExt	Yes	No
PolicyConstraintsExt	Yes	No
SubCANameCheck	Yes	No
PolicyMappingsExt	Yes	No
IssuerRule	Yes	No

To modify a policy rule in the CMS configuration:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select the subsystem to which the policy rule you want to modify belongs.

4. Select Policies.

   The Policy Rules Management tab appears. It lists configured policy rules.

5. In the Policy Rule list, select a rule that you want to modify.

   For the purposes of this instruction, assume that you selected the rule named DefaultValidityRule.

6. Click Edit/View.

   The Policy Rule Editor window appears, showing how this rule is configured. An example is shown below.
   
   

7. Make the necessary changes and click OK.

   You are returned to the Policy Rules Management tab.

8. Repeat steps 5 through 7 for the remaining rules.

9. Click Refresh.

Step 3. Delete Unwanted Policy Rules

You can delete any unwanted policy rules from the CMS configuration. If you think you might need a rule in the future, instead of deleting it from the configuration you should disable it by unchecking the enable parameter. In this way, you can avoid re-creating the rule in the future. Because the subsystems subject end-entity requests only to rules that are currently enabled (see Policy Processor), keeping unwanted rules in the disabled state in the configuration does not affect policy decisions made by a subsystem.

To delete a policy rule from the CMS configuration:

1. In the Policy Rules Management tab, select the rule you want to delete and click Delete.

2. When prompted, confirm the delete action.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet; you can do so after you've made all the required changes.

Step 4. Add New Policy Rules

Adding a policy rule to the CMS configuration involves creating a new instance of an already registered policy plug-in module, assigning a unique name for the instance, and entering appropriate values for the parameters that define the module you want to create an instance of.

When you add a policy rule, the CMS configuration gets updated with policy-specific information. Keep the following points in mind:

• When naming a policy instance (or rule), be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type My_Policy_Rule or MyPolicyRule as the instance name, but not My Policy Rule.

• The status of the rule, enabled or disabled, depends on whether you check or uncheck the enable parameter. A subsystem subjects certificate requests only to rules that are enabled.

• The server does not automatically reorder rules. Be sure to change the order of the rule, if required.

Figure 18-2 shows the policy modules registered with a Certificate Manager. The Registration Manager also has a similar list. Table 18-4 summarizes the default modules registered with both Certificate Manager and Registration Manager.

Figure 18-2    Default policy modules registered with a Certificate Manager

Table 18-4    Policy modules of a Certificate Manager and Registration Manager  

Policy plug-in module name	Certificate Manager	Registration Manager
AttributePresentConstraints	Yes	Yes
AuthInfoAccessExt	Yes	Yes
AuthorityKeyIdentifierExt	Yes	No
BasicConstraintsExt	Yes	No
CertificatePoliciesExt	Yes	Yes
CertificateRenewalWindowExt	Yes	Yes
CertificateScopeOfUseExt	Yes	Yes
CRLDistributionPointsExt	Yes	Yes
DSAKeyConstraints	Yes	Yes
ExtendedKeyUsageExt	Yes	Yes
GenericASN1Ext	Yes	Yes
IssuerAltNameExt	Yes	Yes
IssuerConstraints	Yes	No
KeyAlgorithmConstraints	Yes	Yes
KeyUsageExt	Yes	Yes
NameConstraintsExt	Yes	No
NSCComment	Yes	Yes
NSCertTypeExt	Yes	Yes
OCSPNoCheckExt	Yes	Yes
PolicyConstraintExt	Yes	No
PolicyMappingsExt	Yes	No
PrivateKeyUsagePeriodExt	Yes	Yes
RemoveBasicConstraintsExt	Yes	No
RenewalConstraints	Yes	Yes
RenewalValidityConstraints	Yes	Yes
RevocationConstraints	Yes	Yes
RSAKeyConstraints	Yes	Yes
SigningAlgorithmConstraints	Yes	Yes
SubCANameConstraints	Yes	No
SubjectAltNameExt	Yes	Yes
SubjectDirectoryAttributesExt	Yes	Yes
SubjectKeyIdentifierExt	Yes	Yes
UniqueSubjectNameConstraints	Yes	No
ValidityConstraints	Yes	Yes

To add a new policy rule to the CMS configuration:

1. In the Policy Rules Management tab, click Add.

   The Select Policy Plugin Implementation window appears. It lists registered policy plug-in modules. If you have registered any custom policy modules (see Registering a Policy Module), they too will be listed here.
   
   

2. Select a plug-in module.

   For the purposes of this instruction, assume that you selected the ValidityConstraints module.

3. Click Next.

   The Policy Rule Editor window appears, listing the configuration information.
   
   

4. Enter the appropriate information.

   Policy Rule ID. Type a unique name that will help you identify the rule; be sure to use an alphanumeric string without spaces.

   enable. Check the box to enable the rule (default). If you enable the rule and set the remaining parameters correctly, the server sets the configured validity period in certificates specified by the predicate parameter. Uncheck the box to disable the rule. If you disable the rule, the server does not set the configured validity period in certificates; it sets the validity period to the one specified in the request.

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

   minValidity. Type the minimum validity period, in days, for certificates. The value must be an integer greater than zero and less than the value you will type for the maxValidity parameter next. The default value is 180 days.

   maxValidity. Type the maximum validity period, in days, for certificates. The value must be an integer greater than zero and also greater than the value you typed for the minValidity parameter. The default value is 730 days.

   leadTime. Type the lead time, in minutes, for certificates. For a certificate renewal request to pass the renewal validity constraints policy, the value of the notBefore attribute in the certificate request must not be more than value of the leadTime parameter in the future, relative to the time when the policy rule is run. The default value is 10 minutes.

   The notBefore attribute value specifies the date on which the certificate validity begins.

   lagTime. Type the lag time, in minutes, for certificates. For a certificate renewal request to pass the renewal validity constraints policy, the value of the notBefore attribute in the certificate request must not be more than the value of the lagTime in the past, relative to the time when the policy is run. The default value is 10 minutes.

   The notBefore attribute value specifies the date on which the certificate validity ends.

   notBeforeSkew. Type the number of minutes to subtract from the current time when creating the value for the certificate's notBefore attribute. It can help some clients with incorrectly set clocks use the new certificate after downloading. For example, if the certificate is issued at 11:30 a.m. and the clock settings of the client into which the certificate is downloaded is 11:20 a.m., the certificate cannot be used for 10 minutes. Setting the value of the notBeforeSkew parameter to 10 minutes would adjust the value of the notBefore parameter to 11:20 a.m.—thus making the certificate usable following the down load. The default value is 5 minutes.

5. Click OK.

   You are returned to the Policy Rules Management tab.

6. Repeat steps 1 through 5 and create additional rules, if required.

Step 5. Reorder Policy Rules

For maintaining priority levels, Certificate Management System supports a linear list of policy rules in increasing order of priority. This means that for a given policy category in the configuration file, a policy configuration with a lower priority precedes one with a higher priority. This simple linear listing avoids the need to have explicit locking on request attributes to prevent conflicting changes. By ordering the rules, you introduce a concurrency control whereby a higher-priority rule configuration overwrites any changes made by a lower-priority rule configuration that precedes it.

You may want to specify policies at different priority levels for the same operation depending on the end-entity information. For example, authentication policies, if any, need to precede others in the list.

To reorder policy rules in the CMS configuration:

1. In the Policy Rules Management tab, click Reorder.

   The Reorder Policy Rules window appears. It lists configured policy rules in the order in which they are executed by the subsystem.
   
   

2. To change the order of a rule, select it in the list and click the Up or Down button, as appropriate.

   Keep in mind that the server executes the rules on a first-come-first-served basis, overwriting the configuration determined by the previous rule, if any.

3. When you have the correct order, click OK.

   You are returned to the Policy Rules Management tab.

4. To view the updated configuration, click Refresh.

Step 6. Restart the Server

This step is required only if you were prompted to restart the server in any of the previous steps.

To restart the server from the CMS window:

1. Click the Tasks tab

2. Click Restart the Server.

Step 7. Test Policy Configuration

To make sure that you've configured the server correctly, request a certificate and check the certificate for details such as for validity period, key type and size, and extensions.

• Step A. Enroll for a Certificate

• Step B. Approve the Request

• Step C. Check the Certificate Details

Step A. Enroll for a Certificate

The steps outlined below explain how to request a personal certificate from the Certificate Manager using the manual enrollment method. If you've configured the Certificate Manager for automated certificate issuance, for example the directory-based enrollment, you can use the appropriate form and request a certificate.

To request a client or personal certificate from the Certificate Manager:

1. Open a web browser window.

2. Go to the End Entity Services interface of the Certificate Manager you configured (or the Registration Manager that's connected to this Certificate Manager).

   The URL is in this form: https://<hostname>:<end_entity_HTTPS_port> or http://<hostname>:<end_entity_HTTP_port>

3. In the left frame, under Browser, click Manual.

   This opens the manual enrollment form.

4. Fill in all the values and submit the request.

   The client prompts you to enter the password for your key database.

5. When you enter the correct password, the client generates the key pairs.

   Do not interrupt the key-generation process.

Step B. Approve the Request

This step is required if you used the manual enrollment form for requesting the certificate. The request you submitted is waiting in the agent queue for approval by an agent.

To approve the request:

1. Go to the Certificate Manager's Agent Services interface.

   The URL is in this format: https://<hostname>:<agent_port>

2. In the left frame, click the link that says List Requests.

3. In the form that appears, select the "Show pending requests" option and click Find.

   You should see your request in the list of pending requests.

4. Locate the request you submitted and approve the request.

   You should see a confirmation page indicating that the certificate has been issued. Don't close the page until you finish the next step.

Step C. Check the Certificate Details

Verify that the certificate contains the required details. Be sure to check the Extension section to see if it contains all the required extensions.

Using JavaScript for Policies

---

Certificate Management System includes a facility for complex scripting of the policy plug-in instances via JavaScript^TM. Using the JavaScript policy processor allows you to:

• Determine the call sequence of existing Java plug-ins

• Use complex logic to determine whether to call a plug-in (versus the simpler predicates)

• Write policies in JavaScript

• Develop extensions without needing to know Java or have the Java SDK

Certificate Management System uses the Rhino JavaScript engine from Mozilla.org. You can get more details about the Rhino project from this site:

http://www.mozilla.org/rhino

To learn more about how to use JavaScript in Certificate Management System, consult the sample policy.js file included in the distribution:

<server_root>/bin/cert/js/policy.js

Managing Policy Plug-in Modules

---

This section explains how to use the CMS window to perform the following operations:

• Registering a Policy Module

• Deleting a Policy Module

For information on adding or changing policy-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.

Registering a Policy Module

You can register new policy plug-in modules in a subsystem's policy framework. Registering a new policy module involves specifying the name of the module and the full name of the Java class that implements the policy interface. For example, you can add a policy implementation, named as follows, to the Data Recovery Manager's policy framework: com.iplanet.policy.KeyArchivalPolicy

Before registering a plug-in module, be sure to put the Java class for the module in the classes directory (the implementation must be on the class path).

To register a policy module in a subsystem's policy framework:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select the subsystem that will use the module you want to register.

4. Select Policies, and then in the right pane, select the Policy Plugin Registration tab.

   The Policy Plugin Registration tab appears. It lists registered policy plug-in modules.
   
   

5. Click Register.

   The Register Policy Plugin Implementation window appears.
   
   

6. Specify information as appropriate:

   Plugin name. Type a name for the plug-in module.

   Class name. Type the full name of the class for this module—that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named myPolicy and if this class is in a package named com.myCompany, type com.myCompany.myPolicy.

7. Click OK.

   You are returned to the Policy Plugin Registration tab.

8. To view the updated configuration, click Refresh.

Deleting a Policy Module

You can delete unwanted policy plug-in modules using the CMS window. Before deleting a module, be sure to delete all the policy rules that are based on this module; see Step 3. Delete Unwanted Policy Rules.

To delete a policy module from a subsystem's policy framework:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select the subsystem that registers the module you want to delete.

4. Select Policies, and then in the right pane, select the Policy Plugin Registration tab.

   The Policy Plugin Registration tab appears. It lists registered policy modules.

5. In the Plugin Name list, select the module you want to delete and click Delete.

6. When prompted, confirm the delete action.