Script parameters and configuration file

This is a parameter reference for the Secure Channel certificate management SecureChannelCertificateInstaller.ps1 script.

Script parameters

The parameters for the SecureChannelCertificateInstaller.ps1 script are listed below. Multiple parameters may be combined.

Tip: Using quotes around string values isn't required by PowerShell, but it is good practice to avoid certain errors, so the examples will use quotes around string values. If you use strings that contain spaces, the spaces will be read as a break between different items unless the entire string is enclosed in quotes. For example, Client 1 is two different items which may be interpreted as two different strings, and "Client 1" is one string.

Tip: You can access help for the script by typing this command at the PowerShell prompt, for example (if already in the same directory as the script): PS C:\> get-help .\SecureChannelCertificateInstaller.ps1 -detailed

-AppendGatewayHostIPAddresses "strIpAddress1", "strIpAddress2", etc.

This parameter is used to specify a list of comma-separated IP addresses of the gateway computer that will be added to the default list of local computer IPv4 addresses. This list of IP addresses will be available to the certificates to validate communication with the Studio Database Gateway.

The default local IPv4 addresses may be found by using the ipconfig command in a Windows command line interface (cmd.exe or PowerShell).

Use GatewayHostIPAddresses to create a list of IPAddresses that doesn't include the local computer IPv4 addresses. Use AppendGatewayLoopbackHostIPAddress to add only the loopback IP address (127.0.0.1) to the default list of local computer IPv4 addresses. If none of these three parameters are used, the local computer IPv4 addresses will be used by default.

-AppendGatewayLoopbackHostIPAddress

This parameter is used to add the loopback IP address (127.0.0.1) to the default list of local computer IPv4 addresses. This list of IP addresses will be available to the certificates to validate communication with the Studio Database Gateway.

The default local IPv4 addresses may be found by using the ipconfig command in a Windows command line interface (cmd.exe or PowerShell).

Use GatewayHostIPAddresses to create a list of IPAddresses that doesn't include the local computer IPv4 addresses. Use AppendGatewayHostIPAddresses to add IP addresses to the default list list of local computer IPv4 addresses. If none of these three parameters are used, the local computer IPv4 addresses will be used by default.

-ClientNames "strClient1", "strClient2", etc.

This parameter is used to specify a list of comma-separated client certificate names. The comma-separated list may have spaces after the commas, but this isn't necessary. If the client names contain spaces, the quotes are required. This parameter is used with the NewClientCertificate and NewClientCSR parameters.

-ClientServiceName "strServiceName"

This parameter is used with the InstallCertificatesOnClient parameter to install client certificates to the certificate store of a service on the client computer. strServiceName is the Windows service name, which you can find by looking at the properties of the service in services.msc.

-ClientUserAcct "strDomain\strAccountName"

This parameter is used with the InstallCertificatesOnClient parameter to install client certificates to the certificate store of on an account on the client computer that is different from the one you are using. Its use requires that you have privileges to access this other account (such as administrator privileges) and a password to access it. An example of the string argument is "MACHINE2\Service Acct". The "\" is mandatory and the quotes allows the space to used in the string in this example.

-ConfigPath "strFilePathAndName"

This parameter specifies a text configuration file that can contain the string arguments of the following parameters in JSON format, rather than specifying them on the command line: ClientNames, Country, Domain, GatewayHostFQDN, GatewayHostIPAddresses, GatewayHostNameUpperCase, Locality, Organization, OrgUnit, Path, and State.

The mandatory string argument is the file name and the path to the file, for example ".\CertConfig.txt" . See Certificate Configuration File below for more information.

-Country "strCC"

This optional information parameter is used to add optional country information to the certificate subject using an ISO format country code. Most country codes are two characters long, and incorrect codes can result in an error in a CSR. You can look up ISO format country codes online. Example: -Country "US"

-Domain "strDomainName"

This optional information parameter is used to specify the Domain information for the certificate subject.

-ExpirationDays intNumDays

This optional parameter is used to specify the number days until the certificate expires when creating a new certificate or CSR, expressed as an integer argument. If not explicitly defined, the default value of 365 is used.

-ExportCertificates

This parameter is used to export all certificate pem, key, and pfx files, and zip file archive of these three files, to the folder specified in the Path parameter. If no folder is specified by the Path parameter, the default .\certificates is used; the folder will be created if it doesn't already exist.

If files with the same name already exist in the correct folder, they will not be overwritten unless the Force parameter is added to the command.

-Force

This parameter is used with InstallCertificatesOnClient, InstallCertificatesOnGateway, and ExportCertificates to overwrite certificates or files with the same name, so that the new certificates or files will be installed or generated. One use of this parameter is to replace expired or soon-to-expire certificates. Force is not currently supported with ClientServiceName.

-GatewayHostFQDN "strFQDN"

This parameter is used to specify the fully qualified domain name (FQDN) of the gateway computer for the certificate Subject Alternative Names (SAN) list. If this parameter isn't specified, the local computer FQDN will be used.

-GatewayHostIPAddresses "strIpAddress1", "strIpAddress2", etc.

This parameter is used to specify a list of comma-separated IP addresses of the gateway computer added to the certificates' Subject Alternative Names (SAN) list. You may leave spaces between the IP addresses and the quotes are optional. This list of IP addresses will be available to the certificates to validate communication with the Studio Database Gateway.

The default local IPv4 addresses may be found by using the ipconfig command in a Windows command line interface (cmd.exe or PowerShell).

Use AppendGatewayHostIPAddresses to add IP addresses to the default list list of local computer IPv4 addresses. Use AppendGatewayLoopbackHostIPAddress to add only the loopback IP address (127.0.0.1) to the default list of local computer IPv4 addresses. If none of these three parameters are used, the local computer IPv4 addresses will be used by default.

