Mutual TLS (mTLS)

Lamaste uses client certificates to authenticate admin access — your browser proves its identity at the TLS level before any HTTP request is sent.

In Plain English

When you visit a normal HTTPS website, your browser checks the server's certificate to verify you are talking to the real site. This is one-way trust: the browser trusts the server.

Mutual TLS (mTLS) adds a second direction. The server also checks your certificate to verify you are an authorized admin. This is two-way trust: the browser trusts the server, and the server trusts the browser.

Think of it like a members-only club with ID checks at the door. The club has a sign outside proving it is legitimate (the server certificate). But to get in, you also need to show your membership card (the client certificate). If you do not have the card, the bouncer does not even let you through the door — you never reach the lobby.

This is exactly how Lamaste protects its admin panel. During installation, a digital "membership card" (a .p12 file) is generated. You import it into your browser once, and from then on, every time you visit the panel, your browser automatically presents the certificate. No username, no password, no login page. If someone without the certificate tries to access the panel, nginx rejects the connection at the TLS layer — before any HTTP traffic is exchanged.

This approach is inspired by LXD, which uses the same client certificate model for its management API.

For Users

When you encounter mTLS

You encounter mTLS during two moments:

After installation — the installer prints a .p12 file path and password. You download this file and import it into your browser or OS keychain.
Every time you visit the panel — your browser silently presents the certificate. You see no login prompt; you are simply authenticated.

Importing the certificate

After running npx @lamalibre/create-lamaste, the installer prints something like:

╔══════════════════════════════════════════════════════════════╗
║  Client certificate ready                                    ║
║                                                              ║
║  Download:  scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .  ║
║  Password:  a7f3b2e1d9c8456e                                ║
║  Panel URL: https://203.0.113.42:9292                        ║
╚══════════════════════════════════════════════════════════════╝

You copy the .p12 file to your local machine and import it.

macOS (Safari and Chrome)

Double-click the .p12 file
Keychain Access opens — choose "login" keychain
Enter the password printed by the installer
The certificate appears under "My Certificates" in Keychain Access
Visit https://203.0.113.42:9292 — Safari/Chrome prompts you to select a certificate
Select the "Lamaste Client" certificate and click OK

macOS remembers this selection. Future visits present the certificate automatically.

macOS (Firefox)

Firefox uses its own certificate store, separate from Keychain Access:

Open Firefox → Settings → Privacy & Security → Certificates → View Certificates
Click "Your Certificates" tab → "Import"
Select the .p12 file and enter the password
Visit https://203.0.113.42:9292 — Firefox prompts you to select a certificate

Windows (Chrome and Edge)

Double-click the .p12 file
The Certificate Import Wizard opens
Choose "Current User" and click Next
Enter the password and click Next
Choose "Automatically select the certificate store" and click Next
Visit https://203.0.113.42:9292

Linux (Chrome)

Open Chrome → Settings → Privacy and Security → Security → Manage certificates
Click "Your certificates" → "Import"
Select the .p12 file and enter the password
Visit https://203.0.113.42:9292

What happens without a certificate

If you visit the panel URL in a browser that does not have the client certificate imported, nginx rejects the TLS handshake. Instead of the panel, you see a certificate help page explaining what happened and how to import the certificate.

The rejection happens at the TLS level — no HTTP request ever reaches the panel server. This is a stronger security boundary than a login page, which at minimum requires the server to parse and respond to HTTP requests.

Once the certificate is imported, you never see a login page for the admin panel. Your browser presents the certificate automatically on every HTTPS connection to the panel. This is what "zero-login" means — authentication is handled by the TLS layer, not by the application.

This does not affect the tunneled apps. Visitors to your tunneled apps authenticate through Authelia TOTP 2FA, which is a separate system entirely.

Multiple devices

The .p12 file can be imported into multiple browsers and devices. If you want to access the admin panel from both your laptop and your phone, import the same .p12 file on each.

