6 Managing Policies in Oracle Application Server Certificate Authority

6.3.1 RSAKeyConstraints

The RSAKeyConstraints policy rule imposes constraints on the minimum and maximum key sizes used for RSA public/private keys.

Table 6-3 describes the parameters of the RSA key constraints module.

An administrator can specify multiple sets of predicates, minSize, and maxSize using complex predicate expressions.

For example, an organization might need (minsize, maxsize) for Sales and Finance departments to be (512,1024) and (1024,2048), respectively. Multiple predicate expressions and value sets can be used to specify this requirement:

Predicate 1: dn=="ou=Sales"

minSize, maxSize are specified as 512,1024

Predicate 2: dn=="ou=Marketing"

minSize, maxSize are specified as 1024,2048

6.3.2 ValidityRule

The ValidityRule policy rule determines if the validity period in the certificate request is acceptable and enforces the minimum and maximum validity dates as follows:

• For automatic-user certificate requests (OracleAS Single Sign-On Server or SSL authentication), this rule sets the validity period.

• If a request for a manual user certificate or a server certificate does not meet the policy, that request is rejected.

• Irrespective of the validity set by this rule, the expiration date of the certificate cannot be later than that of the CA certificate. This check cannot be disabled.

Table 6-4 describes the parameters for the issuance validity constraints module. The illustration at the end of this section shows how they appear in the web interface.

If this rule is disabled, OracleAS Certificate Authority issues certificates with the validity specified in the certificate request, as long as that period is less than or equal to the validity period of the certificate of the CA.

For the automatic client users (that is, OracleAS Single Sign-On server- and SSL-authenticated users), the validity is automatically set by using the "Default Validity period" in the matching predicate specified in the policy. For all other users, validity is expected as part of the certificate request. This capability enables an administrator to specify the exact validity period that automatic users will get, eliminating the need for such users to enter this value.

The validity period that applies to the Certificate Authority can be 5 years or even 10 years. The longer the validity period is for the CA, the longer its issued certificates remain valid without the need for renewal or replacement. The installation process for OracleAS Certificate Authority uses a default of 10 years for the root CA. The following illustration shows the validity-rule parameters.

6.3.3 UniqueCertificateConstraint

The UniqueCertificateConstraint policy rule prevents OracleAS Certificate Authority from issuing multiple certificates to the same subject name for the same usage. When enabled, this policy can reject such a request, if the parameter in the policy is set to prohibit multiple such certificates.

The policy checks the incoming request against the Oracle Application Server Certificate Authority repository for any certificates matching the subject DN of the incoming certificate request. If an existing certificate is found for the subject DN, then the certificate usages (encryption, signing, and so on.) are checked. If there is an existing certificate for the requesting DN that also specifies the same usage as is being requested, the request is rejected if the policy is set to reject multiples.

Table 6-5 describes the parameters for the UniqueCertificateConstraint module.

6.3.4 RevocationConstraints

The OracleAS Certificate Authority Administrator can restrict revocation of expired certificates by applying this policy to user certificate revocation requests. If this policy is enabled, revocation of an expired certificate is allowed after its expiration date. If you don't want to allow revocation of expired certificates in your PKI setup, you can use the policy to configure Oracle Application Server Certificate Authority accordingly.

Table 6-6 describes the parameters of the revocation constraints module.

6.3.5 RenewalRequestConstraint

The OracleAS Certificate Authority Administrator can restrict the time window during which renewal of certificates is allowed by applying this policy to certificate renewal requests (including the administrator certificate renewal). If this policy is enabled, a user cannot renew a certificate outside the range of days specified around its expiration date. You can exclude or constrain renewal of expired certificates in your PKI setup by configuring this policy accordingly.

Table 6-7 describes the parameters of the renewal constraints policy rule.

All OracleAS Certificate Authority policies are managed by the OracleAS Certificate Authority administrator using the policy subtab of the administrative web interface.

6.4.1 Default Certificate Request Policies

Certificate requests must satisfy the parameters and predicates of the policies that restrict four factors important to security. You can adjust the parameters and predicates affecting the following factors in the default policies:

• Narrow or widen the range of key sizes, and set the defaults for RSA public/private keys

• Narrow or widen the range of validity periods, and set the defaults

• Allow or disallow a user to have multiple certificates for each type of usage, that is, for signing, key encipherment, or data/email encipherment, respectively designated signing, certificate signing, or encryption (SMIME, "Secure Multipurpose Internet Mail Extensions")

• Allow or disallow the use of trusted-certificate-DNs as certificate applicants or owners.

