Connection Options

• Essential options
• Support for big integer
• Ssl
• Configuration
• Certificate validation
• One-way SSL authentication
• Two-way SSL authentication
• Other options
• F.A.Q.

Essential Options

Big Integer Support

Integers in JavaScript use IEEE-754 representation. This means that Node.js cannot exactly represent integers in the ±9,007,199,254,740,991 range. However, MariaDB does support larger integers.

This means that when the value set on a column is not in the safe range, the default implementation receives an inexact representation of the number.

The Connector provides two options to address this issue.

SSL

The Connector can encrypt data during transfer using the Transport Layer Security (TLS) protocol. TLS/SSL allows for transfer encryption, and can optionally use identity validation for the server and client.

There are two different kinds of SSL authentication:

• One-Way SSL Authentication: The client verifies the certificate of the server. This allows you to encrypt all exchanges and make sure that you are connecting to the expected server (to avoid a man-in-the-middle attack).
• Two-Way SSL Authentication The client verifies the certificate of the server, the server verifies the certificate of the client. This is also called mutual authentication or client authentication. When using this system, the client also requires a dedicated certificate.

Server Configuration

In order to use SSL, you need to ensure that the MariaDB Server is correctly configured. You can determine this using the have_ssl system variable.

SHOW VARIABLES LIKE 'have_ssl';

+---------------+----------+
| Variable_name | Value    |
+---------------+----------+
| have_ssl      | DISABLED |
+---------------+----------+

A value of NO indicates that MariaDB was compiled without support for TLS. DISABLED means that it was compiled with TLS support, but it's currently turned off. In order to use SSL with the Connector, the server must return YES, indicating that TLS support is available and turned on. For more information, see the MariaDB Server documentation.

User Configuration

Enabling the ssl option on the server, the Connector uses one-way SSL authentication to connect to the server. Additionally, it's recommended that you also configure your users to connect through SSL. This ensures that their accounts can only be used with an SSL connection.

For GRANT statements, use the REQUIRE SSL option for one-way SSL authentication and the REQUIRE X509 option for two-way SSL authentication. For more information, see the CREATE USER documentation.

CREATE USER 'johnSmith'@'%' IDENTIFIED BY PASSWORD('passwd');
GRANT ALL ON company.* TO 'johnSmith'@'%' REQUIRE SSL;

Now when this user attempts to connect to MariaDB without SSL, the server rejects the connection.

Configuration

• ssl: boolean/JSON object.

JSON object:

The Connector uses the Node.js implementation of TLS. For more information, see the Node.js TLS API documentation.

Certificate Validation

Trusted CA

