Run the Secure Channel script

These are instructions for using the SecureChannelCertificateInstaller.ps1 script to create and import certificates for Secure Channel communication.

Running the Script

The Windows PowerShell script named SecureChannelCertificateInstaller.ps1 is used to create and install the certificates required for Secure Channel communication on the gateway host and client computers (which may be the same or different computers). The script is located in one of these places:

• On a computer with the full software installation, the default location is:

  C:\Program Files (x86)\AVEVA\AVEVA Edge2026\Bin\SecureChannelCertificateInstaller.ps1

• When the Studio Database Gateway software is installed on another computer, the default location is:

  C:\Program Files (x86)\Studio Database Gateway 2026\SecureChannelCertificateInstaller.ps1

Run the script by either navigating to its folder or providing the folder path. Even if running PowerShell in the folder containing the script, specify the folder by typing ".\" before the script. See the example below.

Most of the actions performed by the script will work only if Windows PowerShell is run as an administrator. To do this, right-click the PowerShell icon, select Run as administrator in the context menu, and click Yes in the Windows User Account Control dialog.

The basic scripting commands for Secure Channel certificate placement are given below, but the reference Script Parameters and Configuration File has more information on the script parameters and capabilities, including using a JSON file to supply parameter values for the script.

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 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

Tip: If you using the Microsoft Management Console (MMC) to manually import the certificates, see Managing Secure Channel certificates with the Microsoft Management Console for more information.

For more information, see:

• Script Parameters and Configuration File

• Export Certificate Files with Script

• Create Secure Channel Certificate Signing Requests

• Secure Channel Script File Names

• Secure Channel Script Background

Computer Configuration

There are different configurations of gateway host computer and a client computer:

• The gateway and the client reside on the same Windows computer

• The gateway host is one one Windows computer and client applications are on one or more other Windows computers

• The gateway host is on a Windows computer and a client application is on a Linux IoT View target station.

Each configuration requires a different set of steps as described in the following sections.

Tip: These instructions are for using the script to create the certificates. If your company will be creating certificates, see Create Secure Channel Certificate Signing Requests.

Tip: A password is required for every operation of the script, including export. If the password is lost, future certificates created by the script will not be compatible with previously created certificates.

Tip: Certificates have a built-in expiration, measured in days, when created by the script (default value of 365 days). After expiration, the certificates are no longer valid and Secure Channel communication using them will not work. The certificates can be replaced by running the same script commands used to create and install them initially. The password used during the initial creation and installation of the certificates is required to create new compatible certificates.This also applies to the CA certificate. When the CA certificate expires, create all certificates again. The Force parameter does not create a new CA certificate.

Common PowerShell and Windows Prompts

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:

  

• For each gateway and client certificate you create, you will be prompted by a Windows Security dialog. Click OK each time to continue.

  

• You will be prompted trust the certificates when installing them. Click Yes to continue.

  

Gateway and Client on the Same Computer

If the Studio Database Gateway and the client application are on the same computer, follow these steps:

1. On the gateway host computer, run Windows PowerShell as an administrator.

2. Run the following command on the gateway host computer (which is the same as the client computer) to create gateway and client certificates and import them to the correct Windows certificate stores:

   PS C:\> .\SecureChannelCertificateInstaller -NewGatewayCertificate -InstallCertificatesOnGateway -GatewayHostIPAddresses "127.0.0.1" -NewClientCertificate -ClientNames "ClientName" -InstallCertificatesOnClient "ClientName" [-Path "PathName"] [-Password "StrongPwd#19!84$"] [-ExpirationDays 365] [-GatewayUserAcct "Domain\GatewayUserAcctName"] [-ClientUserAcct "Domain\ClientAccountName"] [-ClientServiceName "ClientServiceName"] [-Force]

   Notes:

   • The parameters inside the square brackets are optional. The brackets are not part of the command; do not 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 path name for the certificate files. If not specified, it defaults to ".\certificates". 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.

     Tip: If you are creating new certificates that are meant to be compatible with previously created certificates, use Path to specify the folder containing the previously created certificate files.

   • 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.

   • ExpirationDays is used to specify the number of days until the certificate expires.

   • GatewayUserAcct is used to specify a different Windows account on the same computer on which the Studio Database Gateway is run.

   • ClientUserAcct is used to specify a different Windows account on the same computer on which the client application is run.

   • ClientServiceName is used to specify the name of a client that is run as a Windows service.

   • Force is used to remove previous versions of these certificates and replace them with new versions, possibly to replace expired certificates. (Currently Force cannot be used with ClientServiceName.)

3. If last line before the prompt in PowerShell is "Import execution complete.", the certificates have been imported to the correct certificate stores.

4. This procedure is finished.

   Tip: Backup and/or safely store the files created in the Path folder (default to ".\certificates"). They will be needed to create more certificates that are compatible with these certificates. You may be creating more certificates to add clients or to replace expired certificates.

   Tip: You can create new client certificates compatible with the previously created gateway and client certificates by running the command without the parameters that have "gateway" in the name, using the previously created certificate files (using Path to specify the file location) and the password used to create the previous certificates.

Client Computer is a Separate Windows Computer

If the Studio Database Gateway and the client application are on different Windows computers, follow these steps:

5. On the gateway host computer, run Windows PowerShell as an administrator.

