Chapter 2. Making Rules for Issuing Certificates (Certificate Profiles)

The Certificate System provides a customizable framework to apply policies for incoming certificate requests and to control the input request types and output certificate types; these are called certificate profiles. Certificate profiles set the required information for certificate enrollment forms in the Certificate Manager end-entities page. This chapter describes how to configure certificate profiles.

2.1. About Certificate Profiles

A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication method, the authorization method, the default certificate content, constraints for the values of the content, and the contents of the input and output for the certificate profile. Enrollment and renewal requests are submitted to a certificate profile and are then subject to the defaults and constraints set in that certificate profile. These constraints are in place whether the request is submitted through the input form associated with the certificate profile or through other means. The certificate that is issued from a certificate profile request contains the content required by the defaults with the information required by the default parameters. The constraints provide rules for what content is allowed in the certificate.
The Certificate System contains a set of default profiles. While the default profiles are created to satisfy most deployments, every deployment can add their own new certificate profiles or modify the existing profiles. All the profiles that are served by the Certificate System are listed and their corresponding profile configuration files defined in the CS.cfg file.
  • Authentication. In every certification profile can be specified an authentication method. The authentication method specified must be one of the registered authentication instances from CS.cfg.
  • Authorization. In every certification profile can be specified an authorization method. The authorization method specified must be one of the registered authorization instances from CS.cfg.
  • Profile inputs. Profile inputs are parameters and values that are submitted to the CA when a certificate is requested. Profile inputs include public keys for the certificate request and the certificate subject name requested by the end entity for the certificate.
  • Profile outputs. Profile outputs are parameters and values that specify the format in which to provide the certificate to the end entity. Profile outputs include base-64 encoded files, CMMF responses, and PKCS #7 output, which also contains the CA chain.
  • Certificate content. Each certificate defines content information, such as the name of the entity to which it is assigned (the subject name), its signing algorithm, and its validity period. What is included in a certificate is defined in the X.509 standard. With version 3 of the X509 standard, certificates can also contain extensions. For more information about certificate extensions, see Section B.3, “Standard X.509 v3 Certificate Extension Reference”.
    All of the information about a certificate profile is defined in the set entry of the profile policy in the profile's configuration file. When multiple certificates are expected to be requested at the same time, multiple set entries can be defined in the profile policy to satisfy needs of each certificate. Each policy set consists of a number of policy rules and each policy rule describes a field in the certificate content. A policy rule can include the following parts:
    • Profile defaults. These are predefined parameters and allowed values for information contained within the certificate. Profile defaults include the validity period of the certificate, and what certificate extensions appear for each type of certificate issued.
    • Profile constraints. Constraints set rules or policies for issuing certificates. Amongst other, profile constraints include rules to require the certificate subject name to have at least one CN component, to set the validity of a certificate to a maximum of 360 days, to define the allowed grace period for renewal, or to require that the subjectaltname extension is always set to true.

2.1.1. The Enrollment Profile

The enrollment profile itself is defined in a special .cfg file in the /instance_path/ca/profiles/ca/ directory for the CA, for example, /var/lib/pki/pki-ca/ca/profiles/ca/. The parameters for this file defining the inputs, outputs, and policy sets are listed in more detail in Section 2.2.3, “Creating and Editing Certificate Profiles through the Command Line”.
A profile usually contains inputs, policy sets, and outputs, as illustrated in the caUserCert profile in Example 2.1, “Example caUserCert Profile”.

Example 2.1. Example caUserCert Profile

The first part of a certificate profile is the description. This shows the name, long description, whether it is enabled, and who enabled it.
desc=This certificate profile is for enrolling user certificates.
visible=true
enable=true
enableBy=admin
name=Manual User Dual-Use Certificate Enrollment

Note

The missing auth.instance_id= entry in this profile means that with this profile, authentication is not needed to submit the enrollment request. However, manual approval by an authorized CA agent will be required to get an issuance.
Next, the profile lists all of the required inputs for the profile:
input.list=i1,i2,i3
input.i1.class_id=keyGenInputImpl
input.i2.class_id=subjectNameInputImpl
input.i3.class_id=submitterInfoInputImpl
For the caUserCert profile, this defines the keys to generate, the fields to use in the subject name, and the fields to use for the person submitting the certificate.
  • Key generation specifies that the key pair generation during the request submission be CRMF-based and has a drop-down menu to select the key bit size.
  • Subject name is used when distinguished name (DN) parameters need to be collected from the user; the text fields in the input form can be used to create the subject name in the certificate.
    • UID
    • Email
    • Common name
    • Organizational unit
    • Organization
    • Country
  • Requester. This input has the following form fields:
    • Requester name
    • Requester email
    • Requester phone
