4.5.3 Connecting With TCP/IP Over SSH

SSH tunneling (or port forwarding) enables you to create a secure connection between your computer and a remote computer through which you can access MySQL data. SSH tunnels permit you to connect to a MySQL database from behind a firewall when the MySQL server port is blocked.

There are several considerations for connecting with standard TCP/IP over SSH:

• Your application (client to make the connection) requires authorization on the SSH server.

• The SSH server communicates with a MySQL server instance in an unencrypted or encrypted mode, based on the value selected for the SslMode connection option (or property). The default value of the option can vary, depending on the version of Connector/NET you use (see Options for Both Classic MySQL Protocol and X Protocol). The MySQL server instance does not require additional configuration for this type of connection.

• The ConnectionProtocol connection option (or property) must use the default value (socket or tcp) to establish a connection with standard TCP/IP over SSH.

• The SSH server name and port are configured using the SshHostName and SshPort connection options (or properties). To authenticate the client requesting a connection (specified by the SshUserName connection option or property), you can use one of the following strategies:

  • SshUserName and SshPassword only

  • SshUserName and SshKeyFile only

    Your SSH server may require that you to also provide the SshPassPhrase connection option (or property) when using a key file. An invalid pass phrase generates an exception.

  • SshUserName and SshKeyFile (SshPassPhrase) and SshPassword

    The combination of user name + key file (pass phrase) + password can perform fallback authentication when the key file and pass phrase are valid, but an error occurs on the server. Specifically, the first attempt to connect uses the key file, and if it fails, the next attempt to connect uses the password instead. If the SSH key file is null or empty, but the SSH password is provided, Connector/NET attempts to connect using the SSH password only.

You can configure SSH tunneling by using either Connector/NET 8.0.17 (or higher) connection-string options or class properties: the MySqlConnectionStringBuilder class for use with the classic MySQL protocol or the MySqlXConnectionStringBuilder class for X Protocol. SSH tunnels to MySQL are supported with .NET Framework 4.5.2, .NET Standard 1.3 (.NET Core 1.1), and .NET Standard 2.2 (.NET Core 2.0).

The examples in the next sections show connections made using standard TCP/IP over SSH:

• Basic SSH Connection with Defaults (Classic Protocol)

• SSH Connection With Ports (Classic Protocol)

• SSH Connection With Key File (Classic Protocol)

• SSH Connection with Fallback (Classic Protocol)

• Basic SSH Connection with Defaults (X Protocol)

• SSH Connection With SSL Mode (X Protocol)

Basic SSH Connection with Defaults (Classic Protocol)

This example shows the most basic form of the SSH tunnel connection. The MySQL port defaults to 3306 and the SSH port defaults to 22, because the values are not configured. Also, only a password is provided to authenticate to the SSH server. In this example, the connection is made using a MySqlConnectionStringBuilder object.

var builder = new MySqlConnectionStringBuilder();
builder.UserID = "myUser";
builder.Password = "test";
builder.Server = "localhost";
builder.SshHostName = "10.0.0.2";
builder.SshUserName = "mySshUser";
builder.SshPassword = "sshtest";
using (var connection = new MySqlConnection(builder.ConnectionString))
{
  connection.Open();
  connection.Close();
}

SSH Connection With Ports (Classic Protocol)

In this SSH tunneling example, the MySQL and SSH ports are configured to override the default values. Only a password is provided to authenticate to the SSH server. Note that the connection is made using a connection string.

using (var connection = new MySqlConnection("uid=myUser;password=test;server=localhost;port=3307;
          sshHostName=10.0.0.2;sshUserName=mySshUser;sshPassword=sshtest;sshPort=23"))
{
  connection.Open();
  connection.Close();
}

SSH Connection With Key File (Classic Protocol)

In addition to making the connection with a password, this example also includes a key file and pass phrase. Like the previous example, both the MySQL and SSH ports are configured.

using (var connection = new MySqlConnection("uid=myUser;password=test;server=localhost;port=3307;
          sshHostName=10.0.0.2;sshUserName=mySshUser;sshKeyFile=C:\\keys\\myOpenSshKeyFile.ppk;sshPassPhrase=sshTest;sshPort=23"))
{
  connection.Open();
  connection.Close();
}

SSH Connection with Fallback (Classic Protocol)

This example includes the SSH key file (without a pass phrase) and the SSH password. Because the key file is valid and the pass phrase is not required, the connection can fall back to the SSH password value if authentication with the SSH key file encounters an error on the server.

var builder = new MySqlConnectionStringBuilder();
builder.UserID = "myUser";
builder.Password = "test";
builder.Server = "localhost";
builder.Port = 3307;
builder.SshHostName = "10.0.0.2";
builder.SshUserName = "mySshUser";
builder.SshKeyFile = @"C:\keys\noPassPhraseOpenSshKeyFile.ppk";
builder.SshPassword = "sshtest";
using (var connection = new MySqlConnection(builder.ConnectionString))
{
  connection.Open();
  connection.Close();
}

Basic SSH Connection with Defaults (X Protocol)

This example configures the SSH connection with a default value for the SSH port (22). However, because the connection uses X Protocol to establish the SSH tunnel, the default MySQL port (33060) is provided in the URI-like connection string.

using (var session = MySQLX.GetSession("mysqlx://myUser:test@localhost:33060?sshHostName=10.0.0.2;
                      sshUserName=mySshUser;sshPassword=sshTest"))
{
    session.Close();
}

SSH Connection With SSL Mode (X Protocol)

This example creates the SSH tunnel for an anonymous object and it ensures that the use of SSL by denying the connection explicitly if the server does not support SSL.

var sessionOptions = {
    UserID = "myUser",
    Password = "test",
    Server = "127.0.0.1",
    Port = 3307,
    SshHostName = "10.0.0.2",
    SshUserName = "mySshUser",
    SshKeyFile = @"C:\keys\myOpenSshKeyFile.ppk",
    SshPassPhrase = "sshtest",
    SslMode = MySqlSslMode.Required
  };
using (var session = MySQLX.GetSession(sessionOptions))
{
    session.Close();
}