6.4.2 Default Certificate Revocation Policy

The RevocationConstraintRule is an OracleAS Certificate Authority default policy shipped with Oracle Application Server Certificate Authority. You can set parameters and predicates on this policy as required, such as to allow or disallow revocation of expired certificates.

6.4.3 Certificate Renewal Policy as Shipped

You can set the parameters and defaults for the RenewalRequestConstraint policy, which establish whether and when certificates can be renewed, and for how long. You specify the window within which renewal is to be allowed, by setting a number of days before and after the certificate's established expiration date. The default is 10 days before and after that date. You can also change the default renewal period, which is initially set at 365 days.

6.4.4 TrustPointDNCustomRule as Shipped

The TrustPointDNCustomRule is a custom policy, a sample plugin for an example OracleAS Certificate Authority policy, which is shipped with OracleAS Certificate Authority. This policy prevents user certificate requests from getting certificates in the name of some trusted Certificate Chain's DNs. For such plugins, you set the description, the name of the class implementing the policy, and specify in a checkbox whether this policy should be enabled.

6.4.5 Policy Actions

The buttons you see on the Policy Rules screen represent the actions you can take, which are described in the sections that follow: "Edit", "Enable or Disable", "Delete", "Reordering Policies", and "Adding Policies".

6.4.5.4 Reordering Policies

As an administrator, you can change the order in which policies are applied. For example, the default policies for certificate requests appear in the order shown on the following screen:

Description of the illustration policysubtab.gif

When you click Reorder, OracleAS Certificate Authority displays the list of existing policies. You can select and re-position them until you have your desired order, using the following screen:

Description of the illustration reorderonentry.gif

To move the Unique policy up two positions, click it to select it and then click the upward-pointing button two times, creating the following screen:

Description of the illustration confignwuniqueup3.gif

When you click OK, you see that policy in the first position instead of where it had been, as shown on the following screen:

Description of the illustration confignuniqueup3ok.gif

Note that OracleAS Certificate Authority displays an Information message alerting you to the change.

The predicates within a policy rule can also be reordered in a similar way. See the section titled "Reordering Predicates".

6.4.5.5 Adding Policies

On the Policy Rules page, you can click the Add button to add a new policy for the type of operation you were reviewing, that is, for requests, revocations, or renewals. Only custom policies can be added, as embodied in an object class that you have already defined and made available as a jar in the $ORACLE_HOME\oca\policy directory. OracleAS Certificate Authority displays a form for you to enter the new policy's name, description, and object class, and to specify whether it should be enabled. For more information on custom policy development, see "Developing a Custom Policy Plug-in".

Description of the illustration addacustompolicy.gif

See "Developing a Custom Policy Plug-in" for further explanation.

You can also add a predicate, within a policy rule, to any of the default policies displayed on the edit page for the policy. (Predicates cannot be added to custom policies.) See "Adding Predicates".

6.5.1 Multiple Predicate Evaluation

A policy rule can have more than one predicate. When the policy rule has multiple predicates, evaluation begins by comparing the first predicate expression against the incoming certificate request object. If it matches, the rule is applied. If not, then evaluation compares the next predicate expression against that request. This procedure continues until a predicate matches the certificate request object or, if no predicates match, the policy rule's default values are applied.

No attempt is made to find the best match: the first match that occurs is used. The administrator is responsible for specifying the order of predicates in the manner most appropriate to the organization.

One criterion is to place, at the top of the rules, those predicate expressions targeted for specific matches and least-significant RDNs, so they will be evaluated first.

6.5.1.1 Evaluation Example for Multiple Predicates

The following example demonstrates how a rule evaluates multiple predicates. In this example, the policy rule is about the key sizes used by the RSA rule. The rule has two predicate expressions, about server certificates and client certificates, specifying corresponding minimum and maximum key sizes. If an incoming server or client certificate request specifies a key size outside the range specified for its corresponding predicate, the rule will reject it.

Description of the illustration keysizeexample.gif

If neither predicate expression matches the incoming certificate request, then the rule compares the requested key size with the minimum and maximum specified as defaults. If the requested key size is outside this range, the request is rejected; otherwise, it is approved. (The factual default range as shipped is 512 to 4096. If the administrator has chosen Microsoft Strong Cryptographic Provider, the default size for the key that is generated is normally 1024. However, in some Windows environments the "Strong" choice creates 4096-bit keys.)

6.5.1.3 Reordering Predicates

