PFX Enrollment

The PFXClosed 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. EnrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). page provides the ability to submit a certificate request and download the resulting PFX certificate file. Given the power involved in allowing a user to generate his or her own subject name and automatically receive a certificate in this subject name, Keyfactor recommends that permissions for this feature are only given to very trusted users and/or that you consider making use of Keyfactor Command workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. with a RequireApproval step (see Adding, Copying or Modifying a Workflow Definition).

Important:  Before you can use the PFX enrollment function, you must:
Note:  All enrollment (PFX, ODKG and CSRClosed 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.), renewal, and revocation requests flow through Keyfactor Command workflow (see Workflow Definitions).
Note:   Some subject fields may be automatically populated by enrollment defaults configured at the system-wide or enrollment pattern level. You may override the system-populated data, if desired. Any regular expressions set at the system-wide or enrollment pattern level will be used to validate the data entered in the subject fields. Policies set at the system-wide or enrollment pattern level will affect the request. For more information, see Enrollment Pattern Operations. Subject data may also be overridden after an enrollment request is submitted either as part of a workflow (see Update Certificate Request Subject\SANs for Microsoft CAs) or using the Subject Format application setting (see Application Settings: Enrollment Tab).
Tip:  You can expand and collapse sections of the PFX enrollment page by clicking on the plus/minus icon to the left of each section title.

