Security

Notary is designed with security as a core principle, implementing robust measures to safeguard sensitive data and ensure secure communication. This document outlines the key security features of Notary.

If you discover a security issue, see the Notary security policy for information on how to report the issue.

Encryption at Rest

Notary encrypts sensitive data at rest using AES-256 in Galois/Counter Mode (GCM).

The encryption key is stored alongside the data and can be encrypted with one of the following encryption backends:

  • PKCS#11: Uses a hardware security module (HSM) to manage encryption keys.

  • HashiCorp Vault: Utilizes Vault’s Transit secrets engine for encryption.

  • None: Leaves the data-encryption key unwrapped alongside the encrypted data. It does not disable AES-GCM, but possession of the database also gives access to that key. It is not recommended for production environments.

Configuration

The encryption backend is configured in the configuration file.

Transport Layer Security (TLS)

Notary uses TLS to secure its API and web interface. The use of TLS is mandatory, Notary will not start if the TLS configuration is missing or invalid.

Configuration

The TLS configuration is defined in the configuration file.

Certificate Management

To update TLS certificates:

  • Replace the certificate and key files on disk.

  • Restart Notary to apply the changes.

Supported TLS Versions

Notary supports TLS versions 1.2 and 1.3.

Cluster trust

Clustered members authenticate each other with dqlite mTLS, separate from the HTTPS API certificate. There are two modes.

Shared pair (default). If cluster.tls is not configured, the first member generates a self-signed pair on bootstrap and stores it in db_path as cluster.crt and cluster.key. Every member presents the same certificate, and each verifies its peer against it.

CA mode. Set cluster.tls.ca_path, cert_path, key_path, and peer_san. Each unit presents its own leaf signed by a dedicated cluster CA that Notary does not operate. Peers must present that CA plus the group SAN (peer_san). The unit private key is not copied into db_path. Do not reuse the HTTPS API CA.

Joining members do not receive cluster key material by copying files. notary cluster add issues a one-time token carrying the member name, the API addresses, a secret, an expiry, and the SHA-256 fingerprint of the issuing member’s HTTPS certificate. The joiner redeems the token against that member’s API over a connection pinned to the fingerprint. In shared-pair mode the response includes the cluster certificate and key. In CA mode the response is dqlite addresses only; the joiner must already have ca_path and its own leaf. The token itself never contains a private key.

dqlite has no protocol authentication. TLS trust on the dqlite port is authorisation. Join tokens only constrain notary start --join. Restrict the dqlite port to cluster members.

Three consequences are worth planning for:

  • A join token is a bearer credential. Until it is redeemed or expires, whoever holds it can obtain the shared cluster private key (default mode) or the current dqlite addresses (CA mode). Treat it like a password: pass it over a secure channel, do not put it in tickets or chat, and prefer notary start --join over storing it in a configuration file.

  • Removing a member is not revocation. notary cluster remove evicts a node from raft but does not invalidate credentials. Until you stop that process it can still reach the cluster database as a client. In shared-pair mode, genuinely revoking a member means generating a new cluster certificate and key, setting cluster.tls on every remaining member, and restarting them. In CA mode, Notary does not check CRLs or OCSP, so CA-side revocation alone does not deny access. Isolate the removed host, terminate its connections, and rotate the trusted cluster CA and remaining leaves if its credentials may be compromised. Expiry prevents new handshakes but does not terminate existing connections.

  • Backups can contain cluster keys. In shared-pair mode cluster.key lives in db_path. In CA mode the unit key stays at cluster.tls.key_path; still store backups of that path with the archive. See Back up and restore Notary.

There is no automatic rotation of the generated shared cluster certificate. That pair is valid for ten years; replacing it earlier is the manual procedure described above.

Authentication

Notary authenticates API requests using the user_token session cookie set by POST /login or OIDC login. Local login sets a Secure, HttpOnly, SameSite=Strict cookie with a two-hour expiry. An Authorization: Bearer header is not a replacement for this cookie. Passwords are hashed using Argon2id.

The first account can be created without authentication and receives the admin role. Restrict network access until the operator completes initialization. GET /status, /metrics, and CA CRL retrieval are public; restrict access to monitoring data at the network boundary. Cluster token redemption requires a valid join token rather than an administrator session.

Authorization

Notary uses role-based access control (RBAC) to manage user permissions. Each user is assigned a role that defines their permissions within the system. Roles are assigned to accounts when they are created, either via the API (see the API account reference) or the web interface. To view the role definitions, see the Roles reference.