You can reorder predicates in a manner similar to reordering policies, as described in "Reordering Policies". If you click Reorder on a page displaying predicates, like the one shown in the "Evaluation Example for Multiple Predicates" section, Oracle Application Server Certificate Authority displays a screen of the following type:

Description of the illustration reorderpredicates.gif

Select the predicate you wish to move, by clicking it, and then click one of the reordering arrowhead buttons: the predicate will move in the direction you chose. For example, if you reversed the order of the predicates in the "Evaluation Example for Multiple Predicates", you would see the following screen:

Description of the illustration prdctsreordsbscrn.gif

Clicking OK would then make that the predicate order for the rule, as shown here:

Description of the illustration mainscrnprdctsreord.gif

Notice that OracleAS Certificate Authority also displays an Information message acknowledging the changed order.

6.5.1.4 Adding Predicates

You can add a predicate by clicking Add Another Row on a page displaying predicates. OracleAS Certificate Authority displays a blank row for you to fill:

Description of the illustration addingaprdctstart.gif

If you fill in the blank row with a valid predicate, as shown in this screen, it will be accepted when you press OK (which also returns you to the main policy page).

Description of the illustration addingdone.gif

On the Edit page for a specific policy, you can add a predicate by clicking Add Another Row. An example of a predicate is requiring that requests for a server certificate use a higher range of key lengths than required of end-user certificate requests, as in this screen:

Description of the illustration keysizeexample.gif

When you click Add Another Row, OracleAS Certificate Authority displays an empty additional predicate row, where you can type your new predicate into the Predicate Expression box. You also specify the capability or default parameter range to be used when the predicate is matched:

Description of the illustration prdctaddnampolicyrule.gif

If you specify a predicate that is invalid or already present for this rule, an error message appears.

When you have specified the predicate to your satisfaction, click OK. OCA displays the original page for this rule with your new predicate row added at the bottom.

6.6.1 What Processing Does a Policy Do?

A custom plug-in can be written by implementing OCACustomPolicyPlugin interface. OCAPolicyRequest object, which is passed to the 'enforce' method of this interface, has all the essential attributes (of the certificate or certificate request) and their values set. The custom plug-in can read these objects to get or set attributes of the certificate request or certificate.

The following steps are involved in custom policy plug-in processing:

6.6.2 Steps in Creating a New Policy Plug-in

Use these steps to create a new policy plug-in:

1. Write a Java class that implements the OCACustomPlugin interface, using the sample implementation shown in the next section as a guide.

2. Save the java class implemented in step 1 and compile after adding $ORACLE_HOME/oca/lib/oca-1_3.jar to the java CLASSPATH and obtaining the class file.

3. Use the jar utility to jar the class file.

   1. For example, the code in the previous section would be jar'd and kept in example.jar.

      To jar the class, use the jar utility available under the $ORACLE_HOME/jdk/bin directory.

      • To create example.jar, execute:

        $ORACLE_HOME/jdk/bin/jar cvf example.jar oca
        

      • where example.jar is the jar file name and OracleAS Certificate Authority is the package directory that contains custom/policy/plugin/examplePlugin.class

   2. If you then were to execute 'jar tvf example.jar', you would see the examplePlugin.class file under the directory structure oca/custom/policy/plugin.

4. Place this jar file into the $ORACLE_HOME/oca/policy directory. (For Windows platforms, the slashes become backslashes):

   $ORACLE_HOME\oca\policy\

   This directory is pre-created by Oracle Application Server Certificate Authority.

5. Stop OracleAS Certificate Authority, OracleAS Certificate Authority's OC4J, and OHS. Use the following commands in ORACLE_HOME:

   $ORACLE_HOME/oca/bin/ocactl stop
   $ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca
   $ORACLE_HOME/opmn/bin/opmnctl stopproc type=ohs
   
   

6. Start OHS, OracleAS Certificate Authority's OC4J, and OracleAS Certificate Authority, in that order. Use these similar commands:

   $ORACLE_HOME/opmn/bin/opmnctl startproc type=ohs
   $ORACLE_HOME/opmn/bin/opmnctl startproc type= oc4j instancename=oca
   $ORACLE_HOME/oca/bin/ocactl start
   
   

   
   Description of the illustration addacustompolicy.gif
   
   

7. Use the OracleAS Certificate Authority Administrator's web interface to add your custom policy to define your new rule.

   That is, navigate to the Policy Rules page within the Policy subtab of Configuration Management, click the Add button, and fill in the fields. You supply the name, description, and class for your custom policy, click the enable checkbox to enable it, and then click OK.

