mTLS Authentication

mTLS Authentication

Mutual TLS (mTLS) provides bidirectional authentication between Thorax and Tarsus agents.

Overview

What is mTLS?

Mutual TLS extends standard TLS by requiring both parties to present certificates:

Benefits

Benefit	Description
Mutual trust	Both parties verify each other
Strong authentication	Cryptographic proof of identity
No shared secrets	Private keys never transmitted
Certificate-based	Integrates with PKI infrastructure

Authentication Modes

Mantis supports two mTLS authentication modes:

Mode	CA Required	Complexity	Use Case
Thumbprint	No	Low	Quick setup, isolated agents
CA-Signed	Yes	Medium	Centralized management, PKI

Thumbprint Mode

Agents use self-signed certificates verified by thumbprint:

┌─────────────────────────────────────────────────────────────┐
│  Thumbprint Mode Authentication                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Agent generates self-signed certificate                │
│  2. Admin registers thumbprint in Mantis                   │
│  3. Agent connects with certificate                        │
│  4. Thorax verifies certificate matches thumbprint         │
│                                                             │
│  Security: TLS validates cert, app validates thumbprint    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

See Thumbprint Mode for configuration.

CA-Signed Mode

Agents use certificates signed by a trusted CA:

┌─────────────────────────────────────────────────────────────┐
│  CA-Signed Mode Authentication                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. CA issues client certificates                          │
│  2. Thorax trusts the CA                                   │
│  3. Agent connects with CA-signed certificate              │
│  4. TLS layer validates CA signature                       │
│  5. Auto-approved — CA-signed clients accepted without     │
│     a separate thumbprint lookup                           │
│                                                             │
│  Security: TLS validates CA chain; PKI trust is sufficient │
│                                                             │
└─────────────────────────────────────────────────────────────┘

See CA-Signed Mode for configuration.

Thorax Configuration

Enable mTLS

[tls]
auth_mode = "thumbprint"  # or "ca_signed"

# Server certificate
cert_path = "/etc/mantis/certs/thorax.crt"
key_path = "/etc/mantis/certs/thorax.key"

# CA certificate (required for ca_signed mode)
ca_cert_path = "/etc/mantis/certs/ca.crt"

Environment Variables

Variable	Description	Default
MANTIS_TLS_AUTH_MODE	Authentication mode	thumbprint
MANTIS_TLS_CERT_PATH	Server certificate	-
MANTIS_TLS_KEY_PATH	Server private key	-
MANTIS_TLS_CA_CERT_PATH	CA certificate	-

Note

TLS is always enabled in Thorax and client certificates are always required (mTLS is mandatory). There is no enabled toggle.

Tarsus Configuration

Client Certificate Setup

[tls]
cert_path = "/etc/tarsus/cert.pem"
key_path = "/etc/tarsus/key.pem"

# Server verification
ca_cert_path = "/etc/tarsus/ca.crt"

Environment Variables

Variable	Description	Default
MANTIS_TLS_CERT_PATH	Client certificate	-
MANTIS_TLS_KEY_PATH	Client private key	-
MANTIS_TLS_CA_CERT_PATH	CA certificate	-
MANTIS_TLS_SERVER_THUMBPRINT	Expected Thorax server cert thumbprint (SHA-256 hex); required with auto-generated certs in thumbprint mode	-

Connection Flow

Complete mTLS Handshake

Connection States

State	Description	Action Required
TLS Established	mTLS handshake complete	None
Authenticating	Verifying registration	Wait
Authenticated	Agent approved	Ready for commands
Rejected	Invalid certificate	Check registration

Certificate Validation

Server-Side Validation

Thorax validates client certificates:

┌─────────────────────────────────────────────────────────────┐
│  Thorax Validation Steps                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. TLS handshake - certificate format valid               │
│  2. Signature check - certificate properly signed          │
│  3. Expiration check - certificate not expired             │
│  4. CA check: if client cert is CA-signed → auto-approved  │
│     (thumbprint steps below are skipped; an audit record   │
│      is written to Mandible non-blocking)                  │
│  5. Thumbprint lookup - registered in Mantis               │
│     (thumbprint mode only, or non-CA-signed clients)       │
│  6. Registration status - approved (not pending/revoked)   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Client-Side Validation

Tarsus validates the server certificate:

