Chapter 19 Configuring a Subsystem's Policies

Netscape Certificate Management System (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.

• Policy Management
• Setting up Policy Rules for a Subsystem
• Managing Policy Plug-in Modules

• By making changes to the authentication-specific parameters from the CMS window, explained in "Policy Management From the CMS Window"
• By editing the parameters in the configuration file, explained in "Policy Parameters in the Configuration File"

The CMS window (as shown in Figure 19.1) provides the appropriate user interface to support policy management for each subsystem, the Certificate Manager, Registration Manager, and Data Recovery Manager.

• Configuration of currently registered policy modules
• Registration of new (custom) policy modules

The Policy Rules Management tab displays the current policy configuration for the selected subsystem. The tab lists the currently configured policy instances (or rules) for a subsystem, enabling you to manage them at a single place. From this tab you can add, modify, or delete rules, enable or disable individual rules, and change the order in which the rules get applied to an end-entity request.

Delete. The delete operation allows you to remove unwanted policy rules from the CMS configuration. For instructions, see "Step 3. Delete Unwanted Policy Rules".

Edit/View. The edit operation allows you to view and modify configuration parameter values associated with the currently configured policy rules. For instructions, see "Step 2. Modify Existing Policy Rules".

Reorder. The reorder operation allows you to change the order of the policy rules a subsystem applies to an end-entity request. Enabled rules are applied in the order in which they appear; disabled rules are ignored. For instructions, see "Step 5. Reorder Policy Rules".

Policy Plugin Registration Tab

The Policy Plugin Registration tab lists the currently registered policy plug-in modules for the selected subsystem and gives you access to the window from which you can register new modules. On this tab you will find the names of registered modules listed on the left and the path to the Java class that implements the module listed on the right.

Delete. This operation allows you to remove unwanted policy modules from the CMS framework. For instructions, see "Deleting a Policy Module".

Policy Parameters in the Configuration File

The sample configuration file shown on page 89 illustrates how policy-specific information appears in the configuration file. Keep the following points in mind:

• All policy-specific information, such as registered policy plug-in implementations, configured rules, and ordering, appear in the Policy section of the configuration file. If you have installed more than one subsystem in a CMS instance, for example Certificate Manager and Data Recovery Manager together, the configuration file will include policy sections that are specific to each of the subsystems that share the configuration.

You can identify policy pertaining to a subsystem by these prefixes:

• Certificate Manager by ca
• Registration Manager by ra
• Data Recovery Manager by kra

• Each registered policy plug-in module is identified by its implementation name and the corresponding Java class.
• Each configured rule of a policy module is identified by the name specified when the rule was created.
• You can create multiple rules out of an implementation; each rule must have a unique name.

• Step 1. Plan
• 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

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 chapters "Constraints-Specific Policy Modules" and determine the rules that you want to use to govern the generation and formulation of certificates in your PKI setup.
• Read "Extension-Specific Policy Modules" to determine the extensions you want to set in certificates.

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.

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 (Figure 19.2). It lists configured policy rules. The default rules are listed in Table 19.1.

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.

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.

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.

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 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. For information on reordering rules, see "Step 5. Reorder Policy Rules".

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

The Select Policy Plugin Implementation window appears. It lists registered policy plug-in modules. The default modules are listed in Table 19.2.



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. It lists the configuration information required for this policy rule.



4. Enter the appropriate information.

Policy Rule ID. Type a unique name that will help you identify the rule. Be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-). For example, you can type My_Policy_Rule or MyPolicyRule as the instance name, but not My Policy Rule.

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.

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.

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



2. To change the order of a rule, select it in the list and click the Up or Down button, as appropriate.
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.

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

1. Click the Tasks tab
2. Click Restart the Server.

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

The steps outlined below explain how to request a personal certificate from the Certificate Manager using the manual enrollment method (see "Manual Authentication"). 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.

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://<host_name>:<end_entity_HTTPS_port> or

http://<host_name>:<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.

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.

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

The URL is in this format: https://<host_name>:<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.

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

• Registering a Policy Module
• Deleting 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:

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.

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

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. For information about this tab, see "Policy Plugin Registration Tab".

5. In the Plugin Name list, select the module you want to delete and click Delete.
6. When prompted, confirm the delete action.