Chapter 18
Extension-Specific Policy Modules
Certificate Management System comes with a set of extension-specific policy plug-in modules that enable you to add X.509 certificate extensions to the certificates the server issues. This chapter explains those modules--it lists and briefly describes the modules that are installed with a Certificate Manager and Registration Manager, and then explains each one in detail.
The chapter has the following sections:
|
Certificate Extensions |
Since its initial publication, the X.509 standard for certificate formats has been amended to include additional information within a certificate. Version 3, the latest version, allows you to add additional information as certificate extensions. For example, Netscape applications (Netscape Navigator 3.0 or higher, and Enterprise Server 2.01 or higher) support an extension that specifies the type of certificate issued (such as client, server, or object signing).
The extensions defined for X.509 v3 certificates enable you to associate additional attributes with users or public keys and manage the certification hierarchy. The Internet X.509 Public Key Infrastructure Certificate and CRL Profile (see http://www.ietf.org/rfc/rfc2459.txt) recommends a set of extensions to be used in Internet certificates (and standard locations for certificate or CA information). These extensions are called standard extensions.
The standard also suggests that you can define your own extensions and include them in certificates you issue. These extensions are called private, proprietary, or custom extensions and they carry information unique to your organization or business. Keep in mind that applications may not able to validate certificates that contain private, critical extensions, thus preventing the use of these certificates in a general context.
Note
Some explanations in this chapter make reference to Abstract Syntax Notation
One (ASN.1) and Distinguished Encoding Rules (DER). These are specified in
the CCITT Recommendations X.208 and X.209. For a quick summary of ASN.1
and DER, see A Layman's Guide to a Subset of ASN.1, BER, and DER, which is
available at RSA Laboratories' web site (http://www.rsa.com).
Structure of Certificate Extensions
In RFC 2459, an X.509 certificate extension is defined as follows:
Extension ::= SEQUENCE {
Which means, a certificate extension consists of the following:
Examples of standard extensions defined in the X.509 v3 standard include the following:
Note that not all applications support certificates with version 3 extensions. Applications that do support these extensions may not be able to interpret some or all of these specific extensions.
Sample Certificate Extensions
The following is an example of the section of a certificate containing X.509 v3 extensions. (Certificate Management System can display certificates in human-readable format, as shown here.) As shown in the example, certificate extensions appear in sequence and only one instance of a particular extension may appear in a particular certificate; for example, a certificate may contain only one subject key identifier extension. Note that certificates that support these extensions have the version 0x2 (which corresponds to version 3).
Certificate:
Data:
Version: v3 (0x2)
...
Extensions:
Identifier: Certificate Type
Critical: no
Certified Usage:
SSL CA
Identifier: Subject Key Identifier
Critical: no
Value:
2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad
Identifier: Authority Key Identifier
Critical: no
Key Identifier:
2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad
Object Identifier
An object identifier (OID) is a string of numbers identifying a unique object, for example, a certificate extension or a company's certificate practice statement. For general information on OIDs, see the information at this URL:
http://www.alvestrand.no/objectid/
OIDs are controlled by the International Standards Organization (ISO) registration authority. In some cases, this authority is delegated by ISO to regional registration authorities. For example, in the United States, the American National Standards Institute (ANSI) manages this registration.
Registration of Object Identifiers
To promote interoperatability, the PKIX standard recommends that all objects (such as extensions and policy statements) that appear in certificates that will be used in networks shared by other organizations should be included in the form of OIDs. If you plan to issue certificates that will be used in such networks, you should register your object identifier prefixes with the appropriate registration authority. For example, assume you want to add a custom extension that points to a certificate practice statement (CPS) of your company. To implement this, you need to compose the policy statement you want to include in the extension, define an OID for the policy statement, and configure Certificate Management System with the OID so that it can add that to the certificate it issues.
The use of an OID registered to another organization or the failure to register an OID may carry legal consequences, depending on context. Registration may be subject to fees. For more information, you should contact the appropriate registration authority.
To define or assign OIDs for your objects, you must know your company's arc, which is an OID for a private enterprise. If your company doesn't have an arc, it needs to get one. This URL contains information on registering for a company arc:
http://www.isi.edu/cgi-bin/iana/enterprise.pl
To understand why you need to have a company arc, check the information at this site:
http://www.alvestrand.no/objectid/2.16.840.1.113730.1.13.html
The site contains information on Netscape-defined OID for an extension named Netscape Certificate Comment. Note that the OID assigned to this extension is hierarchical and it includes the Netscape company arc, which is 2.16.840.1.113730. Every OID Netscape owns has this prefix.
When determining whether to add custom extension to certificates, keep in mind that if the extension exists in a certificate and if it is marked critical, the application validating the certificate must be able to interpret the extension (including the optional qualifiers, if any), or else it must reject the certificate. Since it's unlikely that all applications will be able to interpret your company's extensions (embedded in the form of OIDs), the PKIX standard recommends that the extension be always marked noncritical. For general guidelines on setting extensions in certificates, see "Certificate Extensions" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
|
Overview of Extension-Specific Policy Modules |
To enable you to add standard and private extensions to end-entity certificates, Certificate Management System provides a set of policy plug-in modules; each module enables you to add a particular extension to a certificate request. Plug-in modules are implemented as Java classes and are registered in the CMS policy framework. The Policy Plugin Registration tab of the CMS window (Figure 18.1) lists all the modules that are registered with a CMS instance.
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. For general guidelines on using extensions in certificates, see "Certificate Extensions" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
Figure 18.1 Extension policy modules registered with a Certificate Manager
Table 18.1 lists extension-specific policy modules that are installed with a Certificate Manager. A Registration Manager installation also includes all the modules, expect for the ones noted below:
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 (see "Policy Processor"). 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.
As indicated in Table 18.1, Certificate Management System enables you to add almost all of the extensions defined in the PKIX standard RFC 2459 (http://www.ietf.org/rfc/rfc2459.txt). All modules have three features in common, enabling you to specify these:
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. It is 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 these locations:
<server_root>/cms_sdk/samples/policy and <server_root>/cms_sdk/samples/exttools
For instructions to configure a Certificate Manager and Registration Manager to use one or more of the policy modules, see "Configuring a Subsystem's Policies".
|
Authority Information Access Extension Policy |
The AuthInfoAccessExt plug-in module implements the authority information access extension policy. This policy enables you to configure Certificate Management System to add the Authority Information Access Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension specifies how the application validating the certificate can access information, such as on-line validation services and CA policy statements, about the CA that has issued the certificate in which the extension appears. Note that this extension should not be used to point directly to the CRL location maintained by the CA; the CRL Distribution Points extension explained in "CRL Distribution Points Extension Policy" allows you to reference to CRL locations.
The PKIX standard recommends that you may include the authority information access extension in end-entity and CA certificates and that the extension be marked noncritical. For general guidelines on setting the authority information access extension, see "authorityInfoAccess" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The authority information access extension policy in Certificate Management System allows you to set the authority information access extension as defined in its X.509 definition. The policy enables you to specify any number of access points for CA information. For each access point, you can specify the access method, actual location that contains the additional information about the CA, and the mechanism for retrieving the information. The location can be specified in any of the following general-name forms: an rfc822name, a directory name, a DNS name, an EDI party name, a uniform resource indicator (URI), an IP address, an object identifier (OID), and any other name.
By default, the policy supports two access methods:
The built-in support for the ocsp access method and a URI value for the access location in the extension conform to the profile defined in RFC 2560 (see http://www.ietf.org/rfc/rfc2560.txt) for CAs that support the OCSP service. For details about OCSP support in Certificate Management System, see "Supported Methods for Verifying Revocation Status of Certificates".
If you configure a Certificate Manager to publish CRLs to an OCSP responder and want to include the authority information access extension referencing to the responder, you should configure an instance of this policy as follows: access method is set to ocsp, name type is set to URI, and name value is set to the URL at which the OCSP responder listens to OCSP requests. This way, OCSP-compliant applications can verify the revocation status of certificates issued by the Certificate Manager by accessing the validation authority using the OCSP method.
Unlike some of the other policy modules, Certificate Management System does not create an instance of the AuthInfoAccessExt module during installation. If you want the server to add this extension to certificates, you must create an instance of the said module and configure it. For instructions, see "Step 4. Add New Policy Rules").
AuthInfoAccessExt Module
The Java class that implements the authority information access extension policy is as follows:
com.netscape.certsrv.policy.AuthInfoAccessExt
Figure 18.2 shows how the configurable parameters for the AuthInfoAccessExt module are displayed in the CMS window.
Figure 18.2 Parameters defined in the AuthInfoAccessExt module
The configuration shown in Figure 18.2 creates a policy rule named AuthInfoAccessExtForClientCert, which enforces a rule that the server should add the authority information access extension to client certificates. The extension indicates that the online validation service (or the OSCSP responder) for the CA that has issued these certificates is at this URL:
http://ocspResponder.siroe.com:8000
The extension is marked noncritical (to comply with the PKIX recommendation).
Table 18.2 gives details about the configurable parameters defined in the AuthInfoAccessExt module.
|
Authority Key Identifier Extension Policy |
The AuthorityKeyIdentifierExt plug-in module implements the authority key identifier extension policy. This policy enables you to configure Certificate Management System to add the Authority Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to identify the public key that corresponds to the private key used by a CA to sign certificates.
You should consider adding this extension to all certificates, especially CA certificates, issued by Certificate Management System. The reason is, in certain situations, a CA's public key may change (for example, when the key gets updated) or the CA may have multiple signing keys (either due to multiple concurrent key pairs or due to key changeover). In these cases, the CA ends up with more than one distinct key. When verifying a signature on a certificate, other applications need to know which key was used in the signature. The extension, if present in a certificate, enables applications (those that can use the extension) to identify the correct key to use in situations when multiple keys exist; the extension specifies the public key to be used to verify the signature on the certificate.
For general guidelines on setting the authority key identifier extension, see "authorityKeyIdentifier" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The authority key identifier extension policy in Certificate Management System allows setting of the authority key identifier extension as defined in its X.509 definition with key identifiers. The policy enables you to specify what is to be done if the CA certificate does not have a subject key identifier extension--whether to use the a SHA-1 hash of the CA's subject public key information (carries the public key and identifies the algorithm with which the key is used) or skip adding the authority key identifier extension itself. For information on setting the subject key identifier extension in certificates, see "Subject Key Identifier Extension Policy".
Note that PKIX and Federal PKI standards recommend against the use of authorityCertIssuer and authorityCertSerialNumber fields of the X.509 definition.
If enabled, the policy does the following:
During installation, Certificate Management System automatically creates an instance of the authority key identifier extension policy. See "AuthorityKeyIdentifierExt Rule".
AuthorityKeyIdentifierExt Module
The Java class that implements the authority key identifier extension policy is as follows:
com.netscape.certsrv.policy.AuthorityKeyIdentifierExt
Figure 18.3 shows how the configurable parameters for the AuthorityKeyIdentifierExt module are displayed in the CMS window.
Figure 18.3 Parameters defined in the AuthorityKeyIdentifierExt module
The configuration shown in Figure 18.3 creates a policy rule named AuthKeyIDExtForCACert, which enforces a rule that the server should set the authority key identifier extension in all CA certificates.
Table 18.3 gives details about each of these parameters.
AuthorityKeyIdentifierExt Rule
The rule named AuthorityKeyIdentifierExt is an instance of the AuthorityKeyIdentifierExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.3. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Basic Constraints Extension Policy |
The BasicConstraintsExt plug-in module implements the basic constraints extension policy. This policy enables you to configure Certificate Management System to add the Basic Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in certificates. The extension identifies whether the Certificate Manager is a CA. In addition, the extension is also used during the certificate chain verification process to identify CA certificates and to apply certificate chain-path length constraints.
You should consider adding this extension to all CA certificates (root as well as subordinate) issued by Certificate Management System. The current PKIX standard requires that this extension be marked critical and that it appear in all CA certificates. The standard also recommends that the extension should not appear in end-entity certificates. For general guidelines on setting the basic constraints extension, see "basicConstraints" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
Because the basic constraints extension is a critical extension and is used by applications to determine the path length during certificate validation to chain up to the trusted CA, it's important that you set this extension correctly.
Also note that when a user submits a certificate request using the manual-enrollment method, the basic constraints extension is set on that request as per the configured policy, and then the request is queued for agent approval. When an agent approves the request, it is subjected to the configured policy again. If there's a change in the configuration of the basic constraints extension, the server may reject the agent-approved request. For the server to approve the request, the user will have to resubmit the request.
During installation, Certificate Management System automatically creates an instance of the basic constraints extension policy. See "BasicConstraintsExt Rule".
BasicConstraintsExt Module
The Java class that implements the basic constraints extension policy is as follows:
com.netscape.certsrv.policy.BasicConstraintsExt
Figure 18.4 shows how the configurable parameters for the BasicConstraintsExt module are displayed in the CMS window.
Figure 18.4 Parameters defined in the BasicConstraintsExt module
The configuration shown in Figure 18.4 creates a policy rule named BasicConsExtForCACert, which enforces a rule that the server should set the basic constraints extension in all CA certificates.
Table 18.4 gives details about each of these parameters.
BasicConstraintsExt Rule
The rule named BasicConstraintsExt is an instance of the BasicConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.4. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Certificate Policies Extension Policy |
The CertificatePoliciesExt plug-in module implements the certificate policies extension policy. This policy enables you to configure Certificate Management System to add the Certificate Policies Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in certificates. The extension contains a sequence of one or more policy statements, each indicating the policy under which the certificate has been issued and identifying the purposes for which the certificate may be used. Presence of this extension in certificates enables an application with specific policy requirements to compare its list of policies to the ones contained in a certificate during its validation; typically, such applications will have a list of policies (which they will accept) and compare the policies in the certificate to their list as a part validating the certificate.
To promote interoperatability, the PKIX standard recommends that the policy statements or information terms should be included in certificates in the form of object identifiers (OIDs). For more information on OIDs, see "Object Identifier". This means, in order for the server to add this extension to any certificate it issues, you need to compose policy statements you want to include in the extension, define OIDs for these policy statements, and configure the server with these OIDs.
When determining whether to add this extension to certificates, keep in mind that if the extension exists in a certificate and if it is marked critical, the application validating the certificate must be able to interpret the extension (including the optional qualifiers, if any), or else it must reject the certificate. For general guidelines on setting the certificate policies extension, see "certificatePolicies" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The certificate policies extension policy in Certificate Management System enables you to set the extension with the following information:
During installation, Certificate Management System automatically creates an instance of the certificate policies extension policy. See "CertificatePoliciesExt Rule".
CertificatePoliciesExt Module
The Java class that implements the certificate policies extension policy is as follows:
com.netscape.certsrv.policy.CertificatePoliciesExt
Figure 18.5 shows how the configurable parameters for the CertificatePoliciesExt module are displayed in the CMS window.
Figure 18.5 Parameters defined in the CertificatePoliciesExt module
The configuration shown in Figure 18.5 creates a policy rule named CertPoliciesExtForClientCert, which enforces a rule that the server should set the certificate policies extension in all client certificates.
Table 18.5 gives details about each of these parameters.
CertificatePoliciesExt Rule
The policy rule named CertificatePoliciesExt is an instance of the CertificatePoliciesExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.5. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules". For example, if you want to include different policy statements in different types of certificates, you should create multiple instances of the policy module and configure each instance with the appropriate policy OID and predicate expression.
|
Certificate Renewal Window Extension Policy |
The CertificateRenewalWindowExt plug-in module implements the certificate renewal window extension policy. This policy enables you to configure Certificate Management System to add the Certificate Renewal Window Extension to certificates. The extension, which must be noncritical, aids in managing the life cycle of a certificate by specifying a process to follow for renewing a certificate and by defining a time window when automatic renewal of the certificate should be attempted.
Every certificate issued by Certificate Management System has a validity period beyond which it cannot be used. In order to continue to participate in the PKI-using system beyond this validity period, the entity owning the certificate must renew the certificate. Renewal of a certificate essentially means getting a new certificate for the existing key pair with a new validity time period (and updated attributes).
Once a certificate is issued, the owner of the certificate may attempt its renewal any time. To prevent certificate owners from renewing their certificates too often and thus reduce the overhead of processing new certificate requests, the CA can use a policy that restricts the time period when certificate renewal may occur. For example, the CA can use a policy that limits the renewal process to the last few weeks or days of validity of the certificate, thus defining a certificate renewal window. In general, the renewal window must be sufficient for the renewal to occur, but at the same time delay the renewal as long as possible to best utilize a certificate's life time.
The certificate-renewal process is often different than the enrollment process an entity uses to obtain the certificate; this is because the entity already owns a key pair that is associated with his or her identity. For example, in Certificate Management System, the certificate-renewal process for end users is different than the enrollment process they used to obtain the certificate. To renew their certificates, end users go to the certificate-renewal interface of Certificate Management System and submit their original certificates; for details, see "Authentication of End Users During Certificate Renewal".
Because the renewal process requires end users to remember when their certificates expire and renew them before the expiry date, some clients provide built-in support for automated renewal. Inclusion of the certificate renewal window extension in certificates is useful in a PKI setup with such clients; such a setup eliminates the need for the owner of the certificate to manually submit a renewal request to the CA and install the renewed certificate. For example, assume you have deployed clients that can automatically submit certificate-renewal requests to Certificate Management System. If you issue certificates with the certificate renewal window extension to these clients, they can then read this extension for the renewal window and automatically get the certificate renewed from the CA during that window.
For a PKI setup without clients that can handle automated certificate renewals, Certificate Management System enables administrators to easily manage certificate renewals using the following features:
Unlike some of the other policy modules, Certificate Management System does not create an instance of the certificate renewal window extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the CertificateScopeOfUseExt module and configure it (see "Step 4. Add New Policy Rules").
CertificateRenewalWindowExt Module
The Java class that implements the certificate renewal window extension policy is as follows:
com.netscape.certsrv.policy.CertificateRenewalWindowExt
Figure 18.6 shows how the configurable parameters for the CertificateRenewalWindowExt module are displayed in the CMS window.
Figure 18.6 Parameters defined in the CertificateRenewalWindowExt module
The configuration shown in Figure 18.6 creates a policy rule named CertRenewWindowExtForClientCert, which enforces a rule that the server should set the certificate renewal window extension in client certificates only; the renewal window starts 30 days before a certificate expires and ends with certificate expiration.
Table 18.6 gives details about each of these parameters.
|
Certificate Scope of Use Extension Policy |
The CertificateScopeOfUseExt plug-in module implements the certificate scope of use extension policy. This policy enables you to configure Certificate Management System to add the Certificate Scope of Use Extension to certificates. The extension enables you to specify a list of web sites that may request the use of a particular certificate for SSL client authentication, thus aiding certificate-using applications to select certificates to present to web sites and to control release of these certificates.
The SSL protocol provides a way for a client application to authenticate itself to a web site or server. SSL client authentication occurs upon request of the server, and proceeds by providing a certificate and a signature to the server. The client may have more than one certificate that could be used to perform this authentication. The SSL protocol provides a way for the server to indicate which certificate may be useful by listing issuing CAs in one of the SSL protocol messages.
By using a particular certificate for SSL client authentication, the client releases information about itself to the server. This information may include the name and key information contained in the certificate. It also releases the information that the client holds a certificate from a particular CA. This information may be of interest to the company running the server, for example to find users that have certificates from competing companies.
The certificate scope of use extension can be included in certificates to restrict the scope-of-use of the certificate for client authentication; the extension enables the certificate-using application to restrict the release of individual certificates to web sites requesting SSL client authentication.
The certificate scope of use extension policy in Certificate Management System enables you to include a list of name patterns that will match server DNS names where the certificate may be used. It's up to the certificate-using applications to use the values in this extension to filter the list of potential certificates to use for client authentication.
Unlike some of the other policy modules, Certificate Management System does not create an instance of the certificate scope of use extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the CertificateScopeOfUseExt module and configure it (see "Step 4. Add New Policy Rules").
CertificateScopeOfUseExt Module
The Java class that implements the certificate scope of use extension policy is as follows:
com.netscape.certsrv.policy.CertificateScopeOfUseExt
Figure 18.7 shows how the configurable parameters for the CertificateScopeOfUseExt module are displayed in the CMS window.
Figure 18.7 Parameters defined in the CertificateScopeOfUseExt module
The configuration shown in Figure 18.7 creates a policy rule named CertScopeOfUseExtForClientCert, which enforces a rule that the server should set the certificate scope of use extension in client certificates only.
Table 18.7 gives details about each of these parameters.
|
CRL Distribution Points Extension Policy |
The CRLDistributionPointsExt plug-in module implements the CRL distribution points extension policy. This policy enables you to configure Certificate Management System to add the CRL Distribution Points Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. This extension, when present in a certificate, identifies one or more locations from where the application that is validating the certificate can obtain the CRL information (to verify the revocation status of the certificate).
For general guidelines on setting the CRL distribution points extension in certificates, see "cRLDistributionPoints" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The CRL distribution points extension policy in Certificate Management System enables you to specify pointers to one or more CRL locations. The pointers can be in these forms: the name of the X.500 directory that stores the CRL, the URI to the location that contains the CRL, or both.
Note that in the current implementation, the policy supports only two name forms for distribution points, X.500 Directory Name and URI; URIs described in this document support two CRL retrieval mechanisms, LDAP-based and HTTP-based. Optionally, each distribution point may contain a set of reason flags, indicating what revocation reasons are covered by the CRL at that location. Also, the distribution point location can be relative to the location of the issuer. In this last case, the issuerName and issuerType parameters should be included to give the location of the issuer.
You can modify the policy to support any name form by making appropriate changes to the sample code provided for this purpose. The sample code is located here:
<server_root>/cms_sdk/samples/policy/CRLDistributionPoints
During installation, Certificate Management System automatically creates an instance of the CRL distribution points extension policy. See "CRLDistributionPointsExt Rule".
CRLDistributionPointsExt Module
The Java class that implements the CRL distribution points extension policy is as follows:
com.netscape.certsrv.policy.CRLDistributionPointsExt
Figure 18.8 shows how the configurable parameters for the CRLDistributionPointsExt module are displayed in the CMS window.
Figure 18.8 Description of parameters defined in the CRLDistributionPointsExt module
The configuration shown in Figure 18.8 creates a policy rule named CRLDistPtsExtForRouterCert, which enforces a rule that the server should set the CRL distribution point extension in router certificates; the CRL location is a X.500 directory.
Table 18.8 gives details about each of these parameters.
CRLDistributionPointsExt Rule
The policy rule named CRLDistributionPointsExt is an instance of the CRLDistributionPointsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.8. It is important that you review this rule and make the appropriate changes required by your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules". For example, if you want to include different CRL distribution points in different types of certificates, you should create multiple instances of the policy module and configure each instance with the appropriate CRL distribution point and predicate expression.
|
Extended Key Usage Extension Policy |
The ExtendedKeyUsageExt plug-in module implements the extended key usage extension policy. This policy enables you to configure Certificate Management System to add the Extended Key Usage Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension identifies one or more purposes--in addition to or in place of the basic purposes indicated in the key usage extension--for which the certified public key may be used. For example, if the key usage extension identifies a key to be used for signing, the extended key usage extension can further narrow down the usage of the key for signing OCSP responses only or for signing Java applets only. (For information on key usage extension, see "Key Usage Extension Policy".)
The PKIX standard suggests that organizations can define their own extended key usage purposes, if there's a need. Each key purpose must be identified by an OID, which in turn must be defined in accordance with IANA or ITU-T Rec. X.660 | ISO/IEC/ITU 9834-1. The standard also recommends that the extension may be marked either critical or noncritical--mark the extension critical if you want to restrict the usage of the certificate only for one of the key-usage purposes indicated by the extension; mark the extension noncritical, when you want it to indicate the intended purposes of the key, and not restrict the use of the certificate to the indicated purposes (in this case, validating applications are expected to treat the extension as an advisory field and may use it to identify the key, not its usage purpose).
Table 18.9 lists the usages defined by PKIX for use with the extended key usage extension.
For general guidelines on setting the extended key usage extension in certificates, see "extKeyUsage" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The extended key usage extension policy in Certificate Management System allows setting of the key usage extension as defined in its X.509 definition. The policy enables you to specify OIDs, that identify key usages, in the extension.
During installation, Certificate Management System automatically creates two instances of the extended key usage extension policy. See "CODESigningExt Rule" and "OCSPSigningExt Rule".
ExtendedKeyUsageExt Module
The Java class that implements the extended key usage extension policy is as follows:
com.netscape.certsrv.policy.ExtendedKeyUsageExt
Figure 18.9 shows how the configurable parameters for the ExtendedKeyUsageExt module are displayed in the CMS window.
Figure 18.9 Parameters defined in the ExtendedKeyUsageExt module
The configuration shown in Figure 18.9 creates a policy rule named CodeSigningExt, which enforces a rule that the extended key usage extension should be set in object-signing certificates.
Table 18.10 gives details about each of these parameters.
CODESigningExt Rule
The rule named CODESigningExt is an instance of the ExtendedKeyUsageExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
Note that this policy rule must remain enabled if you want Certificate Management System to issue object signing certificates with the correct extended key usage extension.
For details on individual parameters defined in the rule, see Table 18.10. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
OCSPSigningExt Rule
The rule named OCSPSigningExt is an instance of the ExtendedKeyUsageExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
Note that this policy rule must remain enabled if your PKI setup includes a CA-delegated OCSP responder and you want to issue an OCSP responder certificate to that server; the rule adds the extended key usage extension to an OCSP responder certificate indicating that the associated key can be used for signing OCSP responses.
Here's some background information that will help you understand why you should set this extension in OCSP responder certificates:
The online certificate status protocol (OCSP) enables OCSP-compliant applications to determine the revocation status of a certificate being validated. Certificate Management System supports the OCSP service--you can configure a Certificate Manager to publish CRLs to an online validation authority (also called OCSP responder); for details, see "Publishing of CRLs to an Online Validation Authority". If you configure Certificate Management System to work with an OCSP responder, OCSP-compliant applications in your PKI setup will be able to do real-time verification of certificates by querying the OCSP responder for their revocation status. Note that these applications will be able to query the OCSP responder only if the certificate being validated includes the authority information access extension indicating the location of the OCSP responder; for information on adding this extension to certificates, see "Authority Information Access Extension Policy".
When queried by an application on the status of a certificate, the OCSP responder sends a digitally signed response. To generate the signature, the responder needs to use a key. Because the signature needs to be verified by the application that sought the response, RFC 2560 recommends that the key used for signing an OCSP response must belong to one of the following:
If you want to deploy a CA-delegated OCSP responder, the OCSPSigningExt rule enables you to add the extended key usage extension (with OCSPSigning value) to the OCSP responder certificate. In addition to this extension, the responder's signing certificate should also include the OCSP no check extension. For details, see "OCSP No Check Extension Policy".
|
Generic ASN.1 Extension Policy |
The GenericASN1Ext plug-in module implements the generic ASN.1 extension policy. This policy enables you to configure Certificate Management System to add custom extensions to certificates. Using this policy, you can add as many ASN.1 type based-extensions as required without having to write any code. Further, it eliminates the dependency on the command-line tools for generating base-64 encoded standard extensions from the x.509 extension classes.
The generic extension policy in Certificate Management System accepts custom extensions in the form of object identifiers (OIDs) and values as DER-encoded extension values. That is, for the server to add a custom extension to certificates it issues, you need to first define the extension and then configure the server with extension details.
Similar to a standard extension, you define a custom extension by defining an OID and a ASN.1 structure.
The resulting extension would look similar to the way a standard extension appears in certificates (as defined in RFC 2459):
Extension ::= SEQUENCE { extnID OBJECT IDENTIFIER, critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }
In the policy configuration, the extnID field is defined by the oid parameter, the critical field is defined by the critical parameter, and the extnValue field is defined by evaluating the expression in the pattern parameter, which in turn is defined by the attribute parameters. See Table 18.11 for details on individual parameters.
Typically, the application receiving the certificate checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used. When adding your custom extension to certificates, keep in mind that if the extension exists in a certificate and if it is marked critical, the application validating the certificate must be able to interpret the extension, or else it must reject the certificate. Since it's unlikely that all applications will be able to interpret your custom extensions, you should consider marking these extensions noncritical.
Note that each instance of the policy can be configured to add one custom extension only. To configure the server to add multiple custom extensions, create multiple instances of the module, each with a distinct name and appropriate configuration values. Also note that the policy allows you to encode simple (possibly nested) SEQUENCEs. There is no support for CHOICE, SET, or ASN.1 tagging.
During installation, Certificate Management System automatically creates an instance of the generic ASN.1 extension policy. See "GenericASN1Ext Rule".
GenericASN1Ext Module
The Java class that implements the generic extension policy is as follows:
com.netscape.certsrv.policy.GenericASN1Ext
Figure 18.10 shows how the configurable parameters for the GenericASN1Ext module are displayed in the CMS window.
Figure 18.10 Parameters defined in the GenericASN1Ext module
The configuration shown in Figure 18.10 defines a custom extension named testGenASN1Ext with OID 2.4.5.99. The extension is non-critical, and it will be added to all certificates issued by the server. The expected dumpasn1 output (see "dumpasn1 Tool") of the resulting extension, would look like this:
337 30 148: . . . . SEQUENCE {
340 06 3: . . . . . OBJECT IDENTIFIER '2 4 5 99'
345 04 140: . . . . . OCTET STRING, encapsulates {
348 30 137: . . . . . . . SEQUENCE {
351 13 24: . . . . . . . . PrintableString '1st data in 1st sequence'
377 16 24: . . . . . . . . IA5String '2nd data in 1st sequence'
403 13 32: . . . . . . . . PrintableString 'This is 3rd data in 1st
sequence'
437 04 10: . . . . . . . . OCTET STRING
: . . . . . . . . . 11 22 33 44 A0 B0 C0 D0 E0 F0
449 30 37: . . . . . . . . SEQUENCE {
451 17 13: . . . . . . . . . UTCTime '000406070000Z'
466 30 8: . . . . . . . . . SEQUENCE {
468 01 1: . . . . . . . . . . BOOLEAN TRUE
471 06 3: . . . . . . . . . . OBJECT IDENTIFIER '2 4 5 100'
: . . . . . . . . . . }
476 04 10: . . . . . . . . . OCTET STRING
: . . . . . . . . . 11 22 33 44 A0 B0 C0 D0 E0 F0
: . . . . . . . . . }
: . . . . . . . . }
: . . . . . . . }
: . . . . . }
Table 18.11 describes the configurable parameters of the generic ASN.1 extension policy module.
GenericASN1Ext Rule
The rule named GenericASN1Ext is an instance of the GenericASN1Ext module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.11. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Issuer Alternative Name Extension Policy |
The IssuerAltNameExt plug-in module implements the issuer alternative name extension policy. This policy enables you to configure Certificate Management System to add the Issuer Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. This extension enables binding of or associating Internet style identities--such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI)-- with the certificate issuer.
For general guidelines on setting the issuer alternative name extension, see "issuerAltName" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The issuer alternative name extension policy in Certificate Management System allows setting of the issuer alternative name extension as defined in its X.509 definition. The policy enables you to associate the following alternative identities to a CA, by including them in the extension:
Unlike some of the other policy modules, Certificate Management System does not create an instance of the issuer alternative name extension policy during installation. If you want the server to add this extension to certificates, you must create an instance of the IssuerAltNameExt module and configure it (see "Step 4. Add New Policy Rules").
IssuerAltNameExt Module
The Java class that implements the issuer alternative name extension policy is as follows:
com.netscape.certsrv.policy.IssuerAltNameExt
Figure 18.11 shows how the configurable parameters for the IssuerAltNameExt module are displayed in the CMS window.
Figure 18.11 Parameters defined in the IssuerAltNameExt module
The configuration shown in Figure 18.11 creates a policy rule named IssuerAltNameExtForCACert, which enforces a rule that the server should set the issuer alternative name extension in CA certificates only.
Table 18.12 gives details about each of these parameters.
|
Key Usage Extension Policy |
The KeyUsageExt plug-in module implements the key usage extension policy. This policy enables you to configure Certificate Management System to add the Key Usage Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension specifies the purposes for which the key contained in a certificate should be used--for example, it specifies whether the key should be used for data signing, key encipherment, or data encipherment--and thus enables you to restrict the usage of a key pair to predetermined purposes.
The key usage extension is a string of boolean bit-flags, each bit identifying the purpose for which a key is to be used. Table 18.13 lists the bits and their designated purposes.
You can restrict the purposes for which a key pair (and thus the corresponding certificate) should be used by setting the appropriate key-usage bits. For example, if you want to restrict a key pair to be used for digital signature only, when issuing the certificate you would add the key usage extension to the certificate with digital_signature bit (or bit 0) set. For general guidelines on setting the key usage extension in certificates, see "keyUsage" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
Note that you can specify which bits in the extension are to be set on both server and client sides:
Note
For all certificates, the key-usage-bits set on the server side (which is governed
by the policy) override the ones set on the client side.
During installation, Certificate Management System automatically creates multiple instances of the key usage extension policy suitable for various types of certificates that you may want the server to issue. The default instances are named as follows:
It is important that you review each policy instance and make the appropriate changes required by your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
Additionally, as you'll notice in Figure 18.13 through Figure 18.17, the default enrollment forms provided for requesting various types of certificates (see "Forms for Certificate Enrollment") include the appropriate HTTP input variables that correspond to the key-usage bits. By default only variables that correspond to key-usage bits that need to be set are included in the form.
Typically, you won't have to change the key-usage bit setting by editing the enrollment forms as you can do this easily by making the appropriate changes to the policy instance (bits set on the server side override the ones set on the client side). However, if you want to add new variables on the client side, you can do that too. Be sure to add the new variable in the following format:
<input type="HIDDEN" name="variable_name" value=true>
where, variable_name can be any of the HTTP input variables listed in Table 18.14.
The value of an HTTP input variable corresponding to a key-usage bit must be either true or false; any other value is considered equivalent to false. For example, a value tree would be interpreted as false by the server. Note that values true and false are case insensitive.
KeyUsageExt Module
The Java class that implements the key usage extension policy is as follows:
com.netscape.certsrv.policy.KeyUsageExt
Figure 18.12 shows how the configurable parameters for the KeyUsageExt module are displayed in the CMS window.
Figure 18.12 Parameters defined in the KeyUsageExt module
The configuration shown in Figure 18.12 creates a policy rule named KeyUsageExtForClientCert, which enforces a rule that the server should set the key usage extension (digitalSignature, nonRepudiation, and keyEncipherment bits) in client certificates.
Table 18.15 gives details about each of these parameters.
CMCertKeyUsageExt Rule
The policy rule named CMCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in Certificate Manager CA signing certificates; see "Certificate Manager's Key Pairs and Certificates". By default, the rule is configured as follows:
RMCertKeyUsageExt Rule
The policy rule named RMCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in Registration Managers' signing certificates; see "Registration Manager's Key Pairs and Certificates". By default, the rule is configured as follows:
ServerCertKeyUsageExt Rule
The policy rule named ServerCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in SSL server certificates. By default, the rule is configured as follows:
ClientCertKeyUsageExt Rule
The policy rule named ClientCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in SSL client certificates. By default, the rule is configured as follows:
Notice that the key-usage bits specified in the default policy rule match the bits specified in the enrollment form for requesting SSL client certificates. Figure 18.16 shows the default directory-based enrollment form for end users with the information related to the key usage extension variables highlighted--it shows three of the total number of variables listed in Table 18.14. Note that by default three key-usage bits--digitalSignature, nonRepudiation, and keyEncipherment--are enabled and the remaining bits are disabled.
Additionally, also notice the HTTP variables for the Netscape certificate type extension: the values indicate that the certificate is meant for S/MIME and SSL client authentication use only. (For details on Netscape certificate type extension, see "Netscape Certificate Type Extension Policy".)
Figure 18.16 Key usage extension bits in the directory-based enrollment form
Keep in mind that for requesting client certificates, there are many enrollment forms. You may be using a combination of them:
For details about these forms, see "Enrollment Forms".
Each of these forms embed HTTP input variables (for key-usage bits) that are considered appropriate for the certificate being requested using that form. If you want, you may create additional instances of the key usage extension policy, one each for each client certificate enrollment form and configure these instances as appropriate. Be sure to use the correct predicate expression to distinguish the certificates to thus avoid setting incorrect bits.
ObjSignCertKeyUsageExt Rule
The policy rule named ObjSignCertKeyUsageExt is an instance of the KeyUsageExt module. This rule is for setting the appropriate key-usage bits in object signing certificates. By default, the rule is configured as follows:
|
Name Constraints Extension Policy |
The NameConstraintsExt plug-in module implements the name constraints extension policy. This policy enables you to configure Certificate Management System to add the Name Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used in CA certificates to indicate a name space within which subject names or subject alternative names in subsequent certificates in a certification path or chain should be located.
Various standards describe how the name constraints extension should be processed during certificate verification. It's beyond the scope of this document to explain this. For general guidelines on setting the name constraints extension in certificates, see "nameConstraints" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The policy implemented in Certificate Management System allows setting of the name constraints extension in any form as defined in its X.509 definition; the policy enables you to specify the number of subtrees permitted and excluded in the extension. It is up to applications to process the extension as described in the standards.
During installation, Certificate Management System automatically creates an instance of the name constraints extension policy. See "NameConstraintsExt Rule".
NameConstraintsExt Module
The Java class that implements the name constraints extension policy is as follows:
com.netscape.certsrv.policy.NameConstraintsExt
Figure 18.18 shows how the configurable parameters for the NameConstraintsExt module are displayed in the CMS window.
Figure 18.18 Parameters defined in the NameConstraintsExt module
The configuration shown in Figure 18.18 creates a policy rule named NameConsExtForCACert, which enforces a rule that the server should set the name constraints extension as a critical extension in CA certificates.
Table 18.16 gives details about each of these parameters.
NameConstraintsExt Rule
The policy rule named NameConstraintsExt is an instance of the NameConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.16. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Netscape Certificate Comment Extension Policy |
The NSCCommentExt plug-in module implements the Netscape certificate comment extension policy. This policy enables you to configure Certificate Management System to add the Netscape Certificate Comment Extension (see http://www.netscape.com/eng/security/cert-exts.html) to certificates. The extension can be used to include textual comments in certificates. Applications that are capable of interpreting the comment may display it to a relying party when the certificate is used or viewed.
For general guidelines on setting the Netscape certificate comment extension, see "netscape-comment" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The Netscape certificate comment extension policy in Certificate Management System allows you to specify a textual statement or a comment to be included in certificates. You may choose to directly embed the text in the certificate itself or point to the file that contains the statement.
During installation, Certificate Management System automatically creates an instance of the Netscape certificate comment extension policy. See "NSCCommentExt Rule".
NSCCommentExt Module
The Java class that implements the Netscape certificate comment extension policy is as follows:
com.netscape.certsrv.policy.NSCCommentExt
Figure 18.19 shows how the configurable parameters for the NSCCommentExt module are displayed in the CMS window.
Figure 18.19 Parameters defined in the NSCCommentExt module
The configuration shown in Figure 18.19 creates a policy rule named NetscapeCommentExtForClientCert, which enforces a rule that the server should set the Netscape certificate comment extension in client certificates.
Table 18.17 provides details for each of these parameters.
NSCCommentExt Rule
The policy rule named NSCCommentExt is an instance of the NSCCommentExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.17. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Netscape Certificate Type Extension Policy |
The NSCertTypeExt plug-in module implements the Netscape certificate type extension policy. This policy enables you to configure Certificate Management System to add the Netscape Certificate Type extension to certificates. The extension identifies the certificate type--for example, it identifies whether the certificate is a CA certificate, server SSL certificate, client SSL certificate, object signing certificate, or S/MIME certificate--and thus enables you to restrict the usage of a certificate to predetermined purposes.
The Netscape certificate type extension is a string of boolean bit-flags, each bit identifying the purpose for which a certificate to be used. Table 18.18 lists the bits and their designated purposes. The extension has no default value.
The Netscape certificate type extension policy has been implemented in such a way that it enables you to set the appropriate certificate-type bits for certificates being issued by Certificate Management System. This way, you can restrict the purposes for which a certificate should be used by adding the extension, with the appropriate bits set, to the certificate at the time of issuance. For example, if you want to restrict a certificate to be used for SSL client authentication only, when issuing the certificate you would add the Netscape certificate type extension to the certificate with ssl_client (bit 0) set. For general guidelines on setting the Netscape certificate type extension, see "netscape-cert-type" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
In the current implementation, you can specify whether to add the extension to certificates on the server side and which bits in the extension are to be set on the client side--you specify whether to add the extension by enabling the Netscape certificate type extension policy and which bits are to be set by adding the appropriate HTTP variables to the enrollment forms.
Bits set in the Netscape certificate type extension are formed from pre-defined input variables that you can embed as hidden values in the default enrollment forms (see "Forms for Certificate Enrollment"). Table 18.19 lists the HTTP input variables that correspond to Netscape certificate type extension bits.
During installation, Certificate Management System automatically creates an instance of the Netscape certificate type extension policy for the various types of certificates that you may want the server to issue. See "NSCertTypeExt Rule".
Additionally, the default enrollment forms--the directory-based, directory- and PIN-based, manual, Kerberos server-based, and NIS server-based enrollment forms--for various types of certificates also include the appropriate HTTP input variables corresponding to Netscape certificate type extension bits. For details about these forms, see "Forms for Certificate Enrollment".
Figure 18.20 shows the default directory-based enrollment form for end users with HTTP input variables specific to Netscape certificate type extension highlighted; it shows two of the total number of variables listed in Table 18.19, ssl_client and email, indicating that these bits be set in certificates requested using this form.
Figure 18.20 Netscape certificate type extension-specific variables in enrollment forms
Note that the default enrollment forms embed variables that are considered appropriate for the type of certificate, such as client, server, or CA, that can be requested using the form. For example, the server enrollment form embeds the ssl_server variable, whereas the subordinate CA (Certificate Manager) enrollment form embeds the ssl_client, email_ca, ssl_ca and object_signing_ca variables.
In general, the forms are set up so that you don't have to make any modifications. However, if there is a need to modify the bit settings, be sure to add or remove the corresponding variable. Also, when adding a new variable, make sure that the HTML input format is as follows:
<input type="HIDDEN" value="true" name="variable_name">
where variable_name can be any of the variables listed in Table 18.19.
NSCertTypeExt Module
The Java class that implements the Netscape certificate type extension policy is as follows:
com.netscape.certsrv.policy.NSCertTypeExt
Figure 18.21 shows how the configurable parameters for the NSCertTypeExt module are displayed in the CMS window.
Figure 18.21 Parameters defined in the NSCertTypeExt module
The configuration shown in Figure 18.21 creates a policy rule named NetscapeCertTypeExtForClientCert, which enforces a rule that the server should set the Netscape certificate type extension in client certificates.
Table 18.20 gives details about each of these parameters.
NSCertTypeExt Rule
The policy rule named NSCertTypeExt is an instance of the NSCertTypeExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.20. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
OCSP No Check Extension Policy |
The OCSPNoCheckExt plug-in module implements the OCSP no check extension policy. This policy enables you to configure Certificate Management System to add the OCSP No Check Extension defined in X.509 and PKIX standard RFC 2560 (see http://www.ietf.org/rfc/rfc2560.txt) to certificates. The extension, which should be used in OCSP responder certificates only, indicates how OCSP-compliant applications can verify the revocation status of the certificate an authorized OCSP responder uses to sign OCSP responses.
The online certificate status protocol (OCSP) enables OCSP-compliant applications to determine the revocation status of a certificate being validated. Certificate Management System supports the OCSP service--you can configure a Certificate Manager to publish CRLs to an online validation authority (also called OCSP responder); see "Supported Methods for Verifying Revocation Status of Certificates". If you configure Certificate Management System to work with an OCSP responder, OCSP-compliant applications in your PKI setup will be able to do real-time verification of certificates by querying the OCSP responder for their revocation status. Note that these applications will be able to query the OCSP responder only if the certificate being validated includes the authority information access extension indicating the location of the OCSP responder; for information on adding this extension to certificates, see "Authority Information Access Extension Policy".
When queried by an application on the status of a certificate, the OCSP responder sends a digitally signed response. For the signature, the responder uses the key pair designated for signing OCSP responses. Usually, the CA issues an OCSP responder certificate to the responder, which enables applications to identify it as a CA-designated responder. The CA issues this certificate with an extended key usage extension with a unique value, which indicates that the key associated with the certificate can be used for signing OCSP responses. For details on this extension, see "OCSPSigningExt Rule".
When an OCSP-compliant application receives a signed response, as a part of validating the signature, the application needs to verify that the responder's certificate has not been revoked. RFC 2560 recommends three ways in which a CA may indicate the revocation status of an OCSP responder certificate. One of them is that the CA issue the OCSP responder a certificate with the OCSP no check extension, which indicates that the certificate can be trusted by the clients for its lifetime. The OCSP no check policy of Certificate Management System implements this method and enables you to set the OCSP no check extension in OCSP responder certificates.
Because OCSP-compliant applications don't check for the revocation status of the OCSP responder certificate (containing the OCSP no check extension), when issuing these types of certificates, you should consider issuing them with a short validity period (and renew them frequently). Note that the OCSP no check extension policy only adds the extension to a certificate; it doesn't control the validity period of the certificate. If you want to limit the validity period of these certificates to a short period, you should consider creating an instance of the ValidityConstraints module with the appropriate configuration, for example, set the predicate parameter to HTTP_PARAMS.certType=ocspResponder. For details, see "Validity Constraints Policy". If you have agent privileges, you can also specify the required validity period when approving the OCSP responder certificate request in the request queue; the enrollment process for an OCSP responder certificate is manual, and the request gets queued for agent approval.
Before configuring the server to add the OCSP no check extension to OCSP responder certificates, read the general guidelines provided in "OCSPNocheck" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
During installation, Certificate Management System automatically creates an instance of the OCSP no check extension policy. See "OCSPNoCheckExt Rule".
OCSPNoCheck Module
The Java class that implements the OCSP no check extension policy is as follows:
com.netscape.certsrv.policy.OCSPNoCheckExt
Figure 18.22 shows how the configurable parameters for the OCSPNoCheckExt module are displayed in the CMS window.
Figure 18.22 Parameters defined in the OCSPNoCheckExt module
The configuration shown in Figure 18.22 creates a policy rule named OCSPNoCheckExtForResponderCert, which enforces a rule that the server should set the OCSP no check extension in OCSP responder certificates only.
Table 18.21 provides details for each of these parameters.
OCSPNoCheckExt Rule
The policy rule named OCSPNoCheckExt is an instance of the OCSPNoCheckExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.21. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Policy Constraints Extension Policy |
The PolicyConstraintsExt plug-in module implements the policy constraints extension policy. This policy enables you to configure Certificate Management System to add the Policy Constraints Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension, which can be used in CA certificates only, constrains path validation in two ways--either to prohibit policy mapping or to require that each certificate in a path contain an acceptable policy identifier.
The policy constraints extension policy in Certificate Management System allows setting of the policy constraints extension as defined in its X.509 definition. The policy allows you to specify both, requireExplicitPolicy and inhibitPolicyMapping fields. PKIX standard requires that, if present in a CA certificate, the extension must never consist of a null sequence. At least one of the two specified fields must be present. Before configuring the server to add the policy constraints extension to certificates, read the general guidelines provided in "policyConstraints" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
During installation, Certificate Management System automatically creates an instance of the policy constraints extension policy. See "PolicyConstraintsExt Rule".
PolicyConstraintsExt Module
The Java class that implements the policy constraints extension policy is as follows:
com.netscape.certsrv.policy.PolicyConstraintsExt
Figure 18.23 shows how the configurable parameters for the PolicyConstraintsExt module are displayed in the CMS window.
Figure 18.23 Parameters defined in the PolicyConstraintsExt module
The configuration shown in Figure 18.23 creates a policy rule named PolicyConsExtForCACert, which enforces a rule that the server should set the policy constraints extension in CA certificates only.
Table 18.22 gives details about each of these parameters.
PolicyConstraintsExt Rule
The policy rule named PolicyConstraintsExt is an instance of the PolicyConstraintsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.22. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Policy Mappings Extension Policy |
The PolicyMappingsExt plug-in module implements the policy mappings extension policy. This policy enables you to configure Certificate Management System to add the Policy Mappings Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension lists one or more pairs of OIDs, each pair identifying two policy statements of two CAs. The pairing indicates that the corresponding policies of one CA are equivalent to policies of another CA. The extension may be useful in the context of cross-certification.
The PKIX standard suggests that the extension must be marked noncritical and may be supported by CAs and/or applications. If supported, the extension is to be included in CA certificates only. Before configuring the server to add the policy mappings extension to certificates, read the general guidelines provided in "policyMappings" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The policy mappings extension policy in Certificate Management System allows setting of the policy mappings extension as defined in its X.509 definition. The policy allows you to map policy statements of one CA to that of another by pairing the OIDs assigned to their policy statements. (For information on OIDs, see "Object Identifier". For information on certificate policies, see "Certificate Policies Extension Policy".)
Each pair is defined by two parameters, issuerDomainPolicy and subjectDomainPolicy. The pairing indicates that the issuing CA considers the issuerDomainPolicy equivalent to the subjectDomainPolicy of the subject CA. The issuing CA's users may accept an issuerDomainPolicy for certain applications. The policy mapping tells these users which policies associated with the subject CA are equivalent to the policy they accept.
During installation, Certificate Management System automatically creates an instance of the policy mappings extension policy. See "PolicyMappingsExt Rule".
PolicyMappingsExt Module
The Java class that implements the policy mappings extension policy is as follows:
com.netscape.certsrv.policy.PolicyMappingsExt
Figure 18.24 shows how the configurable parameters for the PolicyMappingsExt module are displayed in the CMS window.
Figure 18.24 Parameters defined in the PolicyMappingsExt module
The configuration shown in Figure 18.24 creates a policy rule named PolicyMapExtForCACert, which enforces a rule that the server should set the policy mappings extension in CA certificates only.
Table 18.23 provides details for each of these parameters.
PolicyMappingsExt Rule
The rule named PolicyMappingsExt is an instance of the PolicyMappingsExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.23. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
|
Private Key Usage Period Extension Policy |
The PrivateKeyUsagePeriodExt plug-in module implements the private key usage period extension policy. This policy enables you to configure Certificate Management System to add the Private Key Usage Period Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension allows the certificate issuer to specify a different validity period for the private key than the one specified for the corresponding certificate. The extension is intended for use with digital signature keys.
The PKIX standard recommends against the use of this extension. The standard also recommends that CAs conforming to the standard must not generate certificates with private key usage period extensions that are marked critical. For general guidelines on setting this extension in certificates, see "privateKeyUsagePeriod" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The private key usage period extension policy in Certificate Management System allows setting of the private key usage period extension as defined in its X.509 definition. The policy enables you to specify values for the notBefore and notAfter components. When included in a certificate, the notBefore and notAfter components define the time before and after which the private key associated with the certificate should not be used to sign objects.
PrivateKeyUsagePeriodExt Module
The Java class that implements the private key usage period extension policy is as follows:
com.netscape.certsrv.policy.PrivateKeyUsagePeriodExt
Figure 18.25 shows how the configurable parameters for the PrivateKeyUsagePeriodExt module are displayed in the CMS window.
Figure 18.25 Parameters defined in the PrivateKeyUsagePeriodExt module
The configuration shown in Figure 18.25 creates a policy rule named PrivKeyUsagePrdExtForClientCert, which enforces a rule that the server should set the private key usage period extension in client certificates.
Table 18.24 provides details for each of these parameters.
|
Subject Alternative Name Extension Policy |
The SubjectAltNameExt plug-in module implements the subject alternative name policy. This policy enables you to configure Certificate Management System to add the Subject Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension enables you to bind additional identities--such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI)--to the subject of the certificate.
The standard suggests that if the certificate subject field contains an empty sequence, then the subject alternative name extension must contain the subject's alternative name and that the extension be marked critical. For general guidelines on setting the subject alternate name extension in certificates, see "subjectAltName" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The subject alternative name extension policy in Certificate Management System enables you to include values of certificate-request attributes in the extension. You can include any number of attributes as long as the attribute values conform to any of the supported general-name forms: rfc822Name, X.500 directory name, DNS name, EDI party name, URL, IP address, object identifier, and Other name.
Attributes in a certificate request 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 can also set additional attributes related to the certificate content on the request; for example, in automated-enrollment methods, some attributes may be read from the authentication directory and set in the request as authenticated attributes.
If you're using any of the directory-based authentication methods, you can configure Certificate Management System to retrieve values for any string and byte attributes from the directory and set them in the certificate request during authentication--you specify these attributes by entering them in the ldapStringAttributes and ldapByteAttributes fields defined in the automated enrollment modules. For more information, see Table 10.2, Table 10.3, and Table 10.4.
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.
In general, you can configure which attributes should or shouldn't be stored in the request; for example, you can exclude sensitive attributes such as passwords from getting stored in the request with the help of the parameter named dontSaveHttpParams defined in the CMS configuration file. For details on using this parameter, see the description for HTTP_PARAMS in Table 24.9. You can also distinguish the attributes based on their origin--that is, whether they originated from the enrollment form or where added to the request during the authentication process. Authenticated attributes have AUTH_TOKEN as prefix (for example, AUTH_TOKEN.mail) and non-authenticated attributes such as the ones that come from the HTTP input have HTTP_PARAMS as prefix (for example, HTTP_PARAMS.csrRequestorEmail).
If enabled, the subject alternative extension policy checks the certificate request for configured attributes. If the request contains an attribute, the policy reads its value and sets it in the extension. This way, the extension that gets to added to certificates contains all the configured attributes.
During installation, Certificate Management System automatically creates an instance of the subject alternative name extension policy. See "SubjectAltNameExt Rule".
SubjectAltNameExt Module
The Java class that implements the subject alternate name extension policy is as follows:
com.netscape.certsrv.policy.SubjectAltNameExt
Figure 18.26 shows how the configurable parameters for the SubjectAltNameExt module are displayed in the CMS window.
Figure 18.26 Parameters defined in the SubjectAltNameExt module
The configuration shown in Figure 18.26 creates a policy rule named SubAltNameExtForClientCert, which enforces a rule that the alternative name of the certificate's subject must be derived from the mail attribute of subject's entry in the authentication directory and that the server should set the subject alternative name extension only in client certificates.
Table 18.25 provides details for each of these parameters.
SubjectAltNameExt Rule
The policy rule named SubjectAltNameExt is an instance of the SubjectAltNameExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.25. You need to review this rule and make the changes appropriate for your PKI setup. For instructions, see "Step 2. Modify Existing Policy Rules". For instructions on adding additional instances, see "Step 4. Add New Policy Rules".
Before you edit the default rule, you should read the additional details about the attributes that are set in the default policy rule.
The first two attributes, AUTH_TOKEN.mail and AUTH_TOKEN.mailalternateaddress, are standard LDAP attributes typically used for storing end users' email addresses in an LDAP directory. These attributes enable you to include a user's email address as an alternative name in the certificate. Remember that you need to specify the LDAP attribute for users' email addresses as a part of configuring the server to use a specific directory for authentication--which means for the default rule to set end users' email addresses in the subject alternative name extension, you must ensure the following:
The third attribute, HTTP_PARAMS.csrRequestorEmail, is the email component of the subject name in an enrollment request--it is an HTTP input value that gets added to the request when a user uses the manual enrollment form; for details, see "Enrollment Forms".
If you enable the default policy rule, the server automatically checks the certificate request for attributes AUTH_TOKEN.mail, AUTH_TOKEN.mailalternateaddress, and HTTP_PARAMS.csrRequestorEmail. If the server finds any of the attributes, it sets the attribute value in the extension and then adds the extension to certificates specified by the predicate parameter. If none of the attributes are in a request, the server does not add the subject alternative name extension to the certificate.
|
Subject Directory Attributes Extension Policy |
The SubjectDirectoryAttributesExt plug-in module implements the subject directory attributes extension policy. This policy enables you to configure Certificate Management System to add the Subject Directory Attributes Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to specify any desired directory attribute values for the subject of the certificate.
As per the PKIX standard, inclusion of this extension in certificates is not essential; the standard suggests that the extension may be used in local environments. For general guidelines on setting the subject directory attributes extension, see "subjectDirectoryAttributes" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The subject directory attributes extension policy in Certificate Management System allows you to include up to three directory attributes in the extension. For each attribute that you want to include in the extension, you need to specify the attribute name and its value--the name must be the X.500 directory attribute name itself and the attribute value can be derived from the request or directly entered in the policy configuration as a string value.
The list of directory attributes supported by default are shown as permissible values for the attribute<n>.attributeName parameter explained in Table 18.26. You can extend the list of attributes supported by the policy by defining new X.500 directory attributes. For details on defining new attributes, see "Extending Attribute Support".
Note that, during installation, Certificate Management System does not create an instance of the subject directory attributes extension policy. If you want the server to add this extension to certificates, you must create an instance of the SubjectDirectoryAttributesExt module and configure it. For instructions, see "Step 4. Add New Policy Rules".
SubjectDirectoryAttributesExt Module
The Java class that implements the subject directory attributes extension policy is as follows:
com.netscape.certsrv.policy.SubjectDirectoryAttributesExt
Figure 18.27 shows how the configurable parameters for the SubjectDirectoryAttributesExt module are displayed in the CMS window.
Figure 18.27 Parameters defined in the SubjectDirectoryAttributesExt module
The configuration shown in Figure 18.27 creates a policy rule named SubDirAttrForClientCert, which enforces a rule that the server should set the subject directory attributes extension in client certificates.
Table 18.26 provides details for each of these parameters.
|
Subject Key Identifier Extension Policy |
The SubjectKeyIdentifierExt plug-in module implements the subject key identifier policy. This policy enables you to configure Certificate Management System to add the Subject Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) to certificates. The extension is used to identify certificates that contain a particular public key--that is, the extension is used to uniquely identify a certificate from among several that have the same subject name.
Typically, the subject key identifier extension is used in CA certificates as it helps determine which CA key is being certified in a CA certificate. To facilitate chain building, you should consider adding this extension to conforming subordinate CA certificates (subordinate Certificate Managers' CA signing certificates) issued by Certificate Management System. You may also want to consider adding this extension to other or all certificates. For example, if added to end-entity certificates, the extension provides a means for identifying certificates containing the particular public key used in an application. If an end entity has multiple certificates, especially from multiple CAs, the subject key identifier provides a means to quickly identify the set of certificates that contain a particular public key.
For general guidelines on setting the subject key identifier extension, see "subjectKeyIdentifier" in Appendix B of Netscape Certificate Management System Installation and Deployment Guide.
The subject key identifier extension policy in Certificate Management System allows setting of the subject key identifier extension as defined in its X.509 definition. It enables you to specify the method for forming the Key Identifier.
By default, the policy supports three types of methods for deriving the Key Identifier; the default methods for forming the Key Identifier are based on PKIX recommendations as defined in section 4.2.1.2. They are as follows:
You can also customize the method for deriving the Key Identifier by subclassing the policy and overriding the following method:
formKeyIdentifier(X509CertInfo certInfo, IRequest req)
For details, check the CMS SDK installed at this location:
<server_root>/cms_sdk/sdkdocs
You may also want to check the CMS samples installed here:
<server_root>/cms_sdk/samples
If enabled, the policy adds a Subject Key Identifier Extension to an enrollment request if the extension does not already exist. If the extension exists in the request, for example from a CRMF request, the policy replaces the extension. In case of manual enrollments, after an agent approves the enrollment request, the policy accepts any Subject Key Identifier Extension that is already there.
During installation, Certificate Management System automatically creates an instance of the subject key identifier extension policy. See "SubjectKeyIdentifierExt Rule".
SubjectKeyIdentifierExt Module
The Java class that implements the subject key identifier extension policy is as follows:
com.netscape.certsrv.policy.SubjectKeyIdentifierExt
Figure 18.28 shows how the configurable parameters for the SubjectKeyIdentifierExt module are displayed in the CMS window.
Figure 18.28 Parameters defined in the SubjectKeyIdentifierExt module
The configuration shown in Figure 18.28 creates a policy rule named SubKeyIDExtForAllCert, which enforces a rule that the server should set the subject key identifier extension in all certificates.
Table 18.27 provides details for each of these parameters.
SubjectKeyIdentifierExt Rule
The policy rule named SubjectKeyIdentifierExt is an instance of the SubjectKeyIdentifierExt module. Certificate Management System automatically creates this rule during installation. By default, the rule is configured as follows:
For details on individual parameters defined in the rule, see Table 18.27. It is important that you review this rule and make the appropriate changes required by your PKI setup. For example, if you're planning to issue multiple certificates to an end entity and want to assist applications in identifying the appropriate end-entity certificate, you should consider modifying the predicate expression to add this extension to all end-entity certificates. For instructions, see "Step 2. Modify Existing Policy Rules". Also, if you need to add additional instances, follow the instructions in "Step 4. Add New Policy Rules".
|
|
|