Major Release 12.0 Notes

June 2024

Please refer to Upgrading Keyfactor Command for important information about the upgrade process. For a complete list of the items included in this release, see Release Note Details v12.0.

Highlights

• Workflow

  • Alerts for expiration, revocation monitoring, and SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. key rotation have been updated to optionally use workflow 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. for delivery the alert and performing additional actions. Instead of using the handlers in alerts for PowerShell scripting, renewal, or event logging, you can handle these functions and more in workflow. The legacy alerting system continues to be supported. See the specific alert pages for information on converting existing alerts to use workflow.

  • Workflows of type Enrollment 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). and Revocation have been updated to allow the operation step (enrollment or revocation) to occur at any point during the workflow rather than just at the end, allowing you to add workflow steps following the completion of the certificate enrollment or revocation. For enrollment, for example, this allows you to send an email alerting users that a certificate has been issued after the enrollment has completed, avoiding the need to configure Issued Certificate Alerts.

  • New workflow types have been added:

    • Certificate Entered Store

      This workflow type is initiated when a certificate has been added to or has entered a certificate store for the specified certificate store type and optional certificate store container.

    • Certificate Left Store

      This workflow type is initiated when a certificate has been removed from or has left a certificate store for the specified certificate store type and optional certificate store container.

    • Expiration

      This workflow type is initiated by an expiration alert and can be used to send email to notify on expiring certificates, renew an expiring certificate, run a PowerShell script, or many other workflow functions.

    • Key Rotation

      This workflow type is initiated by an SSK key rotation alert and can be used to send email to notify on stale SSH keys, run a PowerShell script, or many other workflow functions.

    • Revocation Monitoring

      This workflow type is initiated by a revocation monitoring alert and can be used to send email to notify on expiring CRLs or unreachable OCSP endpoints, run a PowerShell script, or many other workflow functions.

  • A new workflow step type, Renew Expired Certificates, has been added to support automated renewal of certificate from expiration alert workflows.
  • A workflow may now be disabled and enabled with a toggle. When disabled, it will not be initiated.
  • Additional substitutable text tokens have been added for workflows of types Certificate Entered Collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). and Certificate Left Collection: Issued Date, Expiration Date, SANs. For a complete list of tokens available by workflow step, see Substitutable Text Tokens for Workflow in the Keyfactor Command Reference Guide.
  • When publishing a workflow, you now have the option to publish an older version. This allows you to revert to a previous version of a workflow if, for example, an issue is discovered with the currently published version of a workflow.
  • Updates have been made around handling complex field types such as SANs and the metadata 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. data bucket for workflow for ease of use. A new $(sans formatted print) token has been added that provides the SANs in a cleanly formatted string. The original $(sans) token now functions differently in workflow output depending on the configuration of the Use Deprecated Sans Token Parser application setting. When this application setting is set to True, the $(sans) token output is very similar to the $(sansformattedprint) token output, with the SANs in a cleanly formatted string. When this application setting is set to False, the $(sans) token output is a serialized as a JSON string, which supports the use of ConvertFrom-Json -AsHashtable. For upgrades this application setting will be set to True for backward compatibility and for new installs this will be set to False.
  • Workflows of type Certificate Entered Collection and Certificate Left Collection have been updated to provide a warning on save if doing so will trigger the workflow to run multiple times due to pending entered/left certificates. For more information, see Workflow Types in the Keyfactor Command Reference Guide.