Next, the profile must define the output, meaning the format of the final certificate. There are several pre-defined outputs. More than one of these can be used, but none of the values of the output can be modified.
output.list=o1
output.o1.class_id=certOutputImpl
For caUserCert, the output displays the certificate in pretty print format. This output needs to be specified for any automated enrollment. Once a user successfully authenticates and is authorized using the automated enrollment method, the certificate is automatically generated, and this output page is returned to the user. In an agent-approved enrollment, the user can obtain the certificate, once it is issued, by providing the request ID in the CA end entities page.
The last — largest — block of configuration is the policy set for the profile. Policy sets list all of the settings that are applied to the final certificate, like its validity period, its renewal settings, and the actions the certificate can be used for. The policyset.list parameter identifies the block name of the policies that apply to one certificate; the policyset.userCertSet.list lists the individual policies to apply.
For example, the sixth policy populates the Key Usage Extension automatically in the certificate, according to the configuration in the policy. It sets the defaults and requires the certificate to use those defaults by setting the constraints:
policyset.list=userCertSet
policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9
...
policyset.userCertSet.6.constraint.class_id=keyUsageExtConstraintImpl
policyset.userCertSet.6.constraint.name=Key Usage Extension Constraint
policyset.userCertSet.6.constraint.params.keyUsageCritical=true
policyset.userCertSet.6.constraint.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.constraint.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.constraint.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.constraint.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.constraint.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.constraint.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.constraint.params.keyUsageCrlSign=false
policyset.userCertSet.6.constraint.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.constraint.params.keyUsageDecipherOnly=false
policyset.userCertSet.6.default.class_id=keyUsageExtDefaultImpl
policyset.userCertSet.6.default.name=Key Usage Default
policyset.userCertSet.6.default.params.keyUsageCritical=true
policyset.userCertSet.6.default.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.default.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.default.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.default.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.default.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.default.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.default.params.keyUsageCrlSign=false
policyset.userCertSet.6.default.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.default.params.keyUsageDecipherOnly=false
...

2.1.2. Certificate Extensions: Defaults and Constraints

An extension configures additional information to include in a certificate or rules about how the certificate can be used. These extensions can either be specified in the certificate request or taken from the profile default definition and then enforced by the constraints.
A certificate extension is added or identified in a profile by adding the default which corresponds to the extension and sets default values, if the certificate extension is not set in the request. For example, the Basic Constraints Extension identifies whether a certificate is a CA signing certificate, the maximum number of subordinate CAs that can be configured under the CA, and whether the extension is critical (required):
policyset.caCertSet.5.default.name=Basic Constraints Extension Default
policyset.caCertSet.5.default.params.basicConstraintsCritical=true
policyset.caCertSet.5.default.params.basicConstraintsIsCA=true
policyset.caCertSet.5.default.params.basicConstraintsPathLen=-1
The extension can also set required values for the certificate request called constraints. If the contents of a request do not match the set constraints, then the request is rejected. The constraints generally correspond to the extension default, though not always. For example:
policyset.caCertSet.5.constraint.class_id=basicConstraintsExtConstraintImpl
policyset.caCertSet.5.constraint.name=Basic Constraint Extension Constraint
policyset.caCertSet.5.constraint.params.basicConstraintsCritical=true
policyset.caCertSet.5.constraint.params.basicConstraintsIsCA=true
policyset.caCertSet.5.constraint.params.basicConstraintsMinPathLen=-1
policyset.caCertSet.5.constraint.params.basicConstraintsMaxPathLen=-1

Note

To allow user supplied extensions to be embedded in the certificate requests and ignore the system-defined default in the profile, the profile needs to contain the User Supplied Extension Default, which is described in Section B.1.32, “User Supplied Extension Default”.

2.1.3. Inputs and Outputs

Inputs set information that must be submitted to receive a certificate. This can be requester information, a specific format of certificate request, or organizational information.
The outputs configured in the profile define the format of the certificate that is issued.
In Certificate System, profiles are accessed by users through enrollment forms that are accessed through the end-entities pages. (Even clients, such as TPS, submit enrollment requests through these forms.) The inputs, then, correspond to fields in the enrollment forms. The outputs correspond to the information contained on the certificate retrieval pages.