Create Secure Channel Certificate signing requests

This is a procedure for creating certificate signing requests (CSRs) using the SecureChannelCertificateInstaller.ps1 script.

You can use the script to create a Certificate Signing Request (CSR). A CSR contains information needed to create a Certificate Authority (CA) CER file, and gateway and client certificate PFX (and possibly CER) files. You can then send to the appropriate department (such as the IT department) in your organization, and they will use the CSR files to create CA and certificate files. There are separate switches to create gateway and client certificates, but they can be combined into one line, for example:

PS C:\> .\SecureChannelCertificateInstaller -NewGatewayCSR -NewClientCSR -ClientNames "ClientName" [, "ClientName2", etc.] [-Path ".\certificates\requests"] [-Password "StrongPwd#19!84$"] [-GatewayHostNameUpperCase "HostName"] [-GatewayHostFQDN "FQDN"] [-GatewayHostIPAddresses "IPAddress1", "IPAddress2", etc.] [-AppendGatewayHostIPAddresses "IPAddress1", "IPAddress2", etc.] [-AppendGatewayLoopbackHostIPAddress] [-Country "CC"] [-Domain "Domain"] [-Locality "Locale"] [-Organization "Org"] [-OrgUnit "OrgUnit"] [-State "State"]

Here are parameter descriptions and clarifications. For more information on the parameters, see Script Parameters and Configuration File.

• The parameters inside the square brackets are optional. The brackets are not part of the command; don't include them if using the parameter.

• The "ClientName" string arguments refer to the same local client and are identical.

• Path is used to specify the folder for the CSR files. The script always writes the CSR files to a requests sub-folder of that folder. If Path is not specified, the files are written to ".\certificates\requests". The period before the slash starts the path at the folder containing the script, so the default file folder is the certificates folder in the same folder as the script.

• Password is used to specify the password, which the script will prompt for if not supplied. For security purposes, make this a strong password. Record the password securely because it will be used for other operations with these certificate files.

• GatewayHostNameUpperCase, GatewayHostFQDN, GatewayHostIPAddresses, AppendGatewayHostIPAddresses, and AppendGatewayLoopbackHostIPAddress are optional parameters that can be used to change or add to the default information about the gateway computer that is available to the certificates.

• Country, Domain, Locality, Organization, OrgUnit, and State are optional information parameters that are added to the certificate Subject.

There are some common prompts when running the script:

• You will be prompted by PowerShell whether or not to run the script. Type R or r, then Enter to continue.

• If the password isn't included in the script command, you will be prompted for it in PowerShell.

  Both prompts are shown below:

  

This example command will create the .\certificates\requests folder if necessary, and generate the CSR INF and TXT files, a pair for each certificate. After running the example, the contents of the requests folder look like this:

Client1 Studio Database Client.inf

Client1 Studio Database Client.txt

Client2 Studio Database Client.inf

Client2 Studio Database Client.txt

MACHINE1 Client1 Studio Database Gateway.inf

MACHINE1 Client1 Studio Database Gateway.txt

Send these files to the appropriate department in your company (such as the IT department), so that they can supply you with a CA CER file and a PFX file for each gateway and client certificate. They may also supply CER files for each certificate.

If you are using the SecureChannelCertificateInstaller script to install these certificates, the file names should follow this syntax described in Secure Channel Script File Names. If you are using the Microsoft Management Console to install these certificates, the file names don't need to follow this syntax.

Tips and Notes

• Private keys and PFX files may be governed by your organization's security policies. The computer used to generate the CSR includes enough information to generate the private key if you can only get CER files from the CSR. Work with your organization to generate these private keys.

• Along with the CSR files, include a request for the following to be included in the certificates:

  • Client certificates require "Enhanced Key Usage" to include "Client Authentication (1.3.6.1.5.5.7.3.2)". Gateway certificates require "Server Authentication (1.3.6.1.5.5.7.3.1)". The script includes both in every certificate.

  • Gateway certificates require "Enhanced Key Usage" includes "Server Authentication (1.3.6.1.5.5.7.3.2)"

• Certificate expiration duration may be governed by your organization's security policies. Work with your organization to set the expiration duration appropriately.

• Clients running on an IoT View target station require this same file name syntax for the PEM and KEY files if using the install.sh script to install them, see Installing CA and Certificate Files on the IoT View Target Station above for more information.