6. Run this command on the gateway host computer to create and import certificates on the gateway computer, and to create certificates files to be copied to the client computer:

   PS C:\> .\SecureChannelCertificateInstaller -NewGatewayCertificate -NewClientCertificate -ClientNames "ClientName1", "ClientName2" -InstallCertificatesOnGateway [-Path "PathName"] [-Password "StrongPwd#19!84$"] [-ExpirationDays 365] [-GatewayUserAcct "Domain\GatewayUserAcctName"] [-Force] [-InstallCertificatesOnClient "ClientName1"] [-ClientUserAcct "Domain\ClientAccountName"] [-ClientServiceName "ClientServiceName"]

   Notes:

   • See previous section, Gateway and Client on the Same Computer for notes on the parameters.

   • The optional parameters InstallCertificatesOnClient, ClientUserAcct, and ClientServiceName are used to install the client certificates if one of the clients, in this example ClientName1, is on the gateway host computer.

   Tip: Backup and/or safely store the files created in the Path folder (default to ".\certificates"). They will be needed to create more certificates that are compatible with these certificates. You may be creating more certificates to add clients or to replace expired certificates.

   Tip: You can create new client certificates compatible with the previously created gateway and client certificates by running the command without the parameters that have "gateway" in the name, using the previously created certificate files (using Path to specify the file location) and the password used to create the previous certificates.

7. If one of the clients, for example ClientName2, is on the a different computer than the gateway host computer, copy the all of the certificate files from the gateway host computer to the client computer. The files are in the folder on the gateway host computer specified using the Path parameter or in the default .\certificates folder.

8. On the client computer, run Windows PowerShell. You do not need to run PowerShell as an administrator unless using ClientServiceName to install certificates for a service.

9. On the client computer, run this command:

   PS C:\> .\SecureChannelCertificateInstaller -InstallCertificatesOnClient "ClientName2" [-ClientUserAcct "Domain\ClientAccountName"] [-ClientServiceName "ClientServiceName"] [-Path "PathName"] [-Password "StrongPwd#19!84$"] [-ExpirationDays 365] [-GatewayUserAcct "Domain\GatewayUserAcctName"] [-Force]

   Notes:

   • See previous section, Gateway and Client on the Same Computer for notes on the parameters.

   • The password is the same password used in the previous step (creating and installing on the gateway host computer).

   Tip: Backup and/or safely store the files created in the Path folder (default to ".\certificates"). They will be needed to create more certificates that are compatible with these certificates. You may be creating more certificates to add clients or to replace expired certificates.

   Tip: You can create new client certificates compatible with the previously created gateway and client certificates by running the command without the parameters that have "gateway" in the name, using the previously created certificate files (using Path to specify the file location) and the password used to create the previous certificates.

10. If last line before the prompt in PowerShell is "Import execution complete.", the certificates have been imported to the correct certificate stores.

11. For security purposes, delete the copies of the certificate files from the client computer. The copies of the certificate files on the gateway host computer should be stored safely as noted above.

12. This procedure is finished.

Client Computer is a Linux IoT View Target Station

If the client is on a Linux IoT View target station, follow these steps:

13. On the gateway host computer, run Windows PowerShell as an administrator.

14. Run this command on the gateway host computer to create and import certificates on the gateway computer, and to create certificates files to be copied to the client computer:

    PS C:\> .\SecureChannelCertificateInstaller -NewGatewayCertificate -NewClientCertificate -ClientNames "ClientName1", "ClientName2" -InstallCertificatesOnGateway [-Path "PathName"] [-Password "StrongPwd#19!84$"] [-ExpirationDays 365] [-GatewayUserAcct "Domain\GatewayUserAcctName"] [-Force] [-InstallCertificatesOnClient "ClientName1"] [-ClientUserAcct "Domain\ClientAccountName"] [-ClientServiceName "ClientServiceName"]

    Notes:

    • See previous section, Gateway and Client on the Same Computer for notes on the parameters.

    • The optional parameters InstallCertificatesOnClient, ClientUserAcct, and ClientServiceName are used to install the client certificates if one of the clients, in this example ClientName1, is on the gateway host computer.

    Tip: Backup and/or safely store the files created in the Path folder (default to ".\certificates"). They will be needed to create more certificates that are compatible with these certificates. You may be creating more certificates to add clients or to replace expired certificates.

    Tip: You can create new client certificates compatible with the previously created gateway and client certificates by running the command without the parameters that have "gateway" in the name, using the previously created certificate files (using Path to specify the file location) and the password used to create the previous certificates.

15. If one of the clients, for example ClientName2, is on the a Linux IoT View target station, copy the all of the certificate files from the gateway host computer to the client computer. The files are in the folder on the gateway host computer specified using the Path parameter or in the default .\certificates folder.

16. In the IoT View target station runtime directory, using sudo, run install.sh followed by the -s switch, and the path to the client KEY file in quotes, for example:

    $ sudo ./install.sh -s "certificates/Client2 Studio Database Client_CC1727A4663763D3FEBDD486B9F44706A7EF4307_52B0188BBD56D07475B29FE30C4017AF4A7D9052.key"

17. For security purposes, delete the copies of the certificate files from the client computer. The copies of the certificate files on the gateway host computer should be stored safely as noted above.

18. This procedure is finished.