Certificate Template Operations

Regular expressions for enrollment are used to validate that the data entered in the certificate subject fields meets certain criteria.

To configure a system-wide regular expression:

1. On the Enrollment RegExes tab, double-click a subject part row in the grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.
2. On the Enrollment RegEx dialog, in the RegEx field, enter a regular expression against which to validate the subject part. See Regular Expressions for examples.
3. In the Error field, enter an error message to be displayed to the user in the enrollment pages of the Keyfactor Command Management Portal or as a response to an enrollment API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request when the subject part referenced in the CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. or entered for a PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. does not match the regular expression defined for the subject part field. Note that the error message already includes the subject part followed by a colon (e.g. Organization: or Invalid O provided: depending on the interface). Your custom message follows this.
4. Click Save to save the regular expression.

Enrollment defaults allow you to define default values for select certificate subject parts that will auto-populate on the PFX enrollment and CSR generation pages in the Keyfactor Command Management Portal.

To configure a system-wide enrollment default:

1. On the Enrollment Defaults tab, double-click a subject part row in the enrollment defaults grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.

2. On the Enrollment Default dialog, in the Value field, enter a value to auto-populate in the PFX enrollment and CSR generation pages of the Keyfactor Command Management Portal. During PFX enrollment or CSR generation, the user can accept the value or modify it; it is not enforced.

3. Click Save to save the default.

Policies for templates cover the following settings:

Enrollment Policies:

• Allow Wildcards

  Enable this option to allow certificates to be created containing wildcards (e.g. *.keyexample.com). The default is enabled.

• Allow Public Key In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. Reuse

  Enable this option to allow public keys to be reused on certificate renewals. The default is enabled.

• Enforce RFC 2818 Compliance

  Enable this option to force certificate enrollments made through Keyfactor Command to include at least one DNS The Domain Name System is a service that translates names into IP addresses. SAN. In the Keyfactor Command Management Portal, this causes the CN A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). entered in PFX enrollment to automatically be replicated as a DNS Name SAN, which will be set to Read Only. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set. The default is disabled.

  Tip:  For CA gateways, some cloud providers will automatically include SANs without you needing to enable the Enforce RFC 2818 Compliance option. Some cloud providers won’t support submission of a SAN that matches the CN (which is the default when you enable the RFC 2818 option). Keyfactor recommends disabling this option for CA gateways.

Supported Key Types:

• RSA Key Sizes

  A list of RSA key sizes that are valid for enrollment through Keyfactor Command. If a key size is not in this list, enrollment will not be supported for requests specifying that key size. To change the selected values, in the dropdown uncheck any values you do not wish to support. The default values are:

  1024, 2048, 4096

• ECC Elliptical curve cryptography (ECC) is a public key encryption technique based on elliptic curve theory that can be used to create faster, smaller, and more efficient cryptographic keys. ECC generates keys through the properties of the elliptic curve equation instead of the traditional method of generation as the product of very large prime numbers. Curves

  A list of elliptic curve algorithms that are valid for enrollment through Keyfactor Command. To change the selected values, in the dropdown uncheck any values you do not wish to support. The default values are:

  P-256/prime256v1/secp256r1, P-384/secp384r1, P-521/secp521r1

• Allow Ed448 / Allow Ed25519

  Set global template values for allowing Ed448 and Ed25519 keys. Templates that utilize Ed448 or Ed25519 key types can be imported into Keyfactor Command. These key types are only available with EJBCA CAs. Default is disabled.

The information in the Details section is for reference and cannot be edited. This includes:

• Template Short Name—The common name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). of the template. This name typically does not contain spaces.

• Template Display Name—The display name of the template.

• Key Size—The minimum supported key size of the template.

• OID—For a Microsoft certificate template, the object ID of the template retrieved from Active Directory. For an EJBCA certificate template, this field is generated within Keyfactor Command as an object identifier Object identifiers or OIDs are a standardized system for identifying any object, concept, or "thing" with a globally unambiguous persistent name., but does not follow official OID Object identifiers or OIDs are a standardized system for identifying any object, concept, or "thing" with a globally unambiguous persistent name. conventions.

• Curve—For ECC templates, the elliptic curve algorithm defined for the certificate template.