Check	Purpose	Configurable
Hostname	Prevent MITM	Yes
CA chain	Trusted issuer	Yes
Expiration	Valid cert	No

Note

Server certificate verification cannot be disabled. TLS is always enabled and Tarsus always validates the server certificate (CA chain plus the configured trust_server_thumbprint in thumbprint mode) — there is no verify_server setting.

Registration Integration

Pre-Registration Flow

Pending Approval Flow

Certificate Thumbprints

Thumbprint Extraction

# Get thumbprint from certificate
openssl x509 -in cert.pem -fingerprint -sha256 -noout

# Output:
# SHA256 Fingerprint=AB:CD:EF:12:34:56:78:90:...

# Convert to Mantis format (lowercase, no colons)
openssl x509 -in cert.pem -fingerprint -sha256 -noout | \
  sed 's/SHA256 Fingerprint=//' | tr -d ':' | tr '[:upper:]' '[:lower:]'

Thumbprint Registration

# Pre-register by thumbprint
mantisctl cert pre-register --name "agent-name" \
  --thumbprint "abcdef1234567890..."

# View a registration's details (by registration ID or thumbprint prefix)
mantisctl cert show "agent-registration-id"

Security Considerations

Certificate Security

Aspect	Recommendation
Key length	RSA 2048+ or ECDSA P-256+
Algorithm	SHA-256 or better
Validity	1 year maximum
Storage	Encrypted at rest

Private Key Protection

# Secure private key permissions
chmod 600 /etc/tarsus/key.pem
chown root:root /etc/tarsus/key.pem

# Verify permissions
ls -la /etc/tarsus/key.pem
# Expected: -rw------- root root

Certificate Revocation

When a certificate is compromised:

1. Revoke registration in Mantis
2. Generate new certificate on the agent
3. Register new thumbprint
4. Investigate the compromise

# Revoke compromised agent (by registration ID or thumbprint prefix)
mantisctl cert revoke "<REGISTRATION_UUID>" \
  --reason "Private key compromised"

Troubleshooting

Connection Failures

Certificate not trusted:

# Check CA configuration
openssl verify -CAfile /etc/mantis/certs/ca.crt \
  /etc/tarsus/cert.pem

# Fix: Ensure CA file is correct on both sides

Thumbprint mismatch:

# Get actual thumbprint
tarsus show-thumbprint

# Compare with the registered thumbprint (by registration ID or thumbprint prefix)
mantisctl cert show "agent-registration-id"

# Fix: revoke the stale registration and pre-register the current thumbprint

Certificate expired:

# Check expiration
openssl x509 -in cert.pem -enddate -noout

# Fix: Renew certificate

Diagnostic Commands

# Test mTLS connection
openssl s_client -connect thorax.example.com:50051 \
  -cert /etc/tarsus/cert.pem \
  -key /etc/tarsus/key.pem \
  -CAfile /etc/tarsus/ca.crt

# Check Thorax logs
journalctl -u mantis-thorax -f | grep -i tls

# Check Tarsus logs
journalctl -u tarsus -f | grep -i certificate

Common Errors

Error	Cause	Solution
no client certificate	Agent didn’t send cert	Check Tarsus TLS config
certificate verify failed	CA mismatch	Verify CA file matches
thumbprint not found	Not registered	Pre-register or approve
registration revoked	Agent revoked	Re-register if appropriate
certificate expired	Cert past validity	Renew certificate

Best Practices

1. Use CA-Signed for Production

For production environments:

• Deploy internal CA
• Issue certificates centrally
• Enable automatic renewal

2. Rotate Certificates Regularly

Certificate Type	Rotation Period
Server certificates	Annually
Client certificates	Annually
CA certificate	5-10 years

3. Monitor Certificate Expiry

# Check all certificates
for cert in /etc/mantis/certs/*.crt; do
  echo "$cert:"
  openssl x509 -in "$cert" -enddate -noout
done

4. Secure Private Keys

• Use hardware security modules (HSM) for CA keys
• Encrypt private keys at rest
• Limit access to key files
• Audit key access

5. Log mTLS Events

Monitor for security issues:

• Failed authentication attempts
• Certificate validation errors
• Unusual connection patterns

Next Steps

• Thumbprint Mode - Self-signed certificate setup
• CA-Signed Mode - PKI-based authentication
• Key Rotation - Certificate renewal procedures