Installing the Keyfactor CA Policy Module Handlers

These steps only need to be completed if your Keyfactor Command license includes the Keyfactor CAClosed 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. Policy Module and you plan to use this feature and one or more of its policy handlers. Review the policy handlers to determine if one or more of them meets a need in your environment.

Important:  For a CA Clustered solution, if the Keyfactor CA Policy Module is installed on a node then configured, then failed over to another node, this will corrupt the check point key. The module must be installed on BOTH nodes, configured on one node, then failed over to the other node.

The available policy handlers are:

Automate inclusion of a DNSClosed The Domain Name System is a service that translates names into IP addresses. 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. 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). of the requested certificate in certificate enrollments for a defined set of CA templates.

Allow the addition of SANs not included in the 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. when making a CSR 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). request. The added SANs will overwrite any existing SANs in the CSR. This functionality is the same as that seen with the Microsoft default policy module for the CA as a whole when the CA EDITF_ATTRIBUTESUBJECTALTNAME2 flag is set except the SAN Attribute Policy Handler provides the ability to control SAN addition on a templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received.-by-template basis without the need to enable the Microsoft CA EDITF_ATTRIBUTESUBJECTALTNAME2 flag.

Important:  By default, Microsoft CAs do not support the addition of SANs not included in the CSR when making a request using a CSR enrollment method. To enable your CA to support requesting certificates with additional SANs, you must either install and configure the Keyfactor Command SAN Attribute Policy Handler on the CA(s) or enable the Microsoft CA EDITF_ATTRIBUTESUBJECTALTNAME2 flag. There are security risks inherent in enabling either of these options on your CA. Keyfactor recommends that you do not enable these options unless it is an absolute requirement. With the SAN Attribute Policy Handler, you can limit the risk by limiting the exposure to just selected templates. Keyfactor further recommends that you:
  • Use the SAN Attribute Policy Handler only with templates that require CA manager approval so that a manager will be required to review the request and the added SANs before the certificate is issued.
  • Use the SAN Attribute Policy Handler in conjunction with the Whitelist Policy Handler to limit requests for the selected templates to being initiated only by the Keyfactor Command server(s).
  • Configure server level monitoring with a product such as Microsoft’s System Center Operations Manager (SCOM) to provide alerts for any changes relating to the CA(s) configured with the SAN Attribute Policy Handler so that, for example, changes to the templates configured to support SAN addition do not go unnoticed.

Allow secure control of on-device key generation during certificate enrollment for iOS and Mac devices.

Enforce that certificate requests for a given template or templates can only be initiated from a given computer or set of computers.

Note:  The following Windows update affects how certificate requests are built when sent to a Microsoft CA and may cause enrollments done outside Keyfactor Command against a Microsoft CA configured with the Whitelist Policy Handler to fail.
https://support.microsoft.com/en-us/topic/kb5014754-certificate-based-authentication-changes-on-windows-domain-controllers-ad2c23b0-15d8-4340-a468-4d4f3b188f16

The processing order of the handlers currently available in the Keyfactor CA Policy Module, when used together on the same machine, is significant for some handlers and not others. Specifically, the processing order is not significant for the vSCEP™ Policy Handler and Machine Whitelist Policy handler. These handlers may be placed anywhere within the list of handlers. However, the processing order does matter for the SAN Attribute Policy Handler and the RFC 2818 Policy Handler. When these two handlers are used together, the SAN Attribute Policy Handler must be placed on the list above the RFC 2818 Policy Handler to allow the SAN Attribute Policy Handler to be processed before the RFC 2818 Policy Handler. This is because the SAN Attribute Policy Handler removes any existing SANs on the enrollment request and replaces them with those specified in the request outside of the CSR—such as those entered in the optional SAN section on the CSR page of the Keyfactor Command Management Portal. This includes any SANs added by the RFC 2818 Policy Handler.

Figure 496: Keyfactor CA Policy Module Policy Module Handler Ordering

When the Keyfactor CA Policy Module is used, the policy module listed on the Default Policy tab of the Policy Module Configuration Properties dialog is run first when a request reaches the CA. This default policy might be the standard Windows default, as shown Figure 497: Default Policy Module, or it might be another non-built-in policy module, such as the Microsoft FIM CM Policy Module. After the default policy module runs, the Loaded Handlers on the Custom Handlers tab of the Policy Module Configuration Properties dialog are run in the order listed (top to bottom). After all the handlers have been run, the result (approved, denied, or marked as pending) is returned to the CA for processing.

Figure 497: Default Policy Module

Tip:  Once the installation is complete, the configuration options for the policy handlers can be found in the registry on the CA in the following paths (where CA_LOGICAL_NAME is the logical nameClosed The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two). of the local CA):
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\CertSvc\Configuration\CA_LOGICAL_NAME\PolicyModules\CMS_Custom.Policy\PolicyHandlers\RFC2818.PolicyHandler
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\CertSvc\Configuration\CA_LOGICAL_NAME\PolicyModules\CMS_Custom.Policy\PolicyHandlers\SANAttribute.PolicyHandler
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\CertSvc\Configuration\CA_LOGICAL_NAME\PolicyModules\CMS_Custom.Policy\PolicyHandlers\vSCEP.PolicyHandler
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\CertSvc\Configuration\CA_LOGICAL_NAME\PolicyModules\CMS_Custom.Policy\PolicyHandlers\CMSWhitelist.PolicyHandler
Warning:  These registry keys should not be modified without advice from Keyfactor support.