In the Friendly Name section, enter a Friendly Name, if desired. Template friendly names, if configured, appear in template selection dropdowns in place of the template short names. This can be useful in environments where the template short names are long or not very human readable. This setting is not required to enable enrollment or configure private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. retention.

In the Allowed Enrollment Types section, click the toggle buttons to enable the options for CSR Enrollment, PFX Enrollment and/or CSR Generation as desired. Enabling these options causes the template to appear in dropdowns in the corresponding section of the Management Portal. In the case of CSR Enrollment and PFX Enrollment, the templates only appear in dropdowns on the enrollment pages if they are available for enrollment from a CA also configured for enrollment within Keyfactor Command (see Adding or Modifying a CA Record).

In the Private Key Retention section, click the toggle button to enable Private Key Retention, if desired, and select the retention type in the dropdown. Enter the number of days, weeks, months, or years to keep the encrypted private key stored in the Keyfactor Command database based on the type selected, then select the desired time frame (Day(s), Week(s), Month(s), or Year(s)). You will not have the option to choose a retention timeframe if you choose Indefinite.

Configuring private key retention allows the private keys for certificates enrolled through Keyfactor Command to be stored, encrypted, in the Keyfactor Command database for a user-definable period of time.

The private key retention configuration options are:

• Blank

  The private key will not be retained if the box is unchecked, or the blank option is selected.

• Indefinite

  The private key will be retained until it is explicitly deleted.

• After Expiration

  The private key will be retained until the specified number of days, weeks, months or years after the certificate expires, at which point it will be scheduled for deletion.

• From Issuance

  The private key will be retained until the specified number of days, weeks, months or years after the date on which the certificate was issued, at which point it will be scheduled for deletion.

On the Enrollment Fields tab, you can add custom enrollment fields. These are configured on a per-template basis to allow you to submit custom fields with CSR enrollments and PFX enrollments to supply custom request attributes to the CA during the enrollment process. This functionality offers such benefits as:

• Preventing users from requesting invalid certificates, based on your specific certificate requirements per template.
• Providing additional information to the CA with the request.

Once created on the template, these values are shown in Keyfactor Command on the PFX and CSR enrollment pages in the Additional Enrollment Fields section. The fields are mandatory during enrollment. The data will appear on the CA / Issued Certificates attribute tab for certificates enrolled with a template configured with Keyfactor Command enrollment fields.

On the Enrollment Fields tab you can add, edit and delete enrollment fields.

To add a new enrollment field:

1. On the Enrollment Fields tab of the selected template click Add. If there are existing fields configured they will appear in a list on this tab.
2. Enter a Field Name for the new custom field. This name will appear on the enrollment pages.
3. Select a Parameter Type. The options are:
   • String: A free-form data entry field.
   • Multiple Choice: Provides a list of acceptable values for the field. A text box will open up below this choice for you to enter the list of acceptable values. Add each value on a separate line. Click OK to close the box.
4. Click Save to save and close the add window.

The Restrict Allowed Requesters option is used to select Keyfactor Command security roles that a user must belong to in order to successfully enroll for certificates in Keyfactor Command using this template. This is typically used for EJBCA templates and Microsoft templates that are not in the local Active Directory forest, since in these cases, Keyfactor Command cannot make use of the access control model of the CA itself to determine which users can enroll for certificates; this setting replaces that functionality. This setting is similar to setting request certificates for the selected security roles at the template level on a Microsoft CA. For multi-forest environments, this setting should be used on any templates from forests other than the Keyfactor Command forest that will be used for enrollment regardless of the type of trust between the forests, including two-way trusts.

On the Authorization Methods tab you can add, edit and delete allowed requesters.

To add a new allowed requester, click to toggle the Restrict Allowed Requesters button and:

1. On the Authorization Methods tab of the selected template click Add. If there are existing requesters configured, they will appear in a list on this tab.
2. In the Security Role dropdown, select a Keyfactor Command security role (see Security Roles and Identities) to grant enrollment permissions on the template.
3. Click Save to save and close the add window.

From the Metadata tab you can:

• View the metadata field settings for that specific template.

• Configure how (or whether) the metadata fields will appear during enrollment for that specific template.

