Netscape logo Administrator's Guide
Netscape Certificate Management System
Previous      Contents      Index      DocHome      Next     

Chapter 12   Policies


Netscape Certificate Management System (CMS) provides a customizable policy framework for 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.

Note: This feature is provided for legacy purposes. If you are new to this product, you should stay with the newer (default) certificate enrollment feature: Certificate Enrollment Profiles (see Chapter 11 "Certificate Profiles"). The policies feature will be discontinued in the future release(s). To enable the feature, you need to copy all the files under: <serverRoot>/bin/cert/forms/ee/<subsystem>/policyEnrollment/ to <serverRoot>/cert-<instanceID>/web-apps/ee/<subsystem>/, where subsystem is either ca or ra.

This chapter contains the following sections:

Introduction to Policy

You can configure the main subsystems of 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:

About Policy

Policy refers to a set of rules that CMS 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.

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

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:

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

CMS 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:

To facilitate this classification, CMS supports a parent interface for a generic policy rule and other operation-specific interfaces that extend the parent interface. Check the CMS SDK.

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:

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.

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==Netscape 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 12-1. For a list of attributes, see Attributes for Predicates.


Table 12-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

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

CMS 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 an HTTP form input and authentication token (authentication result) the authentication result can override the HTTP form input. For example, if email is in an 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==Netscape OR HTTP_PARAMS.certType==ca

Attributes for Predicates

Attributes for predicates can come from any of the following:

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


Table 12-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:

 

Enrollment

 

certauthEnroll

 

Specifies whether it is a certificate-based enrollment. Default values include the following:

 

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

 

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, see "ValidityConstraints".

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

Configuring Policy Rules for a Subsystem