-GatewayHostNameUpperCase "strHostname"

This optional parameter is used to specify the host name of the gateway computer. The computer host name can be determined by using the hostname command in a Windows command line interface (cmd.exe or PowerShell).

If this parameter is not specified, the script will use the local computer host name. You don't need to capitalize the host name; it will be converted automatically.

-GatewayUserAcct "strDomain\strAccountName"

This parameter specifies the user account name that will be used to run the Studio Database Gateway on the gateway computer, for example "MACHINE1\Default User". The "\" is mandatory and the quotes allows the space to used in the string in this example. If this parameter is not specified, the default value is the current user account.

-InstallCertificatesOnClient "strClientCertificateName"

This parameter is used to import client certificates to the correct certificate stores on the client computer. The string argument is mandatory; it specifies the client certificate name. The string argument can be empty; this is done to install the gateway certificate on the client machine (the script requires an empty string to be explicitly declared by typing "").

-InstallCertificatesOnGateway

This parameter is used to install gateway certificates to the correct certificate stores on the gateway computer. It doesn't require additional arguments, but works with other parameters.

-Locality "strLocalityName"

This optional information parameter uses the string argument to specify the Locality information, for example a city, for the certificate subject.

-NewClientCertificate

This parameter is used to create one or more new client certificates and files. The ClientNames parameter is required to specify the client certificate and file names.

The created files will be copied to the folder specified using the Path parameter, defaulting to ".\certificates". The specified or default folder will be created by the script if it doesn't already exist. The Force parameter can be added to the command to remove old certificates and create new ones.

-NewClientCSR

This parameter is used to create a Certificate Signing Request (CSR) for one or more client certificate files. The CSR is sent to the appropriate department in your company to give them the information necessary to create the client certificate files. The ClientNames parameter must be used to name the client name or names. The Path parameter may be used; if not the CSR files are created in the ".\certificates\requests" folder (the folder will be created if it doesn't already exist).

The CSR consists of two files created in the destination folder (specified by Path or the default), an INF file and a TXT file, both with the same file name with the syntax <client name> Studio Database Client, for example Client1 Studio Database Client.inf and Client1 Studio Database Client.txt. Both of these files should be sent to the appropriate department in your company.

-NewGatewayCertificate

This parameter is used to create a new gateway certificate and file.

The created files will be copied to the folder specified using the Path parameter, defaulting to ".\certificates". The specified or default folder will be created by the script if it doesn't already exist. The Force parameter can be added to the command to remove old certificates and create new ones.

-NewGatewayCSR

This parameter is used to create a Certificate Signing Request (CSR) for a gateway certificate file. The CSR is sent to the appropriate department in your company to give them the information necessary to create the gateway certificate file.The Path parameter may be used; if not the CSR files are created in the ".\certificates\requests" folder (the folder will be created if it doesn't already exist).

The CSR consists of two files created in the destination folder (specified by Path or the default), an INF file and a TXT file, both with the same file name with the syntax <gateway host name> Studio Database Gateway, for example MACHINE1 Studio Database Gateway.inf and MACHINE1 Studio Database Gateway.txt. Both of these files should be sent to the appropriate department in your company.

-Organization "strOrganizationName"

This optional information parameter uses the string argument to specify the Organization information for the certificate subject.

-OrgUnit "strOrgUnitName"

This optional information parameter uses the string argument to specify the OrgUnit information for the certificate subject.

-Password "strPassword"

This parameter is used to provide the password used to access the certificate private key. Record this password in a secure place.

Tip: If this password is lost, no further certificates can be created or imported with the private key. In this case, create new certificates and start over.

-Path "strFileLocation"

This parameter is used to specify the directory where the certificates files will be exported to or imported from. The required string argument is the file path, for example ".\certificates". If the Path parameter is not used, the default ".\certificates" folder is used. (An empty string "" will also default to the ".\certificates" folder.)

-State "strStateName"

This optional information parameter uses the string argument to specify the State information for the certificate subject.

-Verbose

When this parameter is included, the script displays all messages in detail in PowerShell.

Certificate Configuration File

You can use a JSON text file to specify several of the script parameters and reference that script using the ConfigPath parameter. The file can contain the string arguments for these parameters rather than specifying them on the command line: ClientNames, Country, Domain, GatewayHostFQDN, GatewayHostIPAddresses, GatewayHostNameUpperCase, Locality, Organization, OrgUnit, Path, and State. The file is a text file that uses JSON formatting. Here is an example command, followed by the referenced file that contains the information:

PS C:\> .\SecureChannelCertificateInstaller -Password "StrongPwd#19!84$" -NewGatewayCertificate -NewClientCertificate -ConfigPath ".\certConfig.txt"

File CertConfig.txt in the same folder as the script:

{

"Common":{

"Path":"c:\\certificates"

"Domain" : "Domain",

"Organization" : "Organization",

"Country" : "CC",

"State" : "State",

"Locality" : "Locality",

"OrgUnit" : "Organizational Unit"

},

"Gateway":{

"GatewayHostNameUpperCase":"MACHINE1",

"GatewayHostFQDN":"MACHINE1.DOMAIN.COM",

"GatewayHostIPAddresses":[

{"IPAddress": "10.0.0.1"},

{"IPAddress": "127.0.0.1"}

],

"GatewayUserAcct":"",

},

"Client":[

{"ClientName":"Client1"},

{"ClientName":"Client2"}

]

}

GatewayUserAcct is a command-line parameter. It is not read from the configuration file.