Dear MySQL Connector/NET community,

We are proud to announce that version 8.0.17 is introducing support for SSH tunneled connections through the classic MySQL protocol and X Protocol. SSH enables the creation of secure encrypted connections between the local and a remote computer allowing services or components to be accessed, MySQL Server in this case. With SSH tunneling, users can connect to a MySQL Server from behind a firewall when the server port is blocked. The server doesn’t require any additional configuration for this type of connection and continues to work as usual.

Users can also add an extra layer of security by making use of SSL over SSH connections, which brings us to the second announcement. Connector/NET previously included support for SSL connections via PFX certificates, which are exclusive to Windows. However, now the support for SSL PEM certificates is available starting with version 8.0.16. This allows Connector/NET to align with other MySQL products. More importantly, it increases the security of your applications, specially when you are working with .NET Core to expand your deployment to platforms beyond Windows.

Connection Options Overview

Those unfamiliar with Connector/NET and/or the differences between the classic MySQL protocol and the X Protocol, first need to be aware of the different ways to construct a connection/session object with which a connection to a MySQL Server can be established. There are 4 methods available:

• Connection string: Available in the classic MySQL protocol and X Protocol. For the classic protocol an instance of the MySqlConnection class is created. In the constructor you provide a string containing key-value pairs which represent the connection options. For the X Protocol, call the MySQLX.GetSession method and provide the connection string in the constructor as well.
• Using a builder object: Available in the classic MySQL protocol and X Protocol. An instance of the MySqlConnectionStringBuilder (classic protocol) or MySqlXConnectionStringBuilder (X Protocol) is created. You assign values to the mentioned object’s properties which resemble the connection options available in the connection string. Once the properties have been set, call the ToString method to get the connection string and simply pass it to the MySqlConnection object or MySQLX.GetSession method.
• URI-like connection string: Available in the X Protocol only. A URI-like string is provided which starts with the mysqlx identifier. It supports the same connection options available for any other connection method.
• Using anonymous objects: Available in the X Protocol only. An anonymous object is created having properties that match the name of the properties defined in the MySqlXConnectionStringBuilder class. The object is simply passed to the MySQLX.GetSession static method.

Refer to the Connection Examples section for code snippets on using each method.

Creating SSH Tunneled Connections

SSH Connection Options

New connection options have been introduced to support SSH tunneled connections. The connection options can either be specified in the connection string or by making use of an instance of the MySqlConnectionStringBuilder or MySqlXConnectionStringBuilder class. Find the new connection options and their details below:

Initiate an SSH Connection

First, the connection protocol being used must be TCP/IP, note that this is the default connection protocol in Connector/NET. Additional to that, the presence of the SSH User Name and either the SSH Password or SSH Key File options will notify Connector/NET of the user’s intent to make use of an SSH connection. Be sure to specify said options.

It is also necessary to specify the IP address or host name of the SSH Server being accessed. If no SSH Port is specified, the connection will default to the commonly known port 22.

An SSH Password or SSH Pass Phrase can also be provided in the event that they are required by the SSH User Name or SSH Key File connection options respectively.

Finally, set the Server connection option to localhost and Port to the port number the MySQL Server is running at in the SSH server.

Fallback for SSH Connections

Connector/NET includes a fallback mechanism when working with SSH connections. If values are provided to connect using both a SSH Key File and a SSH Password, fallback from the key file to the password will take place in the event that the former attempt fails. Note that the fallback is only enabled whenever the error is detected on the server side, this meaning that if the error is on the client side the user will instead get an exception prior to the connection attempts being made. Causes for errors on the client side can be an invalid key file or an incorrect pass phrase. 

Connection Examples

The following code examples will get you started on creating SSH Tunneled connections:

Example 1

// This is the most basic form of an SSH connection. MySQL port defaults to
// 3306 and SSH Port defaults to 22 since the values are not provided.
// Also, only a password is being used to authenticate to SSH server.
// Connection is being 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();
}