System-wide metadata fields are defined in System Settings (see Certificate Metadata). Once the system-wide metadata has been defined, the Enrollment Handling setting can be configured on a template-specific basis, potentially overriding a system-wide required, hidden or optional setting for that metadata field on that template, causing only the set of fields configured for the template to appear on the PFX and CSR enrollment pages when the template is selected, and determining if they are required or optional.

A default value for a metadata field can also be configured that is different from, and overrides, the default value entered for the system-wide metadata field. For string metadata fields, a regular expression validation and error message can also be configured on a template-specific basis. The order in which the metadata fields appear can be changed globally (see Sorting Metadata Fields).

The Metadata grid columns can be sorted by clicking the column heading (except Default Value). The columns are:

• Name: The name of the metadata field.

• Data Type: The metadata field type: String, Integer, Date, Boolean, Multiple Choice, or Big Text.

• Enrollment Handling: The handling of the metadata field during enrollment: Optional, Required or Hidden.

• Default Value: The default value during enrollment, if there is one, will be displayed.

• Uses System-Wide Settings: Displays Yes if system-wide settings are in effect for this template, or No if template-specifc settings are in effect.

To configure metadata fields for a template:

1. On the Metadata tab, double-click a row in the metadata grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.
2. In the Metadata dialog in the System-Wide Settings section, review the existing system-wide settings for the metadata field.
3. In the Template Settings section, click to toggle the Override system-wide settings button. Configure the template-level settings for the metadata field. The available fields will vary depending on the type of the metadata field and may include:

   • Choose the Enrollment Options for this template by selecting the appropriate radio button:

     1. Optional: The metadata field will appear during enrollment with this template, but it will not be required to complete enrollment.

     2. Required: This field will be required in order to complete enrollment with this template.

     3. Hidden: This field will not be displayed during enrollment with this template.

   • Set the Default Value if desired. If no default value is desired, the field may be left blank. For Multiple Choice type metadata fields, this field will appear as a dropdown where you can select from the existing values configured for the metadata field.
   • If desired, set a RegEx Message and RegEx Validation string specific to the template used to validate the value upon enrollment entry, and any error message to display if the entry does not match the regex definition. For more information, see Adding or Modifying a Metadata Field. This option is supported for string type metadata fields.
4. Click Save on the Metadata dialog to save changes for each metadata field.

Enrollment Regexes can be applied at either the template-specifc level or system-wide level. Template-level regular expressions are used to validate that the certificate subject data entered on the CSR enrollment, CSR generation, and PFX enrollment pages meets certain criteria. Template-level regular expressions differ from system-wide regular expressions (see Configuring System-Wide Settings) as they apply on a per-template basis, rather than system-wide. In the case of a conflict in a regular expression between system-wide and template-level definitions, the template-level regular expression takes precedence.

The Enrollment Regexes grid columns can be sorted by clicking the column heading (except Regex and Error). The columns are:

• Subject Part Full Name: The descriptive name of the certificate subject part (e.g. Common Name).

• Subject Part: The code for the certificate subject information part. For instance, CN=Common Name.

• RegEx: The regular expression to apply to the subject part.

• Error: The error message to display (upon Save when enrolling), when the entry does not meet the specified criteria.

• Uses System-Wide Settings: Displays Yes if system-wide settings are in effect for this template, or No if template-specifc settings are in effect.

To configure template regular expression fields for a template:

1. On the Template Regexes tab, double-click a row in the regular expression grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.
2. In the Enrollment RegEx dialog in the System-Wide Settings section, review the existing system-wide settings for the subject part.
3. In the Template Settings section, click to toggle the Override system-wide settings button. Enter a regular expression in the RegEx field. See Regular Expressions for examples.
4. In the Error field enter the error message to display during enrollment if the data entered for the subject part does not meet the validation rule.

5. Click Save on the Enrollment RegEx dialog to save each template-level regular expression.

The regular expressions will be applied at the time of enrollment. Entries which do not match the regular expression requirements will be flagged with an error message during enrollment entry when you click Enroll (or Generate for CSR generation).