If you lose access to the certificate and need a new one, run sudo lamaste-server reset-admin on the server (SSH or your provider's console). It issues a new admin certificate and revokes the old one; the panel itself never issues admin certificates.

Agent certificates

When connecting a machine to Lamaste using lamaste-agent, you should not use the admin certificate. Instead, generate a scoped agent certificate from the panel:

Open the Lamaste panel → Certificates → Agent Certificates
Click "Generate" and enter a label (e.g., macbook-pro)
Save the displayed password — it cannot be retrieved later
Download the .p12 file
Share the .p12 file and password with the agent machine through a secure channel, then install the agent there (npm install -g @lamalibre/lamaste-agent) and run lamaste-agent setup (an enrollment token avoids moving the key at all — see Agent Setup)

Agent certificates have capability-based access. By default, a new agent can only read tunnel configuration. Admins can grant additional capabilities per-agent from the panel UI:

Capability	What it grants
`tunnels:read`	List the agent's own tunnels and fetch its Chisel config (always-on)
`tunnels:write`	Create, update and delete tunnels the agent carries (restricted access mode only)
`services:read`	View service status
`services:write`	Start/stop/restart services
`system:read`	View system stats (CPU, RAM, disk)
`sites:read`	List sites and browse files
`sites:write`	Upload and delete files on assigned sites
`panel:expose`	Expose agent management panel at `agent-<label>.<domain>` via mTLS-protected subdomain
`identity:read`	Parse Authelia identity headers on plugin routes
`identity:query`	Query panel for Authelia user metadata

Capabilities are stored server-side, so changing what an agent can do does not require reissuing its certificate. Users, certificates, agent management, and logs always remain admin-only.

If a machine is compromised, the attacker is limited to whichever capabilities were assigned to that agent's certificate — and the admin can revoke or reduce capabilities at any time from the panel. The agent will immediately lose access.

For Developers

PKI hierarchy

Lamaste generates a minimal two-level PKI (Public Key Infrastructure) during installation:

Lamaste CA (self-signed, 10-year validity)
    │
    ├── Admin certificate (CN=admin, signed by CA, 2-year validity)
    │     └── Full panel access
    │
    └── Agent certificates (CN=agent:<label>, signed by CA, 2-year validity)
          └── Capability-based access (one per agent)

The CA (Certificate Authority) is self-signed because there is no need for external trust. The only party that needs to trust the CA is nginx on the same server. nginx is configured with the CA's public certificate and rejects any client certificate not signed by that CA.

All certificates — admin and agent — are signed by the same CA. The difference is the Common Name (CN): the mTLS middleware parses the CN to determine the role and restricts access accordingly.

Certificate generation

The installer (packages/create-lamaste/src/tasks/mtls.js) generates the PKI in five steps:

1. Generate CA private key     (4096-bit RSA)
2. Create self-signed CA cert  (CN=Lamaste CA, 10-year, SHA-256)
3. Generate client private key (4096-bit RSA)
4. Create CSR and sign it      (CN=admin, 2-year, SHA-256)
5. Export PKCS12 bundle        (client key + cert + CA cert)

Each step uses OpenSSL CLI commands via execa:

javascript

// Step 1: CA key
await execa('openssl', ['genrsa', '-out', `${pkiDir}/ca.key`, '4096']);

// Step 2: CA certificate
await execa('openssl', [
  'req',
  '-x509',
  '-new',
  '-nodes',
  '-key',
  `${pkiDir}/ca.key`,
  '-sha256',
  '-days',
  '3650',
  '-out',
  `${pkiDir}/ca.crt`,
  '-subj',
  '/CN=Lamaste CA/O=Lamaste',
]);

// Step 3: Client key
await execa('openssl', ['genrsa', '-out', `${pkiDir}/client.key`, '4096']);

// Step 4: CSR + sign
await execa('openssl', [
  'req',
  '-new',
  '-key',
  `${pkiDir}/client.key`,
  '-out',
  `${pkiDir}/client.csr`,
  '-subj',
  '/CN=admin/O=Lamaste',
]);
await execa('openssl', [
  'x509',
  '-req',
  '-in',
  `${pkiDir}/client.csr`,
  '-CA',
  `${pkiDir}/ca.crt`,
  '-CAkey',
  `${pkiDir}/ca.key`,
  '-CAcreateserial',
  '-out',
  `${pkiDir}/client.crt`,
  '-days',
  '730',
  '-sha256',
]);

// Step 5: PKCS12 bundle
await execa('openssl', [
  'pkcs12',
  '-export',
  '-keypbe',
  'PBE-SHA1-3DES',
  '-certpbe',
  'PBE-SHA1-3DES',
  '-macalg',
  'sha1',
  '-out',
  `${pkiDir}/client.p12`,
  '-inkey',
  `${pkiDir}/client.key`,
  '-in',
  `${pkiDir}/client.crt`,
  '-certfile',
  `${pkiDir}/ca.crt`,
  '-passout',
  `pass:${password}`,
]);

PKCS12 compatibility flags

The PKCS12 export uses legacy encryption algorithms (PBE-SHA1-3DES) and SHA-1 MAC. This is deliberate. Modern OpenSSL 3.x defaults to AES-256-CBC with SHA-256, which macOS Keychain Access cannot import. The legacy flags ensure compatibility across all platforms:

Platform	Modern PKCS12	Legacy PKCS12 (PBE-SHA1-3DES)
macOS Keychain Access	fails	works
Firefox	works	works
Chrome (Windows)	works	works
Chrome (Linux)	works	works

nginx mTLS enforcement

The installer writes an nginx snippet at /etc/nginx/snippets/lamalibre-lamaste-mtls.conf:

nginx

ssl_client_certificate /etc/lamalibre/lamaste/pki/ca.crt;
ssl_verify_client optional;

This snippet is included in every nginx vhost that should require mTLS. The ssl_verify_client optional directive enables client certificate verification at the TLS level while still allowing connections without a certificate (needed for public endpoints like /api/enroll and /api/invite). Protected locations enforce mTLS via if ($ssl_client_verify != SUCCESS) { return 496; } in each vhost's location blocks. If a client presents a certificate not signed by the specified CA, nginx returns a 495 or 496 error — before any application code runs.

The panel vhost includes this snippet and uses per-location if checks to enforce mTLS on protected locations while allowing public endpoints through:

nginx

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 9292 ssl;
    server_name _;

    ssl_certificate /etc/lamalibre/lamaste/pki/self-signed.pem;
    ssl_certificate_key /etc/lamalibre/lamaste/pki/self-signed-key.pem;

    include /etc/nginx/snippets/lamalibre-lamaste-mtls.conf;

    # Show help page when client cert is missing
    error_page 495 496 /cert-help.html;
    location = /cert-help.html {
        root /opt/lamalibre/lamaste/lamaste-server-ui;
        internal;
    }

    # Protected locations — reject if client cert missing or invalid
    location / {
        if ($ssl_client_verify != SUCCESS) {
            return 496;
        }
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Public API paths — no mTLS check, cert headers cleared
    location /api/enroll {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header X-SSL-Client-Verify "";
        proxy_set_header X-SSL-Client-DN "";
        proxy_set_header X-SSL-Client-Serial "";
        # ... standard proxy headers
    }

    location /api/invite {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header X-SSL-Client-Verify "";
        proxy_set_header X-SSL-Client-DN "";
        proxy_set_header X-SSL-Client-Serial "";
        # ... standard proxy headers
    }

    # API paths with WebSocket upgrade support (mTLS required)
    location /api {
        if ($ssl_client_verify != SUCCESS) {
            return 496;
        }
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

The error_page 495 496 directive shows a help page explaining how to import the certificate, rather than showing a cryptic TLS error. Public endpoints (/api/enroll for agent enrollment and /api/invite for user invitations) clear the client certificate headers so that the Fastify server treats them as unauthenticated requests, matching their registration in the publicContext (no mTLS middleware).

Certificate help page

When a visitor without a client certificate hits the panel, nginx serves a static HTML page from /opt/lamalibre/lamaste/lamaste-server-ui/cert-help.html. This page explains what mTLS is and provides step-by-step import instructions. The page is generated during installation with the VPS IP address embedded, so the SCP command is ready to copy.

Client certificate headers

After TLS negotiation succeeds, nginx forwards client certificate information to the panel server via headers:

nginx

proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
proxy_set_header X-SSL-Client-Serial $ssl_client_serial;

The panel server's mTLS middleware checks these headers in order:

X-SSL-Client-Verify — must be SUCCESS (valid client cert); any other value (FAILED, NONE) results in a 403 Forbidden response.
X-SSL-Client-Serial — checked against the revocation list (revoked.json); if the serial is revoked, the request is rejected with 403.
X-SSL-Client-DN — the CN is parsed to determine the role. CN=admin grants full access; CN=agent:<label> grants capability-based access with permissions looked up from the agent registry.

In development (NODE_ENV=development), all checks are skipped.

Certificate rotation

Client certificates expire after 2 years. The management panel's Certificates page shows the expiry date. The admin certificate is rotated on the server with sudo lamaste-server reset-admin (packages/server/cli/src/commands/reset-admin.js) — the panel runs unprivileged and signs only agent certificates, and its rotation endpoint answers 503 with that instruction:

1. Verify CA key exists
2. Generate new client key (4096-bit RSA)            ─┐
3. Create CSR (CN=admin) and sign with the CA (2 yr)  │ run as the lamaste user,
4. Create new PKCS12 bundle with random password      │ which owns the PKI directory
5. Back up current client.key, client.crt, client.p12 │
6. Move new files into place                         ─┘
7. Revoke the old admin certificate, clear panel 2FA, set adminAuthMode to p12
8. Restart the panel, reload nginx, print the new PKCS12 password

The CA certificate is never rotated — it has a 10-year validity. Since nginx trusts the CA, and all client certificates are signed by the same CA, rotating the client cert does not require any nginx changes.

Idempotent installation

The mTLS generation task is idempotent. If ca.key and client.p12 already exist (e.g., the installer is re-run), the entire generation is skipped. This prevents invalidating a previously imported client certificate:

javascript

const alreadyProvisioned = existsSync(`${pkiDir}/ca.key`) && existsSync(`${pkiDir}/client.p12`);

if (alreadyProvisioned) {
  // Read existing p12 password for the summary display
  ctx.p12Password = await readFile(`${pkiDir}/.p12-password`, 'utf8');
  return; // Skip all generation steps
}

File layout

/etc/lamalibre/lamaste/pki/
├── ca.key              (600) CA private key — never leaves the server
├── ca.crt              (644) CA certificate — nginx uses this to verify clients
├── client.key          (600) Admin client private key — bundled into .p12
├── client.crt          (644) Admin client certificate — bundled into .p12
├── client.p12          (600) Admin PKCS12 bundle — downloaded by admin
├── .p12-password       (600) Password for the admin .p12 file
├── self-signed.pem     (644) Self-signed TLS cert for IP access
├── self-signed-key.pem (600) Key for self-signed TLS cert
├── revoked.json        (600) Revoked certificate serial numbers
└── agents/                   Agent certificate storage
    ├── registry.json   (600) Metadata for all agent certs
    └── <label>/              Per-agent directory
        ├── client.key  (600) Agent private key
        ├── client.crt  (644) Agent certificate (CN=agent:<label>)
        └── client.p12  (600) Agent PKCS12 bundle

Source files

File	Purpose
`packages/create-lamaste/src/tasks/mtls.js`	PKI generation during installation
`packages/create-lamaste/src/tasks/nginx.js`	mTLS snippet and panel vhost
`packages/lamaste-serverd/src/lib/mtls.js`	Certificate rotation, expiry checks, .p12 download
`packages/lamaste-serverd/src/middleware/mtls.js`	Request-level mTLS verification
`packages/lamaste-serverd/src/routes/management/certs.js`	Certificate management API endpoints

Quick Reference

PKI hierarchy

Certificate	Signed by	Validity	Key size	Purpose
CA (`ca.crt`)	Self-signed	10 years	4096-bit RSA	Trust anchor for nginx
Admin (`client.crt`)	CA	2 years	4096-bit RSA	Full panel access (browser)
Agent (`agents/<label>/client.crt`)	CA	2 years	4096-bit RSA	Capability-based access (agent)
Self-signed TLS	Self-signed	10 years	2048-bit RSA	HTTPS for IP access

File permissions

File	Mode	Owner	Access
`ca.key`	`600`	lamaste	CA signing only
`ca.crt`	`644`	lamaste	nginx reads this
`client.key`	`600`	lamaste	Bundled in .p12
`client.crt`	`644`	lamaste	Bundled in .p12
`client.p12`	`600`	lamaste	Downloaded by admin
`.p12-password`	`600`	lamaste	Installer summary

The PKI directory (0700) belongs to the panel's lamaste user: the panel is the CA and signs agent certificates itself, unprivileged, refusing any CN that is not an agent or plugin-agent label. Admin certificates are issued only by sudo lamaste-server reset-admin on the server, which runs its openssl steps as lamaste.

nginx directives

Directive	Value	Effect
`ssl_client_certificate`	`/etc/lamalibre/lamaste/pki/ca.crt`	CA that signs valid client certs
`ssl_verify_client`	`optional`	Enable client cert verification (per-location `if` enforces)
`error_page 495 496`	`/cert-help.html`	Show help when cert is missing

OpenSSL commands

bash

# View CA certificate details
openssl x509 -in /etc/lamalibre/lamaste/pki/ca.crt -text -noout

# View client certificate details
openssl x509 -in /etc/lamalibre/lamaste/pki/client.crt -text -noout

# Check client certificate expiry
openssl x509 -in /etc/lamalibre/lamaste/pki/client.crt -enddate -noout

# Verify client cert is signed by CA
openssl verify -CAfile /etc/lamalibre/lamaste/pki/ca.crt /etc/lamalibre/lamaste/pki/client.crt

# Inspect PKCS12 bundle contents
openssl pkcs12 -in /etc/lamalibre/lamaste/pki/client.p12 -info -nokeys

API endpoints

Method	Path	Description
POST	`/api/certs/mtls/rotate`	Rotate admin client certificate
GET	`/api/certs/mtls/download`	Download current admin `.p12` file
GET	`/api/certs`	List all certificates including mTLS
POST	`/api/certs/agent`	Generate agent-scoped certificate
GET	`/api/certs/agent`	List agent certificates
GET	`/api/certs/agent/:label/download`	Download agent `.p12` file
PATCH	`/api/certs/agent/:label/capabilities`	Update agent capabilities
PATCH	`/api/certs/agent/:label/allowed-sites`	Update agent site access
DELETE	`/api/certs/agent/:label`	Revoke agent certificate

Authentication — how tunneled apps use Authelia TOTP (separate from mTLS)
Certificates — Let's Encrypt certificates for domains
Security Model — mTLS as part of the defense-in-depth strategy
nginx Reverse Proxy — how nginx enforces mTLS

Mutual TLS (mTLS) ​

In Plain English ​

For Users ​

When you encounter mTLS ​

Importing the certificate ​

macOS (Safari and Chrome) ​

macOS (Firefox) ​

Windows (Chrome and Edge) ​

Linux (Chrome) ​

What happens without a certificate ​

Zero-login access ​

Multiple devices ​

Agent certificates ​

For Developers ​

PKI hierarchy ​

Certificate generation ​

PKCS12 compatibility flags ​

nginx mTLS enforcement ​

Certificate help page ​

Client certificate headers ​

Certificate rotation ​

Idempotent installation ​

File layout ​

Source files ​

Quick Reference ​

PKI hierarchy ​

File permissions ​

nginx directives ​

OpenSSL commands ​

API endpoints ​

Related documentation ​

Mutual TLS (mTLS)

In Plain English

For Users

When you encounter mTLS

Importing the certificate

macOS (Safari and Chrome)

macOS (Firefox)

Windows (Chrome and Edge)

Linux (Chrome)

What happens without a certificate

Zero-login access

Multiple devices

Agent certificates

For Developers

PKI hierarchy

Certificate generation

PKCS12 compatibility flags

nginx mTLS enforcement

Certificate help page

Client certificate headers

Certificate rotation

Idempotent installation

File layout

Source files

Quick Reference

PKI hierarchy

File permissions

nginx directives

OpenSSL commands

API endpoints

Related documentation