| Oracle® Application Server Certificate Authority Administrator's Guide 10g (10.1.4.0.1) Part Number B15989-01 |
|
|
View PDF |
| Oracle® Application Server Certificate Authority Administrator's Guide 10g (10.1.4.0.1) Part Number B15989-01 |
|
|
View PDF |
Oracle Application Server Certificate Authority automatically enforces the policies specified by the organization to apply to requests for certificate issuance, revocation, or renewal. The policy rules supplied with OracleAS Certificate Authority support standard needs. They are, however, configurable by the administrator, using the Configuration Management tab of the OracleAS Certificate Authority web interface, or by adding custom policy plug-ins to meet the site's needs. The administrator can also bypass policies by disabling them, if needed.
This chapter explains the policy management component of OracleAS Certificate Authority, including the tools for developing custom policy plug-ins.
Topics in this chapter include:
Table 6-1 Policy Concepts, Terms, and Definitions in OracleAS Certificate Authority
| Concept or Term | Definition |
|---|---|
|
In Oracle Application Server Certificate Authority, a policy rule is a set of defaults and ranges for the values of parameters that apply to certificates, requests, and so on. For example, a policy rule for validity period can specify 365 days as the minimum validity, 730 days as the default, and 3650 days as the maximum. Policy rules can also contain predicates, which limit or alter the application of the rule. Without predicates, a policy rule for a particular operation, such as renewal, applies to all such requests. |
|
|
A predicate, in OracleAS Certificate Authority, is an expression you create to identify a type of certificate or certificate request, plus corresponding values. When the type of certificate or certificate request matches the predicate expression, these corresponding values are used to evaluate the request's validity, instead of the policy's default values. Predicates are available only for OracleAS Certificate Authority default policies; they cannot be used with custom policies, which are discussed at section "Developing a Custom Policy Plug-in". Examples: Type=="client", Type=="server", or Type=="*" |
|
|
A Java class that implements a policy rule. |
Policy management means formulating and applying policies (sets of rules) chosen by the Oracle Application Server Certificate Authority administrator to enforce organizational constraints. Constraint examples include the choices offered to the user for selecting key size and validity period.
As the administrator, you can use policies shipped with OracleAS Certificate Authority to define the following operations:
How OracleAS Certificate Authority is to evaluate incoming requests for certificate issuance, revocation, and renewal
What restrictions the CA is to impose on certificate parameters, such as validity length and key length, or on the issuance of multiple certificates with the same subject name and intended usage
You can enable, disable, or modify policy rules using the edit capability of the Configuration Management tab in OracleAS Certificate Authority's web interface. See the section entitled "Policy Sub-tab of Oracle Application Server Certificate Authority".
You can also create new rules and develop policy plug-ins to embody them. Each rule is embodied in a policy plug-in, that is, a Java class that implements the evaluations or restrictions chosen by the administrator. There is a one-to-one mapping between a policy rule and a policy plug-in. OracleAS Certificate Authority's default plug-ins cover most of the common policy configuration needs. To write a policy plug-in, the administrator must follow good programming practices and use the APIs provided by the OracleAS Certificate Authority package, as described in "Developing a Custom Policy Plug-in" .
After developing a new plug-in defining a site-specific policy, you can use that same Policy subtab to name and describe it to OracleAS Certificate Authority. If you also enable it, OracleAS Certificate Authority will enforce the new rules as it does its own.
Policy rules are enforced by the policy processor module in the OracleAS Certificate Authority engine. This processor module applies all enabled rules sequentially; rules that are not enabled, or are disabled, are not enforced. The order used is the order in which they are listed on the Policy Rules page for each operation, in the Policy subtab. That is, the processor module calls the policy plug-ins in the order specified on the Policy Rules page for each operation. Every incoming request is subjected to all applicable enabled policy rules for that type of operation, that is, request, renewal, or revocation. If a rule is enabled and its terms are not met by an incoming request, that request is rejected.
Each policy rule relates to one or more attributes of a request for certificate issuance, revocation, or renewal. For example, one such attribute relates to minimum and maximum key sizes used in an RSA algorithm. The relevant default policy checks that all such attributes are within the algorithm's valid ranges.
Policies are administered through the web interface using the Policy subtab of the administrative interface.
Further details of policy processing involving predicates are discussed in the section titled "Predicates in Policy Rules".
Oracle Application Server Certificate Authority supplies constraint-specific policy rules that the policy processor uses to evaluate an incoming certificate enrollment, revocation, or renewal request. Within each rule, you can configure OracleAS Certificate Authority to check an incoming request for particular attributes, and either accept these attributes, alter them, or reject the request.
If a policy rule is enabled, the OracleAS Certificate Authority server applies the rule to the certificate request being processed
Table 6-2 lists the default constraint-specific policy rules; the first column contains links to the discussion of each policy rule.
Table 6-2 Default Constraint-specific Policy Rules
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.
Table 6-3 Parameters in the RSA Key Constraints Policy Rule
| Parameter | Description |
|---|---|
|
Default=Enabled |
Specifies (on the Policy Rules page) whether the rule is enabled or disabled. If you enable the rule and set the remaining parameters correctly, Oracle Certificate Manager applies the rule to certificates specified by the predicate expressions. If you disable the rule, the Oracle Certificate Manager allows the RSA key size to be any multiple of 16 between 512 and 4096 bits. |
|
Default: "*" |
Specifies the predicate expression for this rule, to limit the types of certificate to which this rule will apply. If you want the rule to be applied to certificate requests, type * in this field. Examples: Type=="client" Type=="*" |
|
Default=1024 |
Specifies the minimum length (bits), for the RSA key (the length of the modulus in bits). The value must be smaller than or equal to the one specified by the maxSize parameter. Valid values: 512, 1024, 2048, or 4096 bits. |
|
Default=2048 |
Specifies the minimum length (bits), for the key (the length of the modulus in bits). The value must be greater than or equal to the one specified by the minSize parameter. Valid values: 512, 1024, 2048, or 4096 bits. |
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 Marketing 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
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.
Table 6-4 Parameters in the ValidityRule Policy
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.
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.
Table 6-5 Parameters in the UniqueCertificateConstraint Policy Rule
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.
Table 6-6 Parameters in the Revocation Constraints Policy Rule
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.
Table 6-7 Parameters in 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.
When you first select the Policy sub-tab, Oracle Application Server Certificate Authority displays all the policy rules that can apply to certificate requests.
You can change the display to show the policy rules applicable to revocations or renewals by selecting either "Revocations" or "Renewals" from the drop-down box labeled "View Policies For". Oracle Application Server Certificate Authority then displays those policies. The policies shipped with OracleAS Certificate Authority, and the actions available to the administrator, are summarized in the following sections:
Policies specify the rules by which certificate requests are evaluated and by which issued certificates are renewed or revoked. You can add a policy for requests, revocations, or renewals and, if more than one policy exists, reorder the policies to alter the sequence in which they are applied. For each policy of a given type, you can view and edit its parameters and predicates, enable or disable it. Deletion of OracleAS Certificate Authority Default Policies are not allowed, but you can delete custom policies.
To add a policy, you must specify its name and description, and specify a class that you have previously added as a jar in the $ORACLE_HOME/oca/policy directory. (For Windows, %ORACLE_HOME\oca\policy.)
The administrator can disable any policy. Disabling a policy does not remove it from the possibility of future use, but rather resets an entry in the OracleAS Certificate Authority repository that can later be re-enabled. Deleting a policy makes it permanently unavailable (unless you later add it as if new).
Policies are enabled by an entry in the OracleAS Certificate Authority repository. Enabling a disabled policy (or one that was specified in the OracleAS Certificate Authority repository but not enabled) makes its parameters and predicates effective once again.
Policy parameters usually specify default limits or ranges that a certificate request must not violate or it will be rejected automatically. Some parameters simply enable or disable a capability or a constraint. Parameters apply to all circumstances except those specified in predicates.
Policy predicates identify specific types of certificates or requests for which the policy parameter limits, ranges, or constraints are specified to be different from the defaults for all other certificates or requests.
Changes you make to any Policy configuration parameters will take effect only after OracleAS Certificate Authority is restarted, as described in the section titled "Starting and Stopping Oracle Application Server Certificate Authority" in Chapter 4.
OracleAS Certificate Authority ships with policies that apply to certificate requests, revocations, and renewals, as discussed in the sections that follow.
The administrator can override the policy by unchecking the "apply policy" checkbox when issuing a certificate.
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.
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.
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.
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.
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".
When you select a policy and click Edit, Oracle Application Server Certificate Authority displays the screen for that policy, showing its parameters and predicates as currently set. For example, the screen for the key constraints policy shows the defaults for maximum and minimum key sizes. It also shows the predicates that change those defaults for specific certificate types.
On any such page, you can choose different values for the default parameters or for the specific values associated with the existing predicates. For standard policies, you can also change those predicates by typing in the Expression text box, reorder the predicates using the Reorder button, or add a predicate using the Add button. (See "Reordering Predicates" and "Adding Predicates".)
The Custom Policy edit screen will appear when you select a custom policy and click edit. The usual edit screen is only for default policies.
When you create a policy, you can choose to enable it. If you do, it will apply to the type of operation (request, revocation, or renewal) for which you specified it. If you do not enable it, or if you choose to disable it at some point, its parameters, defaults, and predicates will not apply to any request, revocation, or renewal.
However, a disabled policy remains available in the database. You can then later enable it at your discretion.
A deleted policy, on the other hand, is removed from the database, making it permanently unavailable unless re-entered as a wholly new policy.
On the Policy Rules page, the default OracleAS Certificate Authority policies cannot be deleted; only Custom Policies can be deleted. If you had added a custom policy, it would appear in the list, and you could select it and click Delete.
On the Edit page for a particular rule, you can select a predicate and click Delete. OracleAS Certificate Authority immediately removes that predicate and displays an informational message saying it has done so.
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:
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:
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:
When you click OK, you see that policy in the first position instead of where it had been, as shown on the following screen:
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".
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".
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".
Policy rules are specified and enforced according to certain conventions, as explained briefly in the section "Overview of Policy Management". This section explains the use of predicates in policy rules and supplies examples, in the following subsection:
"Multiple Predicate Evaluation", which had the following subsections:
|
Note: Policy rules cannot be shared across request types, that is, requests for certificate issuance, revocation, or renewal. |
A predicate specifies certain values and an expression used as a test of incoming certificate requests. The specified values are to be used instead of the policy's defaults if the predicate expression is matched by the corresponding elements of a certificate request. When a match occurs, the values associated with that predicate expression are used to evaluate the request's validity and set its parameters, instead of the policy's default values.
Predicates are optional, and they cannot be used in custom policies.
You can specify predicates in the web interface for a rule within a default policy. Once specified, the predicates are matched with every incoming request for the particular certificate operation the policy applies to, that is, request, revocation, or renewal.
If an incoming certificate or certificate request matches no predicate expression, or if the rule has no predicates, then the default values, ranges, or actions specified for the policy are used to evaluate the request. For example, values in the request are checked to verify they are in the correct default range specified in the policy. If they are, the request will be honored. Values that do not match the specified defaults or are not in the specified ranges cause the request to be rejected with an informational error message.
If an incoming certificate or certificate request does match a type specified in a predicate, then the defaults or ranges in the rule are not applied to that certificate or certificate request. The only values that can be applied to it are those you specify as corresponding to that predicate.
Thus, as an administrator, you can enhance a rule in a default policy and configure it for different user populations. For example, you can set a longer validity period for the "Development" department than for the "Sales" department.
The predicate expression is a logical expression. You form the expression using variables and relational operators. For example, you could set up a predicate to set different validity dates for certificates for users in different groups.
The following are valid sample predicate expressions:
Type==client AND DN=="ou=Sales,o=oracle,c=us" Type==server AND DN=="o=Oracle,c=us"
Table 6-8 lists the logical operators used in predicate expressions.
Table 6-8 Logical Operators
| Operator | Description |
|---|---|
|
== |
Equal to |
|
!= |
Not equal to |
|
AND |
Logical operator AND |
The following rules use the delimiter ":=" to separate the name of the policy expression and its valid syntax. They show what is valid in constructing policy expressions:
Predicate expression := Expression | AndExpression AndExpression := Expression AND Expression Expression := Attribute op Value Attribute := <attrib_name> op: == or != Value := a string
OracleAS Certificate Authority does not support operators such as OR, <, and >. You can implement the OR logical expression by splitting the predicate into multiple predicates and specifying the same value. (The policy plug-ins and APIs support multiple predicates.) In the predicates, values can be any string enclosed in double quotes. Attribute is always specified as <attrib_name>. All predicate expressions and string values are case-insensitive. A Value in an Expression can be set to "*" to match every "attribute" under consideration, for example, type=="*" matches all the certificate types. However, using "*" with any other string to form partial-pattern string matching is not supported.
Table 6-9 describes the attributes and the values they can have.
Table 6-9 Predicate Attributes
OracleAS Certificate Authority uses DNs as specified in RFC1779, with the most significant component last. For example, in the well-formed DN "cn=user31415,ou=security,ou=ST,o=Oracle,c=US", cn is the least significant component and c is the most significant one. A comma must separate each DN field from the next.
The term RDN stands for "relative distinguished name," meaning the most granular level local entry name that needs no further qualification to address an entry uniquely. If an RDN appears multiple times, then the least significant RDN, specified first, is understood to be a child of the RDN occurring next. In the earlier example, since "ou=security" appears before "ou=ST", "security" is understood as a sub-division under "ST" division.
A DN specified in the predicate can start at any RDN but should complete at the root. For example, "ou=ST,o=Oracle,c=US" is a valid partial DN that can be specified, whereas "ou=ST,o=Oracle" is an invalid partial DN as it stops at "o=Oracle" and does not contain the root (that is, "c=US").
To support the big-endian order, where the most significant component is first, OracleAS Certificate Authority internally converts it to little-endian order before DN matching is done, for policy evaluations only.
When DN components are matched against a DN expression mentioned in a predicate expression, the following rules are applied:
The predicate matches the DN if the whole predicate is a last part of the DN.
For example, if the predicate expression is
then it would match all of the following DNs:
"cn=user31415,ou=ST,o=Oracle,c=US"
"cn=quser2787,ou=security,ou=ST,o=Oracle,c=US"
"cn=kuser987,ou=security, ou=DAS,ou=ST,o=Oracle,c=US"
However, the predicate expression fails to match the following DNs:
"cn=user31415,ou=DAS,ou=ST,o=Oracle,c=IN"
"cn=quser2787,ou=ST, ou=pki, o=Oracle,c=US"
"cn=kuser987,ou=ST,o=Oracle, st=CA,c=US"
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.
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.
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.)
Evaluation of multiple predicates can be subtle. They are applied in the top-down order in which they are listed on the Edit page of the Configuration Management tab in the Oracle Application Server Certificate Authority web interface. The sequence is important.
Suppose the first predicate listed in a policy specifies Type=="client" and OU=="Oracle" and CN=="Clay", and then sets the keylength to 2048.
Then, suppose a later predicate in that same policy specifies Type=="client" and OU=="Oracle", setting the keylength to 512.
Then only client requests from Clay will have the keylength set to 2048; all other Oracle client requests will have it set to 512.
However, if the order is reversed, so that the more general predicate is earlier in the policy, even Clay will have a keylength of 512. The more specific predicate will never be encountered, since only the one earlier in the sequence, the more general one, will be acted on for this policy.
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:
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:
Clicking OK would then make that the predicate order for the rule, as shown here:
Notice that OracleAS Certificate Authority also displays an Information message acknowledging the changed order.
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:
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).
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:
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:
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.
The default policy plug-ins shipped with OracleAS Certificate Authority are generic. To enhance the policy structure for specific organizational requirements, an administrator can write a custom plug-in using the framework OracleAS Certificate Authority provides. This framework includes APIs to get information about certificates and certificate requests, and a few generic functions. To implement a custom plug-in, an administrator must write a Java class and register it with OracleAS Certificate Authority, which is also called "adding a policy."
The following situations are appropriate examples of goals for developing custom plug-ins to handle:
To use an additional corporate account repository to validate user requests
To set additional fields based on other user repositories
The APIs provided by OracleAS Certificate Authority enable the administrator's custom plug-in to acquire request parameters and the attributes of certificates and certificate requests.
The following subsections describe tools and examples to aid an administrator in developing custom plug-ins if the organization requires them:
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:
Table 6-10 Steps in Custom Policy Plug-in Processing
Use these steps to create a new policy plug-in:
Write a Java class that implements the OCACustomPlugin interface, using the sample implementation shown in the next section as a guide.
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.
Use the jar utility to jar the class file.
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
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.
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.
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
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
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.
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.
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
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.
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
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.
|
See Also: The Javadoc provided with the other documentation for descriptions of the classes and methods provided in OracleAS Certificate Authority Custom plug-in, and the constants available for your use. |
|
Note: The generic error messages supported by OracleAS Certificate Authority are translated into the languages supported by OracleAS Certificate Authority, so they are available to use in custom plug-ins as well. By using these constants, these error messages are available to be rendered in any of the languages supported by OracleAS Certificate Authority.If these messages are not used, then any valid java string can be used. However, these java strings will not have been translated, and so they will be rendered simply as they are supplied. |