Template-level enrollment defaults allow you to define default values for certificate subject parts that will auto-populate on the PFX enrollment and CSR generation pages in the Keyfactor Command Management Portal. Template-level default values differ from system-wide default values (see Configuring System-Wide Settings) as they apply on a per-template basis, rather than system-wide. In the case of a conflict in a default value between system-wide and template-level definitions, the template-level default values takes precedence.

The Enrollment Defaults grid columns can be sorted by clicking the column heading (except Value). The columns are:

• Subject Part Full Name: The descriptive name of the certificate subject part (e.g. Common Name).

• Subject Part: The code for the certificate subject information part. For instance, CN=Common Name.

• Value: The default value to apply to the subject part.

• Uses System-Wide Settings: Displays Yes if system-wide settings are in effect for this template, or No if template-specific settings are in effect.

To configure template-level default values for a template:

1. On the Enrollment Defaults tab, double-click a row in the defaults grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.
2. In the Enrollment Default dialog in the System-Wide Settings section, review the existing system-wide default value for the subject part.
3. In the Template Settings section, click to toggle the Override system-wide settings button. Enter a template-level default value for the subject part in the Value field.
4. Click Save on the Enrollment Default dialog to save each template-level default.

The Policies Tab allows you to set template-level policy definitions which take precedence over system-wide settings (see Configuring System-Wide Settings).

The Enrollment Policies section displays the System-Wide Setting (Yes or No) for each of the template enrollment policies and allows you to Override System-Wide Setting for the specific template. Enabling Override System-Wide Setting will cause the system setting is to be disregarded and allow you to enable or disable the setting for that policy on the template. Override System-Wide Setting does not automatically set the policy to the opposite, the selection on the policy (enabled/disabled) will supersede any other settings.

• Allow Wildcards

  Enable this option to allow certificates to be created containing wildcards (e.g. *.keyexample.com) using this template.

• Allow Public Key Reuse

  Enable this option to allow private keys to be reused on certificate renewals made using this template.

• Enforce RFC 2818 Compliance

  Enable this option to force certificate enrollments made through Keyfactor Command for this template to include at least one DNS SAN. In the Keyfactor Command Management Portal, this causes the CN entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set.

  Tip:  For CA gateways, some cloud providers will automatically include SANs without you needing to enable the Enforce RFC 2818 Compliance option. Some cloud providers won’t support submission of a SAN that matches the CN (which is the default when you enable the RFC 2818 option). Keyfactor recommends disabling this option for CA gateways.

The Supported Key Types section displays the System-Wide Setting (value or Yes/No) for the supported key type The key type identifies the type of key to create when creating a symmetric or asymmetric key. It references the signing algorithm and often key size (e.g. AES-256, RSA-2048, Ed25519). and allows you to Override System-Wide Setting for the specific template. Enabling Override System-Wide Setting will cause the system-wide setting is to be disregarded, enable the settings field, and allow you to select the setting for that policy on the template. Override System-Wide Setting does not automatically set the policy to the opposite, the selection on the policy (values or enabled/disabled) will supersede any other settings. Depending on the type of template selected, one of these settings will be available for configuration:

RSA Key Sizes

A list of RSA key sizes that are valid for enrollment through Keyfactor Command for this template. If a key size is not in this list, enrollment will not be supported for requests specifying that key size. To change the selected values, in the dropdown check any values you wish to support. The available values are: 1024, 2048, 4096

ECC Curves

A list of elliptic curve algorithms that are valid for enrollment through Keyfactor Command for this template. To change the selected values, in the dropdown check any values you wish to support. The available values are: P-256/prime256v1/secp256r1, P-384/secp384r1, P-521/secp521r1

Allow Ed448 for Template / Allow Ed25515 for Template

Enable or disable allowing Ed448 or Ed25519 keys on the template.

Note:   When enrolling with the template, the key size of the request is validated against the template key size. This allows for a key size to be set on a template in Keyfactor Command for validation purposes that can be different than the CA template key size setting. Care should be taken to make sure any template policy settings take into consideration CA template key size settings so that errors do not occur at the CA level.


• If a CSR Enrollment request is made with a key size that is not valid, per the template policy settings, an error will be displayed when you click the Enroll button (for example, the CSR has a key size of 2048 but the template policy supports only 4096).

• For PFX Enrollment, the request will contain the minimum settings from the Keyfactor Command presiding template settings.