You can configure the main subsystems of CMS (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.

Modifying Policy Rules

To modify existing policy rules:

  1. Log in to the CMS window (see Logging Into the CMS Console).
  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.
    5. 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.
    6. For the purposes of this instruction, assume that you selected the rule named DefaultValidityRule.
     
  6. Click Edit/View.
    7. The Policy Rule Editor window appears, showing how this rule is configured.
     
  7. Make the necessary changes and click OK.
    8. You are returned to the Policy Rules Management tab.
     
  8. Repeat steps 5 through 7 for the remaining rules.
  9. Click Refresh.

Deleting 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 deselecting 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, 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.
    3. 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 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:

To add a new policy rule to the CMS configuration:

  1. In the Policy Rules Management tab, click Add.
    2. 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.
  3. Click Next.
    4. The Policy Rule Editor window appears, listing the configuration information.
     
  4. Enter the appropriate information.
  5. Click OK.
    6. You are returned to the Policy Rules Management tab.
     
  6. Repeat steps 1 through 5 and create additional rules, if required.

Reordering Policy Rules

For maintaining priority levels, CMS 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.
    2. 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.
    3. 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.
    4. You are returned to the Policy Rules Management tab.
     
  4. To view the updated configuration, click Refresh.

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

  1. Enroll for a Certificate
  2. Approve the Request
  3. 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

CMS includes a facility for complex scripting of the policy plug-in instances via JavaScriptTM. Using the JavaScript policy processor allows you to:

CMS 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 CMS, consult the sample policy.js file included in the distribution:

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

Constraints-Specific Policy Module Reference

Constraints-specific policy plug-in modules help you define rules or constraints that CMS uses to evaluate an incoming certificate enrollment, renewal, or revocation request. Each module enables you to configure the server to check the request for particular attributes, and, based on the configured criteria, either modify these attributes or reject the request altogether.

AttributePresentConstraints

The AttributePresentConstraints plug-in module enables you to configure the Certificate Manager and Registration Manager to reject a request if an LDAP attribute (for example, pin) is not present in the enrolling user's directory entry or if the attribute does not have a specified value.

If you enable the policy and configure it correctly, it first searches for the user under the base specified in the ldap.ldapconn.basedn parameter with the filter (uid=HTTP_PARAMS.UID) for the user's entry.

Unlike some of the other policy modules, CMS does not create an instance of the attribute present constraints policy during installation.

Table 12-3 describes the configuration parameters of the AttributePresentConstraints policy.


Table 12-3    AttributePresentConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

ldap.ldapconn.host

 

Specifies the host name of the LDAP directory to connect to.

Permissible values: The name must be fully-qualified host name in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.example.com

 

ldap.ldapconn.port

 

Specifies the TCP/IP port at which the LDAP directory listens to requests from CMS.

Permissible values: Any valid port number. The default is 389; use 636 if the directory is configured for SSL-enabled communication.

 

ldap.ldapconn.secureConn

 

Specifies the type—SSL or non-SSL—of the port at which the LDAP directory listens to requests from CMS. Select for SSL, deselect for non-SSL.

 

ldap.ldapconn.version

 

Specifies the LDAP protocol version:

  • 2 specifies LDAP version 2. If your directory is based on Netscape Directory Server 1.x, choose 2.
  • 3 specifies LDAP version 3. For Directory Server versions 3.x and later, choose 3 (default).
 

ldap.ldapauth.bindDN

 

Specifies the user entry to bind as for checking the attribute in the LDAP directory.

Example: CN=pinmanager

 

password

 

Specifies the password associated with the DN specified by the ldap.ldapauth.bindDN parameter.

 

ldap.ldapauth.clientCertNickname

 

Specifies the nickname or the friendly name of the certificate to be used for SSL client authentication to the LDAP directory in order to check attributes. Make sure that the certificate is valid and has been signed by a CA that is trusted in the directory's certificate database, and that the directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory. (This is needed for PIN removal only.)

Example: Server-Cert

 

ldap.ldapauth.authtype

 

Specifies how to bind to the directory or the authentication type—basic authentication or SSL client authentication—required in order to check attributes in the LDAP directory:

  • BasicAuth specifies basic authentication (default). If you choose this option, be sure to enter the correct values for ldap.ldapauth.bindDN and password parameters; the plug-in uses the DN from the ldap.ldapauth.bindDN attribute to bind to the directory.
  • SslClientAuth specifies SSL client authentication. If you choose this option, be sure to select the ldap.ldapconn.secureConn parameter and set the value of the ldap.ldapauth.clientCertNickname parameter to the nickname of the certificate to be used for SSL client authentication.
 

ldap.ldapconn.basedn

 

Specifies the base DN for searching the LDAP directory—the plug-in uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters. (If your user's DN is uid=jdoe, o=company, you might want to use o=company here.)

Example: O=example.com

 

ldap.ldapconn.minConns

 

Specifies the minimum number of connections permitted (or to keep open) to the LDAP directory. Permissible values: 1 to 3; the default value is 1.

 

ldap.ldapconn.maxConns

 

Specifies the maximum number of connections permitted to the LDAP directory; when needed, connection pool can grow to this many (multiplexed) connections. Permissible values: 3 to 10; the default value is 5.

 

attribute

 

Specifies the LDAP attribute, the presence of which is to be checked in the certificate-enrollment request. Permissible values: Valid directory attributes, separated by commas; the default value is pin.

 

value

 

If this parameter is non-empty, the attribute value must match this value for the request to proceed to the next stage.

 


DSAKeyConstraints

The DSAKeyConstraints plug-in module imposes constraints on the following:

The policy restricts the key size to one of the sizes, such as 512 or 1024, supported by CMS.

You may apply this policy to end-entity certificate enrollment and renewal requests. For example, if you want your CA to certify public keys up to 512 bits in length for end users and 1024 for servers, you can configure CMS to do so using the policy.

During installation, CMS automatically creates an instance of the DSA key constraints policy, named DSAKeyRule, that is enabled by default.

Table 12-4 describes the configuration parameters of the DSAKeyConstraints policy.


Table 12-4    DSAKeyConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

minSize

 

Specifies the minimum length, in bits, for the key (the length of the modulus in bits). The value must be smaller than or equal to the one specified by the maxSize parameter. Permissible values: 512 or 1024. You may also enter a custom key size that is between 512 and 1024, in increments of 64 bits. The default value is 512.

 

maxSize

 

Specifies the maximum length, in bits, for the key. Permissible values: 512 or 1024. You may also enter a custom key size that is between 512 and 1024, in increments of 64 bits. The default value is 1024.

 

exponents

 

Limits the possible public exponent values. Use commas to separate different values.

Some exponents are more widely used than others. The following exponent values are recommended for arithmetic and security reasons: 17 and 65537. Of these two values, 65537 is preferred. (This setting is mainly an issue if you are using your own software for generating key pairs. Key-generation programs in Netscape clients and servers use 3 or 65537.)

Permissible values: A combination of 3, 7, 17, and 65537, separated by commas. The default value is 3,7,17,65537.

 


IssuerConstraints

The IssuerConstraints plug-in module enables you to effectively deploy certificate-based enrollment explained in Certificate-Based Enrollment.

The policy enables the Certificate Manager to authenticate an end user by checking the issuer DN of the CA that has issued the certificate the user presents as an enrollment token during enrollment. Note that in the current implementation, the CA that issues the new certificates must be the same as the one that has issued the certificates used for SSL client authentication; that is, the issuer DN in the authentication certificate must match the issuer DN specified in the policy configuration.

During installation, CMS automatically creates an instance of the issuer constraints policy, named IssuerRule, that is disabled by default.

Table 12-5 describes the configuration parameters of the IssuerConstraints policy.


Table 12-5    IssuerConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

issuerDN

 

Specifies the name of the CA that has issued certificates that are to be checked. You should enter the issuer name as it appears in the CA's signing certificate; the same name also appears as the issuer name in certificates the CA signs.

Example: CN=bulkGenCA,OU=Information Systems,O=Example Corporation,C=US

 


KeyAlgorithmConstraints

The KeyAlgorithmConstraints plug-in module restricts the key algorithm requested in certificates to the algorithms, such as RSA and DSA, supported by CMS. In other words, this policy allows you to set restrictions on the types of public keys certified by CMS.

You may apply this policy to end-entity certificate enrollment and renewal requests. For example, if you want your CA to certify only those public keys that comply with the PKCS-1 RSA Encryption Standard, you can configure the server for that using the policy.

During installation, CMS automatically creates an instance of the key algorithm constraints policy, named KeyAlgRule, that is enabled by default.

Table 12-6 describes the configuration parameters of the KeyAlgorithmConstraints policy.


Table 12-6    KeyAlgorithmConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

algorithms

 

Specifies the key type the server should certify. The default is RSA.

Permissible values: RSA or RSA.

 


RenewalConstraints

The RenewalConstraints plug-in module imposes constraints on renewal of expired certificates—it allows or restricts the server from renewing expired certificates. You may apply this policy to end-entity certificate renewal requests.

During installation, CMS automatically creates an instance of the renewal constraints policy, named RenewalConstraintsRule, that is enabled by default.

Table 12-7 describes the configuration parameters of the RenewalConstraints policy.


Table 12-7    RenewalConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable the rule (default). Deselect 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.

 

allowExpiredCerts

 

Specifies whether to allow or prevent renewal of expired certificates. Select if you want the server to renew expired certificates (default). Deselect if you don't want the server to renew expired certificates.

 

renewalNotAfter

 

Specifies how long, in days, after the expiration of a certificate can it be renewed. The default value is 30 days. If you leave the field blank, the server will renew all expired certificates that are submitted for renewal.

 


RenewalValidityConstraints

The RenewalValidityConstraints plug-in module governs the formulation of content in the renewed certificate based on the currently issued certificate.

The renewal validity constraints policy enables you to enforce certain restrictions on certificate-renewal requests, when end entities attempt to renew their certificates.

During installation, CMS automatically creates an instance of the renewal validity constraints policy, named DefaultRenewalValidityRule, that is enabled by default.

Table 12-8 describes the configuration parameters of the RenewalValidityConstraints policy.


Table 12-8    RenewalValidityConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

minValidity

 

Specifies the minimum validity period, in days, for renewed certificates.

 

maxValidity

 

Specifies the maximum validity period, in days, for renewed certificates.

 

renewalInterval

 

Specifies how many days before its expiration that a certificate can be renewed.

 


RevocationConstraints

The RevocationConstraints plug-in module imposes constraints on revocation of expired certificates—it allows or restricts the server from revoking expired certificates. You may apply this policy to end-entity certificate revocation requests.

During installation, CMS automatically creates an instance of the revocation constraints policy, named RevocationConstraintsRule, that is enabled by default.

Table 12-9 describes the configuration parameters of the RevocationConstraints policy.


Table 12-9    RevocationConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

allowExpiredCerts

 

Specifies whether to allow or prevent revocation of expired certificates. Select if you want the server to revoke expired certificates (default). Deselect if you don't want the server to revoke expired certificates.

 


RSAKeyConstraints

The RSAKeyConstraints plug-in module imposes constraints on the following:

The policy restricts the key size to one of the sizes supported by CMS—512, 1024, 2048, or 4096. In other words, the policy allows you to set up restrictions on the lengths of public keys certified by CMS.

You may apply this policy to end-entity certificate enrollment and renewal requests. For example, if you want your CA to certify public keys up to 1024 bits in length for end users, you can configure the server accordingly using the policy.

During installation, CMS automatically creates an instance of the RSA key constraints polic, named RSAKeyRule, that is disabled by default.

Table 12-10 describes the configuration parameters of the RSAKeyConstraints policy.


Table 12-10    RSAKeyConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable the rule (default). Deselect 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.

 

minSize

 

Specifies the minimum length, in bits, for the key (the length of the modulus in bits). The value must be smaller than or equal to the one specified by the maxSize parameter. Permissible values: 512, 1024, 2048, or 4096. You may also enter a custom key size that is between 512 and 4096 bits. The default value is 512.

 

maxSize

 

Specifies the maximum length, in bits, for the key. Permissible values: 512, 1024, 2048, or 4096. You may also enter a custom key size that is between 512 and 4096 bits. The default value is 2048.

 

exponents

 

Limits the possible public exponent values. Use commas to separate different values.

Some exponents are more widely used than others. The following exponent values are recommended for arithmetic and security reasons: 17 and 65537. Of these two values, 65537 is preferred. (This setting is mainly an issue if you are using your own software for generating key pairs. Key-generation programs in Netscape clients and servers use 3 or 65537.)

Permissible values: A combination of 3, 7, 17, and 65537, separated by commas. The default value is 3,7,17,65537.

 


SigningAlgorithmConstraints

The SigningAlgorithmConstraints plug-in module restricts the requested signing algorithm to be one of the algorithms supported by CMS: MD2 with RSA, MD5 with RSA, and SHA-1 with RSA, if the Certificate Manager's signing key is RSA and SHA-1 with DSA, if the Certificate Manager's signing key is DSA.

When a Certificate Manager digitally signs a message, it generates a compressed version of the message called a message digest. Some of the algorithms used to produce this digest include MD5 and SHA-1 (Secure Hash Algorithm).

You may apply this policy to end-entity certificate enrollment and renewal requests.

During installation, CMS automatically creates an instance of the signing algorithm constraints policy, named SigningAlgRule, that is enabled by default.

Table 12-11 describes the configuration parameters of the SigningAlgorithmConstraints policy.


Table 12-11    SigningAlgorithmConstraintsConfiguration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

algorithms

 

Specifies the signature algorithm the server should use to sign certificates.

Permissible values: Depends on the CA's signing key type (the key type you chose for the Certificate Manager's CA signing certificate).

  • If the key type is RSA, select one of the following:
    - MD2withRSA,MD5withRSA,SHA1withRSA
    - MD2withRSA,MD5withRSA
    - MD2withRSA,SHA1withRSA
    - MD5withRSA,SHA1withRSA
    - MD2withRSA
    - MD5withRSA
    - SHA1withRSA
    The default value is MD2withRSA,MD5withRSA,SHA1withRSA.
  • If the key type is DSA, select SHA1withDSA.
 


SubCANameConstraints

The SubCANameConstraints plug-in module restricts a CA from issuing a subordinate CA certificate that has the same issuer name as that of the CA itself—that is, the policy prevents a situation where the signing certificates of a CA and its subordinate CA have identical issuer names.

This policy must be turned on if you're planning to issue subordinate CA certificates. Whenever the Certificate Manager issues a certificate, it stores the related information in its internal database; if the CA issues a subordinate CA certificate with an issuer DN that matches its own issuer DN, the internal database will not function properly.

You may apply this policy to CA certificate enrollment and renewal requests.

During installation, CMS automatically creates an instance of the subordinate CA name constraints policy, named SubCANameConstraints, that is enabled by default.

Table 12-12 describes the configuration parameters of the SubCANameConstraints policy.


Table 12-12    SubCANameConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable, deselect to disable (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.

 


UniqueSubjectNameConstraints

The UniqueSubjectNameConstraints plug-in module restricts the server from issuing multiple certificates with same subject names. Optionally, you can also configure the server to allow multiple certificates with the same subject name if the key usages are different. Note that key usages for certificates are usually specified by the key usage extension and CMS allows you to add this extension to certificates using the key usage extension policy explained in KeyUsageExt.

You may apply the unique subject name constraints policy to end-entity certificate enrollment and renewal requests. For example, if you want to prevent your users from requesting multiple certificates with same subject names, you can configure the server accordingly using the policy. Alternatively, if you want to allow your users to own multiple certificates, each for a different use, all having the same subject name, you can do so easily using the enableKeyUsageExtensionChecking parameter defined in this policy. This parameter makes the server check whether the key usages specified in the certificate request being processed is different than those specified in the existing certificates that have the same subject names and accordingly issue or deny the certificate. Keep in mind that the server can check for key usages only if the key usage extension bits are set in the certificate request being processed as well as in the existing certificates that have the same subject names.

During installation, CMS automatically creates an instance of the unique subject name constraints policy, named UniqueSubjectNameConstraints, that is disabled by default.

Table 12-13 describes the configuration parameters of the UniqueSubjectNameConstraints policy.


Table 12-13    UniqueSubjectNameConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable, deselect to disable (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.

 

enablePreAgentApprovalChecking

 

Specifies whether the request must be checked for the subject name uniqueness on submission by the user, before the request gets queued for agent approval.

  • Select if you want the server to check the certificate request for the subject name uniqueness as soon as the user submits it.
  • Deselect if you want the server to check the certificate request for the subject name uniqueness after agent approval; that is, you want the policy to be applied to the request after an agent approves the request. You should choose this option if you want the server to check the Key Usage extension (see KeyUsageExt) before determining whether to issue the certificate.
 

enableKeyUsageExtensionChecking

 

Specifies whether the certificate request must be checked for the Key Usage extension. Note that the policy can check the certificate request for the Key Usage extension only if you deselect the enablePreAgentApprovalChecking parameter. The reason for this is that, extensions are set on the request after agent approval, so this checking can be done after an agent approves the request.

 

 
  • Select if you want the server to check the certificate request for the Key Usage extension. If you select, the server checks its internal database for certificates that have the same subject name as the one specified in the request. For each certificate that has the matching subject name, the server compares the Key Usage extension of the certificate to the one specified in the request. If the server finds a certificate that has the same subject name and Key Usage extension, it rejects request. Otherwise, the server approves the request. (This choice is suitable if you want to have multiple certificates with same subject names but for different purposes, such as signing and encrypting. If key-usage comparison is to be done, be sure to specify that this policy is to be applied after the Key Usage extension policy.
 

 
  • Deselect if you don't want the server to check the certificate request for the Key Usage extension. If you deselect, the server does not compare the Key Usage extension in the request with the ones set in the existing certificates that have the same subject name; it simply rejects requests with same subject names.
 


ValidityConstraints

The ValidityConstraints plug-in module 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:

If this policy rule is enabled, the server applies the rule to the certificate request being processed, and then determines if the validity period in the request is acceptable. The rule checks two X.509 attributes of the certificate, the notBefore and notAfter time, which together indicate the total validity life of a certificate, to make sure that they conform to the configured ranges.

The rule checks that the value of the notBefore attribute in the request is not more than leadTime minutes in the future; the leadTime is a configurable parameter in the plug-in implementation. The ability to configure the value of the leadTime parameter in the policy rule allows you to prohibit end entities from requesting certificates whose validity starts too far in the future, and yet allows some amount of toleration of clock-skew problems. For example, if the current date and time is 01/15/2000 (mm/dd/YYYY) and 1:30 p.m., the value of the notBefore attribute is set to 3:00 p.m., and that the leadTime is 10 minutes, then the request would fail, because the validity requested begins more than 10 minutes in the future.

The rule also checks that the value of the notBefore attribute in the request is not more than lagTime minutes in the past. For example, if the current date and time is 01/15/2000 (mm/dd/yyyy) and 1:30 p.m., the value of the notBefore attribute is set to 1:15 p.m., and the lagTime is set to 10 minutes, the request would fail because the user has requested a certificate 15 minutes in the past. Note that a request with notBefore set to 1:25 p.m. would have passed, however.

Note  

When applying the validity constraints policy, the server does not check the lag time in all certificate requests. It checks the lag time only in those requests that are based on the CRMF protocol—currently, CRMF is the only enrollment format that allows an end entity to request a specific validity period with the notBefore attribute set to a time in the past.

You may apply this policy to end-entity certificate enrollment requests.

During installation, CMS automatically creates an instance of the validity constraints policy, named DefaultValidityRule, that is enabled by default.

Table 12-14 describes the configuration parameters of the ValidityConstraints policy.


Table 12-14    ValidityConstraints Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable (default), deselect to disable.

 

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.

 

minValidity

 

Specifies the minimum validity period, in days, for certificates.

 

maxValidity

 

Specifies the maximum validity period, in days, for certificates.

 

leadTime

 

Specifies 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 notBefore attribute value specifies the date on which the certificate validity begins; validity dates through the year 2049 are encoded as UTCTime, dates in 2050 or later are encoded as GeneralizedTime.

 

lagTime

 

Specifies 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 notBefore attribute value specifies the date on which the certificate validity ends; validity dates through the year 2049 are encoded as UTCTime, dates in 2050 or later are encoded as GeneralizedTime.

 

notBeforeSkew

 

Specifies 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 beforeFix parameter to 10 minutes would adjust the value of the notBefore parameter to 11:20 a.m.—thus making the certificate usable following the download.

 


Extension-Specific Policy Module Reference

To enable you to add standard and private extensions to end-entity certificates, CMS provides a set of policy plug-in modules; each module enables you to add a particular extension to a certificate request.

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.

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

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

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

Additionally, the server also provides a module for adding any custom, ASN.1 type extensions. If you determine that the default policy modules do not meet your requirements entirely, you can develop a custom module using CMS SDK.

AuthInfoAccessExt

The AuthInfoAccessExt plug-in module enables you to add the Authority Information Access Extension. The extension specifies how an application validating a certificate can access information, such as on-line validation services and CA policy statements, about the CA that has issued the certificate. Note that this extension should not be used to point directly to the CRL location maintained by a CA; the CRL Distribution Points extension explained in CRLDistributionPointsExt allows you to reference to CRL locations.

For general information about this extension, see authorityInfoAccess.

During installation, CMS automatically creates an instance of the authority information access extension policy, named AuthInfoAccessExt, that is disabled by default.

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

Note  

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




Table 12-15    AuthInfoAccessExt Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable, deselect to disable.

 

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.

 

critical

 

Specifies whether the extension should be marked critical or noncritical. Select to mark critical, deselect to mark noncritical (default).

 

numADs

 

Specifies the total number of access locations to be contained or allowed in the extension. The default is set to 3. You can set 0 specifying no locations can be contained in the extension, or any integer <n>, number of fields.

 

 

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.

 

ad<n>_method

 

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

 

 

Permissible values:

  • ocsp (or 1.3.6.1.5.5.7.48.1).
  • caIssuers (or 1.3.6.1.5.5.7.48.2).
  • renewal (or 2.16.840.1.113730.16.1)
 

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. Select one type from the following:

  • Select rfc822Name if the location is an Internet mail address.
  • Select directoryName if the location is an X.500 directory name.
  • Select dNSName if the location is a DNS name.
  • Select ediPartyName if the location is a EDI party name.
 

 
  • Select URL if the location is a uniform resource identifier (default).
  • Select iPAddress if the location is an IP address.
  • Select OID if the location is an object identifier.
  • Select otherName if the location is in any other name form.
 

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. Specifying the information based on the following:

 

 
  • If you selected rfc822Name, the value must be a valid Internet mail address in the local-part@domain format. You may use upper and lower case letters in the mail address; no significance is attached to the case. For example, ocspResponder@example.com.
 

 
  • If you selected directoryName, the value must be a string form of X.500 name, similar to the subject name in a certificate. For example, CN=corpDirectory, OU=IS, O=example.com, C=US.
 

 
  • If you selected dNSName, the value must be a valid domain name in the preferred-name syntax. You may use upper and lower case letters in the domain name; no significance is attached to the case. Do not use the string " " for the DNS name. Also don't use the DNS representation for Internet mail addresses. For example, ocspResponder.example.com.
 

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

 
  • If you selected URL, the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules. That is, the name must include both a scheme (for example, http) and a fully qualified domain name or IP address of the host. For example, http://ocspResponder.example.com:8000
 

 
  • If you selected iPAddress, the value must be a valid IP address specified in dot-separated numeric component notation. The syntax for specifying the IP address is as follows:
    IPv4 address must be in the n.n.n.n format; for example, 128.21.39.40. IPv4 address with netmask must be in the n.n.n.n,m.m.m.m format. For example, 128.21.39.40,255.255.255.00.
    For IP version 6 (IPv6), the address should be in the form with netmask separated by a comma. Examples of IPv6 addresses with no netmask are 0:0:0:0:0:0:13.1.68.3 and FF01::43. Examples of IPv6 addresses with netmask are 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:
    FFFF:255.255.255.0     and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.
 

 
  • If you selected OID, the value must be a unique, valid OID specified in dot-separated numeric component notation. Although you can invent your own OIDs for the purposes of evaluating and testing this server, in a production environment, you should comply with the ISO rules for defining OIDs and for registering subtrees of IDs. See <<<XREF Appendix B, "Object Identifiers">>> for information on allocating private OIDs. For example, 1.2.3.4.55.6.5.99.
 

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


AuthorityKeyIdentifierExt

The AuthorityKeyIdentifierExt plug-in module enables you to add the Authority Key Identifier Extension to certificates. The extension is used to identify the public key that corresponds to the private key used by a CA to sign certificates.

For general information about this extension, see authorityKeyIdentifier.

For information on setting the subject key identifier extension in certificates, see SubjectKeyIdentifierExt.

During installation, CMS automatically creates an instance of the authority key identifier extension policy, named AuthorityKeyIdentifierExt, that is enabled by default.


Table 12-16    AuthorityKeyIdentifierExt Configuration Parameters  


Parameter

Description

enable

 

Specifies whether the rule is enabled or disabled. Select to enable, deselect to disable.

 

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.

 

critical

 

Specifies whether the extension should be marked critical or noncritical. Select to mark critical, deselect to mark noncritical (default).

 

AltKeyIdType

 

Specifies what should be done if the CA certificate does not have a Subject Key Identifier extension. Select either of the following:

  • Select SpkiSHA1 if you want the server to use a SHA-1 hash of the CA's subject public key information (default).
  • Select None if you don't want the server to set the authority key identifier extension in certificates.
 


BasicConstraintsExt

The BasicConstraintsExt plug-in module enables you to add the Basic Constraints Extension in certificates. The extension identifies whether the Certificate Manager is a CA. The extension is also used during the certificate chain verification process to identify CA certificates and to apply certificate chain-path length constraints.

For general information about this extension, see basicConstraints.

During installation, CMS automatically creates an instance of the basic constraints extension policy, named BasicConstraintsExt, that is enabled by default.


Table 12-17    BasicConstraintsExt Configuration Parameters  


Parameter

Description

enable