|
A policy rule refers to a uniquely configured instance of any policy plug-in implementation; see "Built-in Policy Plug-in Modules" for a list of plug-in modules provided for Certificate Management System. 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
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:
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/sdkdocs
For general guidelines on developing custom policy modules and adding them to the CMS policy framework, take a look at the samples installed at this location: <server_root>/cms_sdk/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 16.1. For a list of attributes, see "Attributes for Predicates".
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
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:
Table 16.2 lists default attributes that are supported by various request object implementations.
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 "Validity Constraints Policy".
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:
Open the corresponding HTML file in a text editor.
Locate the section that lists the HTTP input variables.
Add this line: <input type="HIDDEN" name="orgunit" value="Sales">
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:
Create a new instance of the ValidityConstraints policy plug-in implementation.
Enter the appropriate values for all the attributes. Assume you
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
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.
|
Previous
