PowerShell Cmdlets for Configuration

This cmdlet is used to create a self-signed encryption certificate in your local computer's personal store and set permissions on the certificate. If there is an exiting certificate, the Set-KeyfactorGatewayEncryptionCert cmdlet will retrieve it and will not create a new one. This certificate is used to encrypt the connection string the AnyCAGateway DCOM uses to connect to the 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.. This is important for third party CAs that rely on a username and password for authentication, for instance, to keep that information secure.

This command identifies an existing certificate, if available in the local machine store, or generates a new certificate, places it in the local machine store, and updates the following registry setting with the serial number of the certificate:

The Set-KeyfactorGatewayEncryptionCert cmdlet does not have any parameters.

This cmdlet configures the connection string the AnyCAGateway DCOM will use to communicate with your SQL database. The connection parameters passed to the command are the SQL server name and the AnyCAGateway DCOM database name. If you are using SQL authentication, the account parameter A parameter or argument is a value that is passed into a function in an application. should be passed as well to provide SQL credentials.

The connection string is encrypted and saved to the registry in the following location:

The parameters for the cmdlet are shown in the following table.

Table 923: Set-KeyfactorGatewayDatabaseConnection cmdlet Parameters

Parameter	Definition
-Server	The host name of the database server. This parameter is required.
-Database	The name of the database created for the AnyCAGateway DCOM. This parameter is required.
-Account	The -Account parameter is required if you are using SQL authentication. Tip:  To use this parameter, first run the Get-Credential PowerShell command with output to an $account variable: $account = Get-Credential When prompted, enter the username and password to authenticate to SQL. Then reference the $account variable with the -Account parameter as part of your Set-KeyfactorGatewayDatabaseConnection command: -Account $account
-ConnectionStringTemplate	A custom connection string to connect to the SQL server. This is used in place of the default connection string and makes use of the -Server, -Database, and -Account parameters. It is supported for SQL and Windows authentication.

This cmdlet will either generate a default configuration file (for a new installation of the AnyCAGateway DCOM), export your existing configuration from SQL (to allow you to review or modify it), or retrieve your exported registry (if you are upgrading from an older version of the gateway).

The parameters for the cmdlet are shown in the following table.

Table 924: Get-KeyfactorGatewayConfig cmdlet Parameters

Parameter	Definition
-CAHostname	The FQDN of the gateway. For example: CA24.keyexample.com. This parameter is required.
-LogicalName	The CA LogicalName. For example: CAGateway This name is used when retrieving existing gateway configuration from the SQL database. The logical name must be unique for each CA.
-FilePath	The path and full name of the JSON configuration file. For example: C:\AnygatewayConfig.json. This parameter is required.

This cmdlet saves the settings in the JSON configuration file to the gateway database, as per the parameters submitted with the command. This option is used both for the initial configuration of the database to import the initial configuration file and for any future updates that need to be made to the configuration.

The parameters for the cmdlet are shown in the following table.

Table 925: Set-KeyfactorGatewayConfig cmdlet Parameters

Parameter	Definition
-CAHostname	The FQDN of the gateway. For example: CA24.keyexample.com. This parameter is required.
-LogicalName	The CA LogicalName. For example: CAGateway. This name will be used when referencing the third party gateway from Keyfactor Command and, optionally, registering the gateway as an enrollment services object in Active Directory to make it discoverable as a CA in the environment. The logical name must be unique for each CA.
-FilePath	The path and full name for the JSON configuration file. For example: C:\AnygatewayConfig.json. This parameter is required.
-PublishAD	This parameter is optional for private and public CAs. The purpose of this parameter is to register the CA in Active Directory (AD) for easy import to Keyfactor Command and/or to see all CAs registered in AD. Note:  Publishing CA Gateways to Active Directory is for management and operational convenience and does not impact the operation of the gateway itself. Publishing a gateway in AD enables easy import of the gateway into Keyfactor Command and also enables operating system tools such as the IIS "Request new domain certificate" to leverage a gateway. The -PublishAD parameter adds a configuration record to AD. The update is made to (where xxx are values that correspond to each level of the forest name): CN=Enrollment Services, CN=Public Key Services, CN=Services, CN=Configuration, DC=xxx, DC=xxx For example, the forest keyexample.com would have DC values of: DC=keyexample, DC=com During an upgrade, or if modifying a configuration, if no change in AD status is desired, then do not provide any parameter and no change will be made.
-UnpublishAD	This parameter is optional for private and public CAs. The purpose of this parameter is to unregister the CA from Active Directory (AD) and remove the configuration record from AD. The update is made to ( where xxx are values that correspond to each level of the forest name): CN=Enrollment Services, CN=Public Key Services, CN=Services, CN=Configuration, DC=xxx, DC=xxx For example, the forest keyexample.com would have DC values of: DC=keyexample, DC=com If you choose not to publish the gateway CA in AD, you must manually add the gateway CA in Keyfactor Command. See Add the AnyCAGateway DCOM CA to Keyfactor Command for instructions.