By default, Node.js trusts the well-known root Certificate Authorities (CA), based on Mozilla. For a complete list, (including the popular and free Let's Encrypt), see the CA Certificate List.

When using a certificate signed with a certificate chain from a root CA known to Node.js, the only configuration you need to do is enable the ssl option.

Certificate Chain Validation

A certificate chain is a list of certificates that were issued from the same Certification Authority hierarchy. In order for any certificate to be validated, all certificates in the chain have to be validated.

In cases where intermediate or root certificates are not trusted by the Connector, the Connector rejects the connection and issues an error.

Hostname Verification (SNI)

Certificates can provide hostname verification to the driver. By default this is done against the certificate's subjectAlternativeName DNS name field.

One-way SSL Authentication

When the server certificate is signed using the certificate chain that uses a root CA known in the JavaScript trust store, setting the ssl option enables one-way SSL authentication.

For instance,

const mariadb = require('mariadb');
mariadb
 .createConnection({
   host: 'myHost.com', 
   ssl: true, 
   user: 'myUser', 
   password:'MyPwd', 
   database:'db_name'
 }).then(conn => {})

When the server uses a self-signed certificate or uses an intermediate certificate, there are two different possibilities:

In non-production environments, you can tell the Connector to trust all certificates by setting rejectUnauthorized to false. Do NOT use this in production.

//connecting
mariadb
 .createConnection({
   host: 'myHost.com', 
   ssl: {
	 rejectUnauthorized: false
   }, 
   user: 'myUser', 
   password:'MyPwd', 
 }).then(conn => {})

A more secure alternative is to provide the certificate chain to the Connector.

const fs = require("fs");
const mariadb = require('mariadb');

//reading certificates from file
const serverCert = [fs.readFileSync("server.pem", "utf8")];

//connecting
mariadb
 .createConnection({
   user: "myUser",
   host: "myHost.com",
   ssl: {
	 ca: serverCert
   }
 }).then(conn => {})

Using Specific TLS Protocols or Ciphers

In situations where you don't like the default TLS protocol or cipher or where you would like to use a specific version, you force the Connector to use the one you want using the secureProtocol and cipher options.

For instance, say you want to connect using TLS version 1.2:

//connecting
mariadb
 .createConnection({ 
   user:"myUser", 
   host: "myHost.com",
   ssl: {
	 ca: serverCert,
	 secureProtocol: "TLSv1_2_method",
	 ciphers:
	   "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256"        
   }
 }).then(conn => {})

For more information on what's available, see possible protocol values.

Two-way SSL Authentication

Mutual SSL authentication or certificate-based mutual authentication refers to two parties authenticating each other by verifying the provided digital certificates. This allows both parties to be assured of the other's identity. In order to use mutual authentication, you must set the REQUIRE X509 option in the GRANT statement. For example,

GRANT ALL ON company.* TO 'johnSmith'@'%' REQUIRE X509;

This option causes the server to ask the Connector for a client certificate. If the user is not set with REQUIRE X509, the server defaults to one-way authentication

When using mutual authentication, you need a certificate, (and its related private key), for the Connector as well as the server. If the Connector doesn't provide a certificate and the user is set to REQUIRE X509, the server returns a basic Access denied for user message.

In the event that you would like to see how users are defined, you can find this information by querying the mysql.user table on the server. For instance, say you wanted information on the johnSmith user.

SELECT ssl_type, ssl_cipher, x509_subject 
FROM mysql.user
WHERE User = 'johnSmith';

You can test it by creating a user with REQUIRE X509 for testing:

CREATE USER 'X509testUser'@'%';
GRANT ALL PRIVILEGES ON *.* TO 'X509testUser'@'%' REQUIRE X509;

Then use its credentials in your application:

const fs = require("fs");
const mariadb = require('mariadb');

//reading certificates from file
const serverCert = [fs.readFileSync("server.pem", "utf8")];
const clientKey = [fs.readFileSync("client.key", "utf8")];
const clientCert = [fs.readFileSync("client.pem", "utf8")];

//connecting
mariadb
 .createConnection({ 
   user:"X509testUser", 
   host: "mariadb.example.com",
   ssl: {
	 ca: serverCert,
	 cert: clientCert,
	 key: clientKey
   }
 }).then(conn => {})

Using Keystores

Keystores allow you to store private keys and certificate chains encrypted with a password to file. For instance, using OpenSSL you can generate a keystore using PKCS12 format:

$ openssl pkcs12 \
	-export \
	-in "${clientCertFile}" \
	-inkey "${clientKeyFile}" \
	-out "${keystoreFile}" \
	-name "mariadbAlias" \
	-passout pass:kspass

You can then use the keystore in your application:

const fs = require("fs");
const mariadb = require('mariadb');

//reading certificates from file (keystore must be read as binary)
const serverCert = fs.readFileSync("server.pem", "utf8");
const clientKeystore = fs.readFileSync("keystore.p12");

//connecting
mariadb.createConnection({ 
 user:"X509testUser", 
 host: "mariadb.example.com",
 ssl: {
   ca: serverCert,
   pfx: clientKeystore,
   passphrase: "kspass"
 }
}).then(conn => {});

Other Options

F.A.Q.

Error Hostname/IP doesn't match certificate's altnames

Clients verify certificate SAN (subject alternative names) and CN to ensure that the certificate corresponds to the hostname. If the certificate's SAN/CN does not correspond to the host option, it returns an error such as:

Hostname/IP doesn't match certificate's altnames: "Host: other.example.com. is not cert's CN: mariadb.example.com"

To fix this, correct the host value to correspond to the host identified in the certificate.

Error routines:ssl_choose_client_version:unsupported protocol

Since Node.js 12 minimum TLS version is set to 1.2.

MariaDB server can be built with different SSL library, old version supporting only TLS up to 1.1. The error "1976:error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol" can occur if MariaDB SSL implementation doesn't support TLSv1.2.

This can be solved by :

• Server side: update MariaDB to a recent version
• Client side: permit lesser version with "tls.DEFAULT_MIN_VERSION = 'TLSv1.1';" or permitting lesser version of protocol by connection configuration: using option `ssl: { secureProtocol: 'TLSv1_1_method' }'