Authentication Plugin - tls_certificate

The tls_certificate authentication plugin authenticates an account by its TLS client certificate alone, with no password, requiring the certificate subject to match REQUIRE SUBJECT.

This plugin is available from MariaDB Enterprise Server 12.3. It is not included in MariaDB Community Server.

The tls_certificate authentication plugin authenticates a user from the TLS client certificate presented during the connection handshake. No password is involved at any point: the account holds no password, none is sent, and none is checked.

The account is identified by the certificate's subject Distinguished Name (DN), which must be pinned on the account with a REQUIRE SUBJECT clause. The plugin refuses to authenticate an account that was not created with REQUIRE SUBJECT.

Description

The plugin itself does no certificate validation. Signature checking, expiry, and revocation (CRL/OCSP) are all handled by the server's TLS layer during the handshake, before the plugin runs. The plugin's only check is that the account carries a REQUIRE SUBJECT clause; enforcing that clause is likewise the server's job.

Installing

The plugin is built into MariaDB Enterprise Server and enabled by default. There is no INSTALL SONAME step, and no separate package to install.

No client-side change is needed either. The plugin accepts any standard client authentication plugin, so existing clients and connectors connect without modification — they simply need to present the certificate.

Example

Create an account whose subject DN matches the client certificate, and grant it as usual:

CREATE USER 'alice'@'%'
  IDENTIFIED VIA tls_certificate
  REQUIRE SUBJECT '/CN=alice/O=Example Ltd/C=FI';

IDENTIFIED WITH is accepted as a synonym for IDENTIFIED VIA.

The client connects with its key pair and no password:

mariadb --user=alice \
        --ssl-ca=/etc/ssl/ca.pem \
        --ssl-cert=/etc/ssl/alice-cert.pem \
        --ssl-key=/etc/ssl/alice-key.pem

If the certificate subject does not match, or the account has no REQUIRE SUBJECT clause, the connection fails with a standard access-denied error — the plugin defines no error code of its own:

ERROR 1698 (28000): Access denied for user 'alice'@'localhost'

For the mechanics of subject matching (case sensitivity, field order, and the issuer-pinning caveat), see Matching the Certificate Subject under CREATE USER.

Account Management Behavior

Because these accounts authenticate with no password, several password-related features do not apply:

• PASSWORD EXPIRE and password_lifetime have no effect — the expiry check is skipped for a connection that used no password. Use ACCOUNT LOCK, which is enforced normally, to disable such an account.

• A USING or AS clause is accepted and stored, but the plugin never reads it, so it has no effect. SET PASSWORD on these accounts is rejected.

An account created with IDENTIFIED VIA tls_certificate but without REQUIRE SUBJECT is created successfully and cannot connect. The plugin API offers no hook at CREATE USER time for a passwordless plugin, so no warning can be raised. Add the clause with ALTER USER and the account works.

When several authentication methods are combined with OR, the first one that succeeds wins. An account given both tls_certificate and a password method can therefore log in with the password alone if REQUIRE SUBJECT is absent. Requiring both a valid certificate and a password needs multi-factor authentication (several plugins combined with AND), which is not yet available.

Options

The plugin adds no system variables and no status variables. The only option is the standard plugin activation option.

tls_certificate

• Description: Controls how the server should treat the plugin when the server starts up.

  • Valid values are:

    • OFF - Disables the plugin without removing it from the mysql.plugin table.

    • ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.

    • FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.

    • FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.

  • See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.

• Command line: --tls-certificate=value, or equivalently --plugin-tls-certificate=value

• Data Type: enumerated

• Default Value: ON

• Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT

• Introduced: MariaDB Enterprise Server 12.3

On the command line and in configuration files, MariaDB treats - and _ in an option name as equivalent, so --plugin-tls_certificate works as well. Option names are always printed with hyphens, which is why mariadbd --help --verbose lists --plugin-tls-certificate even though the plugin is named tls_certificate in SQL.

See Also

• Pluggable Authentication Overview

• CREATE USER

• ALTER USER

• Securing Connections for Client and Server

• SSL/TLS System Variables

_{This page is licensed: CC BY-SA / Gnu FDL}