• CA Connector Client

  • The CA Connector The Keyfactor CA Connector is installed in the customer environment to provide a connection between a CA and Keyfactor Command when a direct connection is not possible. It is supported on both Windows and Linux and has versions for Microsoft (Windows only) or EJBCA CAs. Client now connects directly to Keyfactor Command, eliminating the need for the Remote CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. Configuration Portal. A new CA Connector API 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. has been added to Keyfactor Command to support this connectivity. The CA Connector API relies on RabbitMQ to communicate with instances of the CA Connector Client, so an implementation of RabbitMQ (https://www.rabbitmq.com) is required in the environment to use this feature. RabbitMQ can be installed in a Linux container. The CA Connector Client requires an OAuth identity provider to support token authentication to Keyfactor Command. This is necessary even if the remainder of your Keyfactor Command implementation is using Active Directory as an identity provider.

  • The Certificate Authorities grid has been updated to add a Connection Type column that indicates whether the CA is configured to use a CA Connector Pool, an Orchestrator, or Neither.

Changes & Improvements

• Dashboard

  • Certificate collections that are configured to display on the dashboard Collection panel may now be sorted. Click the panel Settings icon to edit. For more information, see Dashboard: Collections in the Keyfactor Command Reference Guide.
  • The dashboard Collection panel has the following display changes:
    • Collection names under each bar are slanted 45 degrees.
    • Data labels above bars are formatted to show three significant figures.
    • When highlighting a collection's bar, it shows the name of the collection as well as the exact certificate count.

• Certificate Search and Collections

  • When downloading a certificate in PEM A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. In general, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key. format, there is now an Include Subject Header option, which defaults to enabled, to include the certificate’s subject as the first line of the downloaded file. Toggle this option off to exclude the certificate’s subject from the file.

  • The Only use Alphanumeric Characters application setting now applies to downloads of certificates with private keys from the Certificate Search page as well as downloads of certificates from 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. Enrollment. When this is True, passwords will contain only letters and numbers. When this is False, passwords will contain letters, numbers and special characters.

  • Certificate collections that are configured to display on the top menu may now be sorted. There is a new Navigation Order option in Certificate Collection Management that allows you to designate the order for the collections. On a fresh install, the collections are pre-sorted to alphabetically by the collection's Name. On an upgraded install, the order is pre-populated with all collections that have ShowInNavigator (Favorite) set to true, and the ordering is determined alphabetically by the collection's Name to preserve the order prior to the upgrade.

    Keyfactor API endpoints have been updated to use the new functionality and new Keyfactor API endpoints have been added (see API Change Log v12.0).

    The Show in Navigator button has been removed from the Collection Management grid and additional functionality has been added to the Navigation Order action button.

  • The Collection Manager in the Management Portal has been updated to display the last time the Keyfactor Command Service job that builds the temporary collection from which workflows of types Certificate Entered Collection and Certificate Left Collection draw was processed and the collections' estimated certificate counts. The frequency of this job is not user configurable. Two new fields (EstimatedCertCount and LastEstimated ) have been added to several Keyfactor API endpoints (see API Change Log v12.0).

• Enrollment

  • When downloading a certificate in PEM format in PFX and 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. enrollment, there is now an Include Subject Header option, which defaults to enabled, to include the certificate’s subject as the first line of the downloaded file. Toggle this option off to exclude the certificate’s subject from the file.

  • For PFX enrollment, the Add button has been moved to the bottom of the Subject Alternative Names section for convenience when adding multiple SANs.

  • A new Case-Sensitive Validation option has been added for certificate templates at both the system-wide settings level and the template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. level (in the RegEx 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. details on the Enrollment RegExes tab in both cases). When toggled on, if the user's entry for the subject part does not match the expected case, the value from the Error field will display. This is broken out from the rest of the regular expression 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. for clarity and to allow the case sensitivity setting to be viewed in the regular expression grid.
  • Auto-Select has been added to the Certificate Authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. selection dropdown for PFX and CSR enrollment. When selected, a CA is automatically selected on enrollment from among those that offer the selected template for enrollment. Auto-Select is the default.
  • The download formats for CSR enrollment have been updated to PEM and DER A DER format certificate file is a DER-encoded binary certificate. It contains a single certificate and does not support storage of private keys. It sometimes has an extension of .der but is often seen with .cer or .crt..

  • In CSR enrollment, if a user attempts to use a CSR generated in Keyfactor Command, a warning message appears on enrollment asking the user to confirm that they want to continue. The warning message says:

    It looks like you are using a CSR generated from the Command platform to perform a CSR enrollment. CSRs are intended to be generated where the private key will reside. To generate a PFX, use PFX enrollment. Do you still wish to enroll for this certificate?

    The intended use case for CSR generation in Keyfactor Command is for cases such as an offline CA where it is desired that Keyfactor Command be able to store the 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..

  • The values used to reference types of subject alternative names (SANs) for certificates have been standardized across the product and several values have been deprecated as a result. The following table shows the SAN 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. values that have been deprecated and the related standard values, where applicable:

    Standard Value	Deprecated Value	Description
    dns	dnsname, dns name	DNS Name
    email	mail	Email Address
    ip	ip4, ipaddress	IP v4 Address Note:  IP v4 and IP v6 addresses are handled separately in the Keyfactor Command Management Portal to allow for the application of separate regular expressions on enrollment, but they are stored using the standard ip value.
    ip	ip6	IP v6 Address
    	rfc822	RFC 822 Name
    	ms_ ntprincipal name	MS_ NTPrincipal Name (a string)
    	ms_ ntds replication	MS_ NTDS Replication (a GUID)

• Alerts

  The Test function on the Expiration, Pending Certificate Request, SSH Key Rotation, and Revocation Monitoring Alert pages has been updated to a new format. See the individual operation pages for these alerts for more information.

• Certificate Authorities

  • The Certificate Authorities page has been redesigned to utilize sliding panel functionality and add the new feature functions CA Connectors and Task Queue Connection. Some certificate authority fields have been moved to different tabs and many new features and functionality have been added. See Certificate Authorities.

  • Connections to EJBCA CAs can now be made using OAuth for authentication.

  • Authentication information for CAs can now be stored in the Keyfactor Command secrets table, in a local PAM solution, or in a remote PAM solution for both DCOM and HTTPS type CAs. Specifically, for DCOM CAs, the password set with the Use Explicit Credentials option can be stored in one of these three locations. For HTTPS CAs using OAuth authentication, the Client Secret can be stored in one of these three locations. For HTTPS CAs using client certificate authentication, PAM is not supported.

• Certificate Stores

  • Certificate stores and certificate store containers can now be scheduled for inventory with the following options: Off, Immediate, Interval, Daily, Weekly, Exactly Once. For more information, see Certificate Store Container Operations in the Keyfactor Command Reference Guide.

  • The Container field in the Add/Edit Certificate Store dialog and the Manage Certificate Stores dialog (approving a discovered certificate store) is now a search select rather than a dropdown, removing the previous limit of 50 containers imposed by the dropdown format. Begin typing a value in the field to narrow results.

  • A user may send a Certificate Store Reenrollment job request to a given orchestrator even when there are required metadata fields defined. Although the certificate store reenrollment jobs do not support the entering of metadata fields, the job will continue and will warn the user that they will need to manually fill in the missing metadata fields. Required metadata fields with a default value will be set automatically when the certificate reenrollment job completes.

  • On approving a discovered certificate store, an inventory schedule may now be added to the certificate store in the Manage Certificate Stores dialog from the Discover tab in Certificate Stores. This eliminates the step of needing to first approve the certificate store on the Discover tab and then locate the approved store on the Certificate Stores tab, edit it, and set an inventory schedule for it there.

  • The Discover tab of the Certificate Stores page now includes a search feature.

• Orchestrator Management

  • A new Capabilities tab has been added to the Orchestrator Management details view displaying a list of job types that are correlated to a particular orchestrator's capabilities. The list includes the short name (e.g. RFJKS), the longer name (e.g. RFJKS Inventory), and the job type (e.g. Inventory).

• Keyfactor Universal Orchestrator

  • Logging in the Keyfactor Universal Orchestrator has been updated to return further data from Keyfactor Command as to the state of the job. The new logs have the following format:

    The '[NAME OF JOB]' job with capability '[CAPABILITY]' and Id '[ORCHESTRATOR ID]' under session '[SESSION ID]' completed, sent a '[STATUS]' status and a job completion message of "[JOB COMPLETION MESSAGE]" to the server, received completion status of [JOB COMPLETION STATUS] from the server.

    For example:

    2024-06-13 18:39:01.7347 4B6EC674-1A02-425F-B11B-57355FB8D9E9 550462 Keyfactor.Orchestrators.JobExecutors.OrchestratorJobExecutor [Info] - The 'RFJKS Inventory' job with capability 'CertStores.RFJKS.Inventory' and Id '4b6ec674-1a02-425f-b11b-57355fb8d9e9' under session 'b514334c-7df1-4f92-9d65-bae07ecee376' completed, sent a 'Failure' status and a job completion message of "Site /opt/jks/mystore.jks on server appsrvr162.keyexample.com:Error attempting SCP file transfer from appsrvr162.keyexample.com using login kyfuser and connection method password. Please contact your company's system administrator to verify connection and permission settings. scp: /opt/jks/mystore123.jks: No such file or directory" to the server, received completion status of 'Success' from the server.
  • Configuration for orchestrator client certificate authentication has moved to the appsettings.json file for the web agent services application. This was done because this information is needed to start the web pipeline, so must be available even if SQL is unavailable when the application starts. Related to this, errors indicating a null value is returned for properties UniqueClaimType and FallbackUniqueClaimType in the log have been corrected. As a result of this change, the Always Use Certificate from Header application setting is no longer available in application settings.

• Certificate Metadata

  • Tooltips (help icons) have been added on the certificate metadata definition page add/edit dialog for the hint and description fields to clarify the purposes of these fields. When the hint is displayed on the enrollment and certificate details pages, it now displays in italics within parentheses to the right of the metadata field name. A tooltip has been added to the right of the hint on the enrollment and certificate details pages to display the metadata description.
  • A new Case-Sensitive Validation option has been added for metadata fields of type String. This option is only active when a value has been added in the RegEx Validation field. When toggled on, if the user's entry for the metadata field does not match the expected case, the value from the RegEx Message field will display. This is broken out from the rest of the regular expression for clarity and to allow the case sensitivity setting to be viewed in the regular expression grid.

• Identity Providers

  • OAuth identity providers are now associated with a permission set. In several interface in the Keyfactor Command Management Portal and Keyfactor API where identity providers are referenced, this now needs to be taken into consideration. Identity provider access (for example, availability in dropdowns) is determined by the permissions of the user accessing the Management Portal or Keyfactor API and the permission set on the identity provider(s). The user must be assigned a security role that has been granted the Identity Providers > Read (and Modify for edits) permission and that security role must have the same permission set applied to it as has been applied to the identity provider. For more information about permission sets, see Permission Sets. Identity providers created through the Keyfactor Command Configuration Wizard are associated with the Global permission set.

• Security Roles and Claims

  • On the Security Roles and Claims page, the built-in Administrator role will accept the addition of claims in the Management Portal, though other aspects of this role cannot be edited.

• Logging and Auditing

  • The Keyfactor API correlation token has been added to Keyfactor API response header (X-Keyfactor-Correlation-Id). This correlation ID also now appears in error messages that appear in the Management Portal to aid in tracking requests in the logs.

  • The Keyfactor Universal Orchestrator has been updated to include failure messages in the log even if the orchestrator was able to report the problem back to Keyfactor Command. This will allow for greater troubleshooting and visibility of failures when doing log monitoring on orchestrator logs.

  • The purge audit log job had the following changes:

    • The Purge Audit Job History timer service job will delete records based on a weekly retention period (formerly years).

    • The Purge Audit Job History timer service job will also delete records in batches of a configurable record sizes, set with a new application settings on the Audit tab (Purge Audit Log Batch Size).

    • Persisted categories for audit logs additionally include SecurityClaims, SecurityRoles, and IdentityProviders.

    During an upgrade, the configuration wizard will no longer populate the value of the audit retention period on the Audit Configuration tab to allow users of previous versions to define the week interval of their choice. Configuration files saved after this change will populate with the saved value.

• .NET Updates

  • Release 12.0 has been updated to require the ASP.NET Core 8.0 Hosting Bundle for installation. For more information, see System Requirements.

• Documentation.

  • Keyfactor provides the option of two sets of documentation—the On-Premises Documentation Suite and the Managed Services Documentation Suite—to link to when accessing the documentation from the Keyfactor CommandManagement Portal help links (from the help icon at the top of the Management Portal or from the help icon on individual screens). The Application Settings: On-Prem Documentation application setting (see Application Settings: Console Tab) determines which documentation set is accessed.

Fixes

• An error message of “Cannot read property ‘ServerName’ of undefined” that appeared in some cases when you attempted to Edit Access for select SSH users has been corrected.
• An issue has been corrected where revocation monitoring alerts using the legacy alerting system would send alerts eve if the Email Reminder Warn option was disabled.
• Duplicate log entries created under some conditions during expiration alert generation have been removed.
• CSR enrollment can now handle CSRs with template information encoded as a UTF8 string, such as those generated by Google SCEP.
• One-click renewal is now case insensitive for certificate template and CA forest 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. comparison.
• Keyfactor Command integration with EJBCA CAs now continues to function correctly even if the EJBCA instance has an SSH CA. Keyfactor Command does not support integration with SSH CAs, but now functions correctly with standard CAs in the presence of SSH CAs.

• On the Certificate Stores page, users with limited permissions to certificates can now click the Query Certificate Store button and get a friendly message if they have insufficient permissions to view the associated certificates rather than an unexpected error.

• The SAN type of URI, supported by EJBCA, is now supported by Keyfactor Command to provide parity between the supported SAN types for EJBCA and Keyfactor Command. The supported SAN types in Keyfactor Command have been standardized and include more types than previously. Only a few of the types are available through the Management Portal, but all are available through the Keyfactor API. For more information, see the SANs input parameter A parameter or argument is a value that is passed into a function in an application. to the POST /Enrollment/PFX endpoint An endpoint is a URL that enables the API to gain access to resources on a server. (POST Enrollment PFX) in the Keyfactor API Reference Guide.
• The Keyfactor Command Service job to add certificates that have entered or left a collection to a temporary table to support workflows of types Certificate Entered Collection and Certificate Left Collection has been streamlined to make it more robust in scenarios with a large number of collections and certificates and to only build the temporary table if there are workflows of these types enabled requiring it.

• Certificate requests that require manager approval at the CA level and have SANs now correctly display the SANs on the pending certificate request details and no longer show warning messages in the log similar to:

  [Warn] - Ignoring unknown extension based SAN with value '192.168.9.9'

Deprecation & Removals

• The prescript and postscript functionality of the Keyfactor Universal Orchestrator has been replaced by other functionality in Keyfactor Command such as that provided by Keyfactor Command workflows. As a result, prescript and postscript functionality has been removed.

• Agent Auto-Registration in the Keyfactor Command Management Portal has been deprecated and will be removed in the next major release. Custom auto-registration handlers will still be supported.
• The Test All action for revocation monitoring, expiration, and SSH key rotation alerts has been removed. This was necessary to support the migration to using workflows for these monitoring alerts.
• The following endpoints have been removed from the Keyfactor API: GET /CertificateStores/Server, POST /CertificateStores/Server, PUT /CertificateStores/Server
• Beginning with release 12.0 of Keyfactor Command, Keyfactor product documentation will be published in HTML format only. PDFs versions of the documentation will no longer be published.

• Java Agent

  Important:  The Keyfactor Java Agent has been deprecated as of Keyfactor Command version 12. Customers must migrate to the Keyfactor Universal Orchestrator with the Remote File custom extension publicly available at:

  https://keyfactor.github.io/integrations-catalog/integrations/remote-file-orchestrator

  For more information about using custom extensions with the Keyfactor Universal Orchestrator, see Installing Custom-Built Extensions in the Keyfactor Orchestrators Installation and Configuration Guide.

• Windows Orchestrator

  Important:  The Keyfactor Windows Orchestrator has been deprecated as of Keyfactor Command version 12. Customers must migrate to the Keyfactor Universal Orchestrator, with the appropriate custom extension, publicly available at:

  https://keyfactor.github.io/integrations-catalog/content/orchestrator

  For more information about using custom extensions with the Keyfactor Universal Orchestrator, see Installing Custom-Built Extensions in the Keyfactor Orchestrators Installation and Configuration Guide.

• Mac Auto-Enroll Agent

  Important:  The Keyfactor Mac Auto-Enroll Agent has been deprecated as of Keyfactor Command version 11. Customers needing an auto-enroll solution for Mac should contact their Keyfactor Customer Success Manager.

• Classic API

  Important:  The Classic API, also known as the CMS API, was removed in Keyfactor Command version 11. All uses of the Classic API should be migrated to the Keyfactor API prior to upgrading to Keyfactor Command version 11 or later.

Known Issues

• The Include Chain option for PFX enrollment in the Management Portal and Keyfactor API is not honored when a format of PEM is selected for the certificate. Likewise, the Include Chain option for the Keyfactor API CSR enrollment endpoint is not honored. The latter affects the functionality of the Keyfactor ACME server with newer versions of Certbot that require the full chain to be returned with the response. This will be corrected in a future release.

• On an upgrade, all existing OAuth identity providers are assigned to the Global permission set.

• If an enrollment request through Keyfactor Command fails, the message returned to the user is vague and does not provide guidance on troubleshooting the issue. In the Keyfactor Command Management Portal, the message may look something like:

  Unable to enroll for certificate. Step 'Keyfactor-Enroll' failed: Certificate with ID 165 was not found (Correlation Id: 3a59a640-a7a5-469d-8062-639a12a24961)

  Additional error information may be available in the Keyfactor Command logs. Contact Keyfactor support for assistance and provide them with the correlation ID found in the error.

• If you're planning to use OAuth authentication, you presently must install the Active Directory Module for Windows PowerShell, even though OAuth does not require it, because there is a check for it in the installer. If you don't have it installed, you get the below error during installation.

  Remote Server Administration Tools' Active Directory PowerShell Module is not installed and is required to support the selected web applications. Please install Remote Server Administration Tools and click the 'Retry' button or restart the configuration process.

API Endpoint Change Log

Please review the information in the API Change Log for this release carefully if you have implemented any integration using these endpoints: API Change Log v12.0.