Example 2

// Now the MySQL and SSH ports are being provided.
// Again, only a password is being used to authenticate to SSH server.
// Connection is being 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();
}

Example 3

// Here, a SSH key file with a pass phrase is provided. 
// Connection is being made using an anonymous object.
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();
}

Example 4

// A pass phrase-less SSH key file and SSH password are both being provided.
// Given that the key file and pass phrase are valid a fallback to SSH 
// password will take place if authentication via SSH key file fails at 
// server side.
// place if a
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();
}

Example 5

// An X Protocol SSH connection using a 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();
}

Example 6

// An X Protocol SSH connection using an anonymous object along with
// setting an SSL Mode.
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();
}

Refer to the official documentation of Connector/NET for additional details on using SSH tunneling for your applications.

Creating SSL Connections with PEM Certificates

Connector/NET supports multiple levels of SSL encryption through the SSL Mode connection option. The list of allowed SSL encryption values are:

• None: Do not use SSL.
• Preferred: Use SSL, if server supports it.
• Required: Always use SSL. Deny connection if server does not support SSL. Do not perform server certificate validation.
• VerifyCA: Always use SSL. Validate server SSL certificate, but different host name mismatch.
• VerifyFull: Always use SSL and perform full certificate validation.

The None, Preferred and Required SSL Modes don’t require the user to provide any certificates. Setting SSL Mode to VerifyCA requires that the SSL CA option is set. Setting SSL Mode to VerifyFull requires that SSL CA, SSL Cert and SSL Key are all set. Both VerifyCA and VerifyFull provide added security by performing various validations on the SSL certificates.

SSL Connection Options

Similar to how SSH tunneling introduced new connection options, a couple of connection options were added to support SSL PEM based connections. In past versions, the SSL CA and CertificateFile options could both be used to specify the path to a PFX certificate. Starting with version 8.0.16, the existing SSL CA option was extended to be used with SSL PEM connections as well. The full list of options relevant for SSL PEM connections can be found below:

As previously mentioned, the SSL CA option is also supported in PFX based SSL connections. The extension of the file referenced in this connection option tells Connector/NET how to process the certificate and in the case of PEM based connections, it will notify Connector/NET to check the SSL Cert and SSL Key options.

Connection Examples

The following code examples will get you started on creating SSL PEM based connections:

Example 1

// Here only the SSL Ca option is required since the SSL Mode is set to VerifyCA.
// The connection is being made using a MySqlConnectionStringBuilder object.
var builder = new MySqlConnectionStringBuilder();
builder.UserID = "myUser";
builder.Password = "test";
builder.Server = "localhost";
builder.SslCa = "ca.pem";
builder.SslMode = MySqlSslMode.VerifyCA; 
using (var connection = new MySqlConnection(builder.ConnectionString))
{
  connection.Open();
  connection.Close();
}

Example 2

// All SSL options are required since the SSL Mode is set to VerifyFull.
// The connection is being made using a connection string.
using (var connection = new MySqlConnection("uid=myUser;password=test;server=localhost;port=3307;sslMode=VerifyFull;sslCa=ca.pem;sslCert=client-cert.pem;sslKey=client.key.pem"))
{
  connection.Open();
  connection.Close();
}

SSL PEM connections are also available for the X Protocol. SSL connection options are named similarly in the MySqlXConnectionStringBuilder class, anonymous object and URI-like connection string methods. Feel free to use the one that best adapts to your  needs. 

Additional Information and Useful Links

We really hope that you’ve enjoyed the time invested in getting to know these new features and that they prove useful and a step in the right direction to deliver more robust and secure MySQL based applications.

Your feedback is always welcome, so be sure to provide any comments or report any issues into our forums and dedicated bug page.

Finally, we leave you with the following links which will serve as reference to additional information about the topics discussed in this blog post and with Connector/NET in general. Thank you. 

• Connection Options Reference Documentation
• Official documentation
• Download Connector/NET
• MySQL Encrypted Connections