8. Restart OracleAS Certificate Authority, as described in the section titled "Starting and Stopping Oracle Application Server Certificate Authority" in Chapter 4, "Introduction to Administration and Certificate Management". Only after OracleAS Certificate Authority is restarted will the new jar be found and recognized, and the rule be able to come into effect. After this step, the custom policy will be applied to requests for certificates, renewals, or revocations, depending on which section was modified by adding this plug-in.

6.6.3 Rules for Custom Policies

While developing custom policy plug-ins, keep the following ground rules in mind:

• There should be no spaces in the policy name

• Make sure the class exists in the specified directory

• The class should implement a particular interface

6.6.4 An Example of a Custom Policy Plug-in

You need to implement OCACustomPolicyplugin interface to write a custom plug-in.

The first step in supplying your own policy plug-in is to create a new Java class.

This section shows you an example of a custom policy plug-in that ensures that the country code in the certificate request is not US.

1:    package oca.custom.policy.plugin; 
2:    import oracle.security.oca.exception.OCMException; 
3:    import oracle.security.oca.policy.custom.OCACustomPolicyplugin; 
4:    import oracle.security.oca.policy.OCAPolicyRequest; 
5:    import oracle.security.oca.policy.OCMPolicyConstants; 
6:    public class PolicyCustomPlugin implements OCACustomPolicyPlugin 
7:    {                                 // ends at line 35
8:       public boolean enforce (OCAPolicyRequest policyRequest)
9:       {                          // ends at line 34
10:      // Add the functionality here. 
11:      // Assume the plug-in should reject all requests with country code as US. 
12:               if (!policyRequest.getCountry().equals("US")) 
13:               { 
14:                      //Plug-in check succeeded. Country ID in request is not US. 
15:                        //Hence return true. 
16:                        return true; 
17:                } 
18:                else 
19:                {                   // ends at line 33
20:                       //Plug-in check failed: Country ID in request is US. Set error and return false. 
21:    try
22:    {
23:                        policyRequest.setError("PolicyCustomPlugin",OCMPolicyConstants.POLICY_ERROR, 
                                                 "Country ID cannot be US."); 
24:                      //The first parameter is the plug-in name. 
25:                     //The second parameter is the status, which is an ERROR. 
26:                    //The third parameter is the Message to be displayed. 
27:     } 
28:   catch(OCMException e) 
29:  { 
30:     //enter exception handling here 
31:   } 
32:                        return false; 
33:                } 
34:        } 
35:    } 

In this example, line 1 is the package to which this custom policy plug-in belongs. The custom policy plug-in can belong to any package other than a package that starts with 'oracle.security.oca'.

Lines 2 through 5 import the class files required. The Javadoc API documentation contains the details of these files.

Line 6 implements the OCACustomPolicyPlugin interface. The custom policy interface must be implemented by all custom plug-ins. The interface that OracleAS Certificate Authority gives belongs to the package oracle.security.oca.policy.custom and is available in $ORACLE_HOME/oca/lib/oca-1_3.jar.

Line 8 implements the method that will contain the functionality of this plug-in. So when the policy processor invokes this plug-in it will invoke the 'enforce' method.

Line 9 through 28 begins the functionality for this plug-in

Line 12 checks if the country code is not US. The API documentation accompanying OracleAS Certificate Authority contains the details of the methods that can be used on policyRequest.

Line 16 returns success to the policy processor.

Line 18 introduces the handling for the error condition, exercised when the country code in the request is US.

Line 23 sets an error code into policyRequest. This error code is read by the policy processor and is rendered to the screen. You can see something similar when you get a new OracleAS Single Sign-On User certificate and immediately try to renew this certificate. The Renewal plug-in will generate an error.

Line 30 should be replaced by code to handle exceptions.

Line 32 returns an error status to the policy processor, indicating that the request failed the policy check and therefore will not be processed.

6.6.5 Generic Error Messages

Following are the generic error messages, and their associated constants, that can be set if any error is found while applying the policy. These messages are translated into the languages supported by OracleAS Certificate Authority, such as the following three:

• Invalid validity period

  "OCA_POLICY_INVALID_VALIDITY"

• Requested validity period exceeds validity of the CA certificate

  "OCA_POLICY_INVALID_VALIDITY_CA"

• Invalid Distinguished Name

  "OCA_POLICY_INVALID_DN"

For example, in the earlier custom policy example, if line 13 is changed to read

13: policyRequest.setError("examplePlug-in",OCMPolicyConstants.POLICY_ERROR, OCAPolicyMessage.OCA_POLICY_INVALID_DN);

then the output would show the "Invalid Distinguished Name" error.