Contents

• Overview
• Creating the Tunnel
• Advanced SSL Settings

Overview

SSL Tunnels can be used to upgrade legacy connections so that they are secured with TLS 1.2. In most cases, this can be accomplished by creating a basic SSL tunnel that connects to the legacy machine. SSL Tunnels negotiate SSL for incoming and outgoing connections separately, so no additional configuration is required to support older SSL protocols (TLS 1.0, TLS 1.1) in one direction and modern SSL protocols (TLS 1.2) in the other.

The second half of this article covers more advanced SSL configuration options. These configuration options are only necessary when the legacy system requires SSL protocols older than TLS 1.0.

The SSL tunnel itself acts as a proxy for the legacy machine. The tunnel connects to the legacy machine (usually within a protected network) using an older SSL protocol, and exposes connections to the outside world using TLS 1.2. For the purposes of this article, the SSL tunnel will create outgoing connections to the legacy machine and accept incoming connections over TLS 1.2.

Creating the Tunnel

To begin creating the tunnel, first navigate to the Tunnels tab of the PowerShellServer UI to view the list of configured tunnels:

Select the Add... button to bring up the Add Tunnel form:

From the Tunnel Type dropdown menu, select SSL Tunnel to bring up the SSL Tunnel form, and fill out the form as described below:

• Enabled should be checked to set the Tunnel as active
• Tunnel Name should be set to a friendly name for the tunnel
• Listening Port should be set to the port that will accept incoming connections over TLS 1.2
• Secure Server should be enabled so that incoming connections are secure
• Certificate should be set to the SSL certificate with a private key that will be used as the host certificate
• Forwarding Host should be set to the legacy machine
• Forwarding Port should be set to the expected port on the legacy machine
• SSL Connection should be enabled so that the outgoing connection is SSL-enabled
• Server Certificate can optionally be set to the public certificate of the legacy machine
• Accept Any Server Certificate should be enabled if Server Certificate is not set

The Test Connection button can be used to verify the outgoing connection to the legacy machine. During a connection test, the tunnel may prompt to dynamically accept the legacy machine's public certificate 'on the fly'. This will only occur if the legacy machine's public certificate has not been specified, Accept Any Server Certificate is disabled, and the certificate is not automatically trusted by the system.

After filling out the form and testing the outgoing connection, select OK and save your settings. Once PowerShellServer is started, TLS 1.2 connections can be made to Listening Port on the machine where PowerShellServer is running to securely access the legacy machine.

Configuring Advanced SSL Settings via the Registry

This section describes the process for modifying the registry to select the particular SSL protocols used in either incoming or outgoing connections. In most cases this is only necessary if the legacy machine requires SSL protocols older than TLS 1.0.

To configure the specific SSL settings for incoming or outgoing connections, first navigate to the following location in the registry:

Computer\HKEY_LOCAL_MACHINE\SOFTWARE software\PowerShell\Server\16\SSLTunnels

Expand this registry key and select the tunnel created in the steps above.

The registry value TunnelForwardingSSLEnabledProtocols governs the SSL protocols used when establishing outgoing connections. For the current setup, this value will need to be set to the SSL protocol that the legacy machine is expecting. By default, TLS 1.0, TLS 1.1, and TLS 1.2 are enabled; thus, modifying this value is only necessary when connecting to a legacy machine that requires SSL 3.0 and older.

Create a new DWORD value called TunnelForwardingSSLEnabledProtocols (or modify this value if it already exists). For the purposes of this example, this value should be set to 0x30 (48 in decimal), the value for SSL 3.0. This will force the tunnel to only negotiate SSL 3.0 for outgoing connections.

The registry value SSLTunnelEnabledProtocols governs the SSL protocols used when accepting incoming connections. To restrict this to only use TLS 1.2, add (or modify) the DWORD value SSLTunnelEnabledProtocols and set that value to 0xC00 (3072 in decimal).

Now the tunnel is fully configured. The Test Connection button on the Edit Tunnel form can be used to verify that the SSL 3.0 connection to the legacy machine is working correctly. After confirming, restart PowerShellServer and begin establishing TLS 1.2 connections.