> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/server/reference/plugins/authentication-plugins/authentication-plugin-parsec.md).

# Authentication Plugin - PARSEC

{% hint style="info" %}
This plugin is available from MariaDB 11.6.
{% endhint %}

The `PARSEC` Authentication Plugin is intended to be the default in a future release.

The `PARSEC` (Password Authentication using Response Signed with Elliptic Curve) authentication plugin uses salted passwords, key derivation, extensible password storage format, and both server- and client-side scrambles.

It signs the response with `ed25519`, but it uses stock unmodified `ed25519` as provided by OpenSSL/WolfSSL/GnuTLS.

### Description

* The KDF function is pbkdf2 (supported by everything, including [windows native](https://learn.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptderivekeypbkdf2), Java, javascript, PHP, .NET.
* Parameters to the pbkdf2 are stored in with authentication plugin data : hash function (SHA512,SHA256), iteration count, salt, key\_length, together with derived key = `PBKDF2(func, password, salt, iteration_count, key_length).`
* The number of iterations is a power of two, at least 1024. From MariaDB 13.1, it is configurable through the [`parsec_iterations`](#parsec_iterations) system variable.
* The algorithm is ed25519, "hash" is the public key generated using ed25519 from the PBKDF2(password).

The authentication string, stored by the server, is this:

```c
concat('P', conv(log2(iterations)-10, 10, 62), ':', base64(salt), ':', base64(hash))
```

For example, it looks like this: `P0:WW9sXaaL/o:vubFBzIrapbfHct1/J72dnUryz5VS7lA6XHH8sIx4TI`

* It consists of colon-separated fields.
* The first field is 'P' (denotes KDF algorithm = PBKDF2) and the number of iterations, '0' means 1024, '1' means 2048, etc.
* This is followed by the salt.
* This is followed by the password hash.

The first two fields together are called *ext-salt*, extended salt.

#### Login Process, Packet Exchange

1. The server sends an [Authentication Switch Request](/docs/server/reference/clientserver-protocol/1-connecting/connection.md#authentication-switch-request) with a 32-byte random scramble.
2. The client sends an empty packet to the server to request the [ext-salt](/docs/server/reference/clientserver-protocol/1-connecting/connection.md#parsec-plugin).
3. The server sends the [ext-salt](/docs/server/reference/clientserver-protocol/1-connecting/connection.md#parsec-plugin) to the client.
4. The client sends the random 32-byte scramble, and the `concat(server scramble, client scramble)` ed25519-signed by a secret key generated from the function `PBKDF2(password, ext-salt)`.
5. The server replies with ["ok"](/docs/server/reference/clientserver-protocol/4-server-response-packets/ok_packet.md) or ["access denied"](/docs/server/reference/clientserver-protocol/4-server-response-packets/err_packet.md).

### Installing

If you run into the error `ERROR 1524 (HY000): Plugin 'parsec' is not loaded` it means you need to install the authentication plugin first. You can do it on a running server with:

```sql
INSTALL SONAME 'auth_parsec';
```

There is no need to pass additional command-line options or have config files to keep the PARSEC authentication method available. Running the `INSTALL SONAME` once is enough and the MariaDB Server will remember it even if server is restarted or upgraded.

### Example

```sql
CREATE USER test1@'%' IDENTIFIED VIA parsec USING PASSWORD('pwd');
```

## Configuring the Number of Iterations

{% hint style="info" %}
The `parsec_iterations` system variable is available from MariaDB 13.1.
{% endhint %}

The number of PBKDF2 iterations used to derive the key from a password is controlled by the [`parsec_iterations`](#parsec_iterations) system variable. A higher value increases the cost of deriving the key, which strengthens resistance to brute-force attacks at the expense of more work per authentication.

The iteration count is baked into an account's stored credentials when its password is set. The value in effect at that time — the session value if set, otherwise the global value — is the one recorded for the account. Changing `parsec_iterations` afterwards does not alter existing accounts; they keep the iteration count they were created with until their password is set again.

```sql
SET SESSION parsec_iterations = 262144;
CREATE USER test1@'%' IDENTIFIED VIA parsec USING PASSWORD('pwd');
```

The value must be a power of two. If a value that is not a power of two is supplied, it is rounded up to the next power of two and a warning is issued:

```sql
SET GLOBAL parsec_iterations = 5000;
```

```
Warning (1231): parsec_iterations rounded up to 8192
```

### `parsec_iterations`

* Description: Number of iterations used when generating the key corresponding to the password (PBKDF2-HMAC-SHA512). Rounded up to a power of two. This variable is only available when the PARSEC plugin is loaded.
* Commandline: `--parsec-iterations=#`
* Scope: Global, Session
* Dynamic: Yes
* Data Type: `INT UNSIGNED`
* Default Value: `1024`
* Minimum Value: `1024`
* Maximum Value: `1073741824`
* Introduced: MariaDB 13.1

## Future

PARSEC is currently available in latest MariaDB versions, but [not installed or used by default yet](https://lists.mariadb.org/hyperkitty/list/developers@lists.mariadb.org/thread/SGQUUHRSSPAURX5JZAGXYXRIBMCKK52F/). Once [MDEV-12320](https://jira.mariadb.org/browse/MDEV-12320) is implemented, MariaDB plans to start using PARSEC as the default password authentication method.

<sub>*This page is licensed: CC BY-SA / Gnu FDL*</sub>

{% @marketo/form formId="4316" %}