To request a certificate via PFX:

  1. In the Keyfactor Command Management Portal, browse to Enrollment > PFX Enrollment.

  2. From the Certificate Authority Information section select an enrollment pattern from the Enrollment Pattern dropdown. If you are enrolling from a standalone CA, enable the Use Standalone CA option instead of selecting an enrollment template.

    The enrollment patterns are organized by configuration tenantClosed A grouping of CAs. The Microsoft concept of forests is not used in EJBCA so to accommodate the new EJBCA functionality, and to avoid confusion, the term forest needed to be renamed. The new name is configuration tenant. For EJBCA, there would be one configuration tenant per EJBCA server install. For Microsoft, there would be one per forest. Note that configuration tenants cannot be mixed, so Microsoft and EJBCA cannot exist on the same configuration tenant. (formerly known as forestClosed An Active Directory forest (AD forest) is the top most logical container in an Active Directory configuration that contains domains, and objects such as users and computers.). If you have multiple configuration tenants and enrollment patterns with similar names, be sure to select the enrollment pattern in the correct configuration tenant.

    The list of enrollment patterns that appears in the dropdown depends on the enrollment pattern’s configurations for Use AD Permissions and Associated Roles (see Basic Information Tab):

    • Use AD Permissions Enabled: An enrollment pattern appears if the user is an Active Directory user, the user has certificate request permissions on the template associated with the enrollment pattern, and Keyfactor Command is installed on a domain-joined Windows server.

    • Use AD Permissions Disabled: An enrollment pattern appears if the user holds a Keyfactor Command security role listed in Associated Roles for the enrollment pattern.

    Figure 113: Select an Enrollment Pattern

  3. If the template for your selected enrollment pattern supports multiple options for key sizeClosed The key size or key length is the number of bits in a key used by a cryptographic algorithm., key typeClosed 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/or elliptic curve—and system-wide or enrollment pattern policies allow multiple values—you can select a Key Algorithm and Key Size or Curve for the request. If the template provides only one value or the policy restricts the options, these dropdowns will be grayed out.

    Note:  The supported key algorithms for enrollment are determined based on:
    • System-wide enrollment pattern policy
    • Individual enrollment pattern policy
    • Supported algorithms set on the template at the CA level

    When configuring key information policies at the enrollment pattern level, only key sizes valid for the selected algorithm will be available. These are governed by the system-wide policy, enrollment pattern policy, and supported key sizes.

    For PFX enrollment and CSR generation, dropdowns for Key Algorithm and Key Size are displayed if the template for the selected enrollment pattern, with its applied policy settings, supports multiple options. If the certificate template configuration or applied policy limits the template to a single key algorithm or size, the dropdowns will be grayed out.

    If ECCClosed 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. is selected as the key algorithm, an elliptic curve can be chosen using a search-select field. Only curves supported by the system-wide policy, enrollment pattern policy, and the template's configuration will appear in this field.

    Figure 114: PFX Enrollment for ECC Enrollment Pattern Displaying Elliptic Curve

  4. In the Certificate Authority field, select the Certificate Authority from which the certificate should be requested, or accept the default of Auto-Select.

    Note:   The list of CAs that appears in the dropdown depends on the enrollment pattern's Restrict CAs setting (see Basic Information Tab) and the configuration tenant of the template associated with the enrollment pattern:

    • Restrict CAs Enabled: The CAs listed in the enrollment pattern’s Certificate Authorities list, limited to those in the same configuration tenant as the associated template.

    • Restrict CAs Disabled: All enterprise CAs defined in Keyfactor Command that share the same configuration tenant as the associated template.

    In either case, in order for the CA to appear in the dropdown:

    • The CA must have the Use for Enrollment option enabled in Keyfactor Command.

    • The template associated with the enrollment pattern must be available for enrollment on the CA.

    • The template must have certificate request permissions granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab).

    If Auto-Select is chosen, a certificate authority (CA) will be randomly selected from the CAs available for enrollment with the specified enrollment pattern, which depends on the configuration of the RestrictCAs setting as noted above. This field is optional unless the enrollment is being done against a standalone CA, in which case it is required.

    Standalone CAs do not use templates or enrollment patterns and will be shown if certificate request permissions on the CA have been granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab).

    Figure 115: Select an Enrollment Pattern and CA

    Tip:  The toggle for standalone CAs only appears if you have a standalone CA configured for enrollment.

  5. In the Certificate Subject Information section of the page, populate the fields as appropriate for the certificate being requested. Although Keyfactor Command does not strictly require the Common Name, the product does ship with a default regular expressionClosed A regular expression--RegEx--is a pattern used to validate data by ensuring it meets specific criteria. Several fields on the CSR enrollment, CSR generation, and PFX enrollment pages support RegEx validation, including certificate subject and metadata fields. requiring a value for this field since it is common for a CA to require this. This regular expression may have been altered in your environment (see Enrollment Pattern Operations).

    Figure 116: Certificate Subject Information

  6. If enabled, add a friendly name in the Custom Friendly Name section of the page. This section only appears if the Allow Custom Friendly Name application setting is set to True. If the Require Custom Friendly Name application setting is set to True, a value is required in this field. For more information, see Application Settings: Enrollment Tab.

    Figure 117: Custom Friendly Name

  7. In the Subject Alternative Names (SANs) section of the page, click Add to add SANs if needed. In the Add SANs dialog, select a Type in the dropdown and in the Value box add one or more SANs of the selected type and save. Only SANs of a single type may be added in a single add action. Click Edit to change a SANClosed The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. field. The Edit SAN dialog includes only one SAN, not the multi-SAN block. Click Delete to delete a SAN.

    The SAN field in this interface supports: DNS name, IP version 4 address, IP version 6 address, User Prinicpal Name, Email. Alternate SANs may be submitted in requests using the Keyfactor APIClosed An API is 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..

    Important:  If the Enforce RFC 2818 Compliance option has been enabled for the selected enrollment pattern (see Enrollment Pattern Operations) or system-wide, a SAN will automatically be added with a DNSClosed The Domain Name System is a service that translates names into IP addresses. SAN matching the CNClosed 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 for the certificate. This SAN will not appear in the grid and cannot be edited.

    Figure 118: Add SANs

    Note:  If you are enrolling against an EJBCA CA, by default the total SAN length cannot exceed 2000 characters. If you need to enter SANs that will cause the total length to exceed this maximum, see Appendix - Configuring Support for Large or Custom SANs with EJBCA.

    Microsoft CAs by default support a total SAN size of 4k. If you need to enter SANs that will cause the total size to exceed this, please refer to this article:

    https://learn.microsoft.com/en-us/troubleshoot/windows-server/certificates-and-public-key-infrastructure-pki/expand-maximum-extension-size-limit-ad-cs#expand-the-limit-by-using-an-administrative-command-prompt
    Note:  If a regular expression is defined system-wide or at the enrollment pattern level (see Enrollment RegExes Tab) for a subject part or SAN, and that field is left blank, the regular expression will still be applied to an empty string. For example, if a regular expression is defined for the organization field but no organization is provided, the system treats the empty string as the input and applies the regular expression accordingly.

  8. If enrollment fields have been defined for the selected enrollment pattern (see Enrollment Fields Tab), the fields will display in the Additional Enrollment Fields section. Additional enrollment fields have a data type of either string or multiple choice. String fields will appear as a text box; multiple choice fields will appear as a dropdown. All additional enrollment fields are required.

    Figure 119: Populate Enrollment Fields

  9. In the Certificate Metadata section of the page, populate any defined certificate metadataClosed Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. fields (see Certificate Metadata, Configuring Template Options, and Adding or Modifying an Enrollment Pattern) as appropriate. These fields may be required or optional depending on your metadata configuration. Required fields will be marked with *Required next to the field label. Any completed values will be associated with the certificate once it has been imported into Keyfactor Command. The order in which the metadata fields appear can be changed (see Sorting Metadata Fields).

    Email metadata fields will allow for multiple email addresses to be added via a pop-up text box where email addresses are entered separated by comma or semicolon. During entry the addresses will appear as a single row in the metadata grid. However, after saving each email address will be displayed on a separate row.

    Tip:  If a hint has been provided for a specific metadata field, it will display in parentheses to the right of the metadata label.

    Figure 120: Populate Metadata Fields

  10. If enabled, in the Password section of the page, check the Use Custom Password box and enter and confirm a custom password to use in securing the PFX file. This section only appears if the Allow Custom Password application setting is set to True. The value in the Password Length field in application settings is shown for guidance when entering a password. For more information about both of these settings, see Application Settings: Enrollment Tab.

    Figure 121: Set a Custom Password

  12. The Certificate Owner section of the page appears if you set the Certificate Owner Role policy to Optional or Required at either the system-wide or enrollment policy level (see Configuring System-Wide Settings and Policies Tab). In the Owner Role Name field, select an owner for the certificate, if appropriate. The certificate owner is a security role defined in Keyfactor Command (see Security Roles and Claims). If the user assigning the owner is an administrator, the Owner Role Name will be a search select field in which to enter the new certificate owner. To narrow the list of results in the search select field, begin typing a search string in the search field. If the user assigning the owner is a limited access user, the Owner Role Name will be a dropdown. Only security roles of which the user is a member will appear in the dropdown.

    Figure 122: Select a Certificate Owner

  13. In the Certificate Delivery Format section of the page, select either Direct Download—to download the certificate immediately—or Install into Certificate Stores—to schedule the certificate to be added to one or more configured certificate stores. If you do not have any configured certificate stores, the Install into Certificate Stores option will not appear.

    The other options available in this section will change depending on the format type you select.

    If you selected Direct Download, follow these steps to configure the output.

    Select a File Format: The supported formats for output are:

    Figure 123: Delivery Format PFX Enrollment

    Configure Chain Options: Toggle Include Chain to On if you want the certificate chain to be included with the returned certificate.

    Note:  In order for chain certificates to be included with end entity certificates for download, one of the following must be true:

    Format-Specific Options:

    • PEM and JKS Formats: If Include Chain is enabled, choose a Chain Order:

      • End Entity First

      • Root First

      Note:  PFX and ZIP PEMClosed A ZIP archive containing multiple PEM encoded certificates, which may include an end entity certificate, certificate chain, and private key. formats automatically use the End Entity First order.

    • PEM Format: Include Subject Header appears only for the PEM file format. When toggled On, the first line in the PEM file contains the certificate’s subject information is included. When toggled Off, subject information is excluded from output. The default is On.

      If both the Include Chain and the Include Subject Header options are enabled, the subjects will be included for the end entity and chain certificates.

    • PFX Format: Use Legacy Encryption appears when the Enable Legacy Encryption application setting is enabled (see Application Settings: Enrollment Tab). If this option is toggled to On, the PFX file is encrypted using the historical algorithm (3DES/SHA1/RC2). If this option is toggled to Off, the newer algorithm set provided by Windows (AES256/SHA256/AES256) is used instead. The default for the PFX enrollment page can be set with the Use Legacy Encryption By Default application setting.

    • PFX Format: Target CSP appears when the Allow Cryptographic Service Providers (CSPs) application setting is enabled (see Application Settings: Enrollment Tab). Select a value if appropriate in your environment. This is typically not required.

    If you have any certificate stores defined, you may opt to install the certificate directly into one or more certificate stores on enrollment. If you choose to do this, the certificate will not be available for download on this page.

    To install a certificate into a certificate store, select the Install into Certificate Stores radio button and then click the Include Certificate Stores button. This will cause the Select Certificate Store Locations dialog to appear. Make your certificate store selections in this dialog as described in Select Certificate Store Locations, below, and click Include and Close. You will then see some additional fields on the enrollment page. Populate these as per Add to Certificate Stores and Information Required for Certificate Stores, below.

    The Select Certificate Store Locations dialog allows you to run queries against your certificate store list to select the store(s) to which to deploy. Check the box next to each certificate store location to which you want to distribute the certificate.

    Note:   Certificate stores appear in the grid if:
    • They are compatible with the certificate type.
    • They are in containers to which you have permissions.
    Tip:  You may change the search results by using the search fields at the top of the dialog. All of the Keyfactor Command grid search features are available to assist your search. See Using the Certificate Store Search Feature for more information on the available search fields. The default search criteria is AgentAvailable is equal to True.

    The actions on the Select Certificate Store Locations dialog are:

    • Include

      Click this to add the selected certificate store(s) to your certificate selection and leave the search dialog open for further searches.

    • Include and Close

      Click this to close the search dialog and add the selected certificate store(s) to your certificate selection, which will then be displayed and ready for updates as per the instructions in Add to Certificate Stores.

    • Close

      Click this to cancel the operation and return to the main page with no certificate stores selected.

    Figure 124: Select Certificate Store Locations Dialog

    The additional fields that appear on the page once you select at least one certificate store to distribute your certificate to include a grid section with a series of tabs that displays a tab for each type of certificate store selected with a list of the selected stores under each tab and required or optional additional fields below this, which vary depending on the certificate store type.

    Above this section are the following global options that apply to the add job as a whole:

    • Include Certificate Stores

      Open the Select Certificate Store Locations dialog again.

    • Schedule when to run the job for the certificate store

      In the Schedule dropdown, select a time at which the job to add the certificate to the store(s) should run. The choices are Immediate or Exactly Once at a specified date and time. If you choose Exactly Once, enter the date and time for the job. A job scheduled for Immediate running will run within a few minutes of saving the operation. The default is Immediate.

    For each selected certificate store you can apply the following actions:

    • Overwrite

      Check Overwrite below the grid to allow the selected certificate to overwrite any existing certificate in the same location with the same name or alias.

    • Alias

      Add an Alias below the grid, if applicable, for the certificate store type. See the Information Required by Certificate Store section, below, for more information.

      Note:   The tab heading of the certificate location will display an alert if an alias is required for the location.

      • The Alias field is a search-select entry type. The dropdown lists all aliases associated with the selected certificate store.

      • If an alias appears in multiple certificate stores, the number of locations is shown in parentheses next to the alias name. This indicator does not appear if the alias exists in only one selected store.
      • Users can enter a new alias as long as Custom Aliases are not forbidden on the certificate store type Certificate Store Types.
      • If you select an existing alias without checking Overwrite, the Save will fail and the certificate store(s) in which that alias already exists will be listed.

    • Custom Fields

      Add values for custom fields, if displayed.

    • Remove

      Select the certificate store and click Remove at the top of the grid to remove the selected certificate store from the page. The certificate will not be added to the store.

    You may return to the Select Certificate Store Locations dialog by clicking Include Certificate Stores above the grid. The current selections will be retained until you change them.

    Figure 125: PFX Enrollment: Certificate Store Delivery Format

    Figure 126: Alias Required Warning on Enrolling

    Each type of certificate store has different requirements for providing an alias or other additional information.

    The certificate store type fields that are relevant to certificate store use are:

    • Supports Entry Password

      If your certificate store type has this enabled, you will have the option to enter a password for the certificate entry in the certificate store on the addition of an entry into the certificate store.

      Figure 127: Certificate Store Type Configuration: Basic Tab

    • Supports Custom Alias

      A value of Required indicates that a custom alias will be required when a certificate is added to a certificate store. Optional indicates an alias can be associated with the entry if desired. If your certificate store type sets this to Forbidden, the Alias field will not display when adding a certificate to a certificate store unless Overwrite is checked on the add page. In this case, you’re not associating an alias with the certificate you’re adding to the store but rather specifying the alias of the certificate already in the store that you wish to replace (in function) with the new certificate you’re adding.

      The format of custom alias values varies depending on the certificate store type. In many cases, the alias is the thumbprint of the certificate. In some cases, it’s the file name of the certificate file or a custom alias provided at the time the certificate was added to the certificate store. For instance:

      Note:  Keyfactor Command will automatically strip out any spaces between the octets in thumbprints in the alias field, so it does not matter whether you enter the thumbprint with or without spaces.
      Tip:  When adding a certificate to a certificate store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite.

      The Alias field is a search-select entry type. The dropdown lists all aliases associated with the selected certificate store.

      • If an alias appears in multiple certificate stores, the number of locations is shown in parentheses next to the alias name. This indicator does not appear if the alias exists in only one selected store.
      • Users can enter a new alias as long as Custom Aliases are not forbidden on the certificate store type Certificate Store Types.
      • If you select an existing alias without checking Overwrite, the Save will fail and the certificate store(s) in which that alias already exists will be listed.

    • Entry Parameters

      Not all certificate store types will have entry parameters. The ones shown in Figure 128: Certificate Store Type Configuration: Entry Parameters Tab are for the custom Windows Certificate type for the Keyfactor custom-built IIS Certificate Store Manager extension (see Installing Custom-Built Extensions).

      Figure 128: Certificate Store Type Configuration: Entry Parameters Tab

  14. At the bottom of the page, click Enroll to begin the certificate request process.

    • If the request completes successfully and a certificate is issued, a success message featuring the following details will be shown:

      • The download format type.

      • Whether the private key will be included in the downloaded certificate.

      • Whether the certificate chain will be included.

      If the private key was not retained for the downloaded certificate, no password will be displayed. Instead, a message will indicate that the private key and certificate can be obtained from the certificate search page.

    • Your browser will begin download of your certificate unless you chose to install it directly into a certificate store. If you have configured PFX enrollment to use Windows authentication (the default) and have not selected the option to enter a custom password, you’ll see a one-time password that has been generated to secure the PFX file. You will need this password in order to open the PFX file.

      Figure 129: PFX Enrollment Completed Successfully

    • If you’ve configured the Keyfactor Command Management Portal to use basic authentication and you’ve configured the Use Active Directory Password application setting option to True, the message will indicate that the PFX file can be opened using the Active Directory domain password of the user making the request. For more information about configuring basic authentication versus Windows authentication, see Application Settings: Enrollment Tab.

      Note:  This option does not work when you authenticate to the Management Portal using Kerberos because Keyfactor Command does not have access to your credentials to apply your password to the PFX file.

    • If the enrollment pattern for the request or its associated template requires approval at the Keyfactor Command workflow level, you'll see a message that your request is suspended and is awaiting one or more approvals. The user(s) responsible for approving the request will be notified (if the workflow has been configured this way, see Adding, Copying or Modifying a Workflow Definition). You can use the My Workflows Created by Me tab (see Workflows Created by Me Operations) to check on the status of your request. If the Management Portal feature has been configured to send notification alerts when a certificate is issued following approval, you may receive an email message when your certificate is available for download. The email message may contain a download link. See Issued Certificate Request Alerts.

    • If the template associated with the enrollment pattern you selected requires manager approval at the CA level, you’ll see a message that your request is pending. The user responsible for approving issuance of pending certificates will be notified (if that Management Portal feature is configured, see Pending Certificate Request Alerts). You can visit the Certificate Requests page (see Certificate Requests) to check on the status of your pending request and certificate search (see Certificate Search and Collections) to complete the certificate download. If the Management Portal feature has been configured to send notification alerts when a pending certificate request is approved or denied, you may receive an email message when your certificate is available for download. The email message may contain a download link. See Issued Certificate Request Alerts and Denied Certificate Request Alerts.

    Tip:  The filename generated for the file for download is based on the CN of the certificate and will either include or not include the periods from the CN based on the configuration of the Allow Periods in Certificate Filenames application setting (see Application Settings: Enrollment Tab).
Tip:  Click the help icon () next to the PFX Enrollment page title to open the Keyfactor Software & Documentation Portal to this section. You will receive a prompt indicating:

You are being redirected to an external website. Would you like to proceed?

You can also find the help icon () at the top of the page next to the Log Out button. From here you can choose to open either the Keyfactor Software & Documentation Portal at the home page or the Keyfactor API Endpoint Utility.

Keyfactor provides two sets of documentation: the On-Premises Documentation Suite and the Managed Services Documentation Suite. Which documentation set is accessed is determined by the Application Settings: On-Prem Documentation setting (see Application Settings: Console Tab).