Certificate Thumbprints

Pre-register client certificates using thumbprint verification.

What is a Thumbprint?

A certificate thumbprint is a SHA-256 hash of the certificate’s DER encoding, providing a unique identifier:

Thumbprint Format

Property	Value
Algorithm	SHA-256
Length	64 hexadecimal characters
Format	Lowercase hex or colon-separated

Example formats:

# Continuous hex (Mantis default)
abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

# Colon-separated (OpenSSL default)
AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:...

Pre-Registration Workflow

Overview

Pre-registration allows you to register a thumbprint before the agent connects:

Step-by-Step

1. Generate certificate on target server
2. Extract thumbprint
3. Pre-register in Mantis
4. Start Tarsus agent
5. Agent auto-approved

Generating Thumbprints

On Target Server

Tarsus automatically generates a certificate on first run if one is not configured. To generate a certificate manually:

# Generate new certificate using OpenSSL
openssl req -new -x509 -nodes \
  -keyout /etc/tarsus/key.pem \
  -out /etc/tarsus/cert.pem \
  -days 365 \
  -subj "/CN=$(hostname)/O=Mantis Agent"

# Get the thumbprint
tarsus show-thumbprint
# Output: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

From Existing Certificate

# Get thumbprint from certificate file
openssl x509 -noout -fingerprint -sha256 -in /etc/tarsus/cert.pem

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

# Convert to lowercase continuous format
openssl x509 -noout -fingerprint -sha256 -in /etc/tarsus/cert.pem | \
  sed 's/SHA256 Fingerprint=//' | tr -d ':' | tr '[:upper:]' '[:lower:]'

# Output:
# abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Via Tarsus Command

# Show current certificate thumbprint
tarsus show-thumbprint

# Output:
# abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Pre-Registering Thumbprints

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Pre-Register Client                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Client Name *                                              │
│  [web-prod-01                             ]                 │
│                                                             │
│  Certificate Thumbprint *                                   │
│  [abcdef1234567890abcdef1234567890abcdef12]                │
│  [34567890abcdef1234567890abcdef1234567890]                │
│  64 hexadecimal characters (SHA-256)                        │
│                                                             │
│  Hostname (optional)                                        │
│  [web-prod-01.example.com                 ]                 │
│  For documentation purposes                                 │
│                                                             │
│  Target Environment (optional)                              │
│  [None (target created without environment)          ▼]     │
│  The environment for the automatically created target       │
│                                                             │
│                              [Cancel]  [Pre-Register]       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via CLI

# Basic pre-registration
mantisctl cert pre-register --name "web-prod-01" \
  --thumbprint "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"

# With hostname
mantisctl cert pre-register --name "web-prod-01" \
  --thumbprint "abcdef1234..." \
  --hostname "web-prod-01.example.com"

# Calculate the thumbprint from a certificate file
mantisctl cert pre-register --name "web-prod-01" \
  --from-cert /path/to/client.crt

Pre-Registration Status

Pre-registered entries immediately receive Approved status. A pre-registered client that has not yet connected will show “Never” for Last Seen:

┌─────────────────────────────────────────────────────────────┐
│  Registrations                                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┬───────────────┬─────────────────────┐  │
│  │ Client         │ Status        │ Last Seen           │  │
│  ├────────────────┼───────────────┼─────────────────────┤  │
│  │ web-prod-01    │ ● Approved    │ Never               │  │
│  │ web-prod-02    │ ● Approved    │ 2 min ago           │  │
│  │ api-prod-01    │ ○ Pending     │ 5 min ago           │  │
│  └────────────────┴───────────────┴─────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Note

There is no distinct “Pre-Reg” status. Pre-registration immediately creates an Approved registration. You can identify clients that have not yet connected by their Never Last Seen timestamp.

Status Transitions

Note

Pre-registration skips the Pending state entirely — the registration is created as Approved immediately. Agents that connect without a matching pre-registration start as Pending and require manual approval.

Agent Connection

With Matching Thumbprint

When an agent connects with a pre-registered thumbprint:

# Start agent (certificate already generated)
tarsus run

# Output:
# Connecting to Mantis server...
# Certificate thumbprint: abcdef1234567890...
# Registration found: web-prod-01 (pre-registered)
# Status: Approved
# Ready to receive deployments.

Without Matching Thumbprint

If thumbprint doesn’t match any pre-registration:

# Start agent
tarsus run

# Output:
# Connecting to Mantis server...
# Certificate thumbprint: xyz789...
# No pre-registration found
# Status: Pending (awaiting approval)

Verification

Thumbprint Comparison

Always verify thumbprint through a secure channel:

┌─────────────────────────────────────────────────────────────┐
│  Verify Thumbprint                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Pre-registered thumbprint:                                 │
│  abcdef1234567890abcdef1234567890abcdef1234567890abcdef12   │
│  34567890abcdef1234567890abcdef1234567890                   │
│                                                             │
│  Agent-provided thumbprint:                                 │
│  abcdef1234567890abcdef1234567890abcdef1234567890abcdef12   │
│  34567890abcdef1234567890abcdef1234567890                   │
│                                                             │
│  Result: ✓ Match                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Secure Channel Options

Exchange thumbprints through secure channels:

Channel	Security Level	Use Case
In-person	Highest	High-security environments
Phone call	High	Verbal verification
Encrypted email	Medium	Documentation trail
Secure chat	Medium	Quick verification
Configuration management	Medium	Automated deployments

Caution

Never exchange thumbprints via unencrypted email or public channels.

Bulk Pre-Registration

Multiple Servers

# Pre-register multiple servers from a file
cat servers.txt | while read name thumbprint; do
  mantisctl cert pre-register --name "$name" --thumbprint "$thumbprint"
done

# servers.txt format:
# web-prod-01 abcdef1234567890...
# web-prod-02 fedcba0987654321...
# api-prod-01 123456abcdef7890...

From Infrastructure Automation

# Ansible example
- name: Pre-register Mantis client
  uri:
    url: '{{ mantis_url }}/api/v1/registrations/pre-register'
    method: POST
    headers:
      Authorization: 'Bearer {{ mantis_token }}'
    body_format: json
    body:
      client_name: '{{ inventory_hostname }}'
      thumbprint: '{{ tarsus_thumbprint }}'

Via CI/CD Pipeline

# GitHub Actions example
- name: Pre-register with Mantis
  run: |
    mantisctl cert pre-register --name "${{ matrix.server }}" \
      --thumbprint "${{ secrets[format('{0}_THUMBPRINT', matrix.server)] }}"

Managing Pre-Registrations

View Pre-Registrations

# List approved client registrations (pre-registered clients are approved)
mantisctl cert list --status approved

# Show details for one registration (by ID or thumbprint prefix)
mantisctl cert show <registration-id>

Removing a Pre-Registration

# Revoke a pre-registration before or after the agent connects
mantisctl cert revoke <registration-id> \
  --reason "Server deployment cancelled"

Note

There is no cert update subcommand. To change a pre-registration (for example its name or thumbprint), revoke the existing entry and pre-register a new one.

Security Considerations

Thumbprint Binding

Thumbprints cryptographically bind to the certificate:

Property	Guarantee
Uniqueness	Each certificate has unique thumbprint
Integrity	Any change produces different thumbprint
Non-repudiation	Agent proves possession of private key

Certificate Storage

Ensure the agent’s private key is secured:

# Secure permissions on Tarsus certificate
chmod 600 /etc/tarsus/key.pem
chmod 644 /etc/tarsus/cert.pem
chown root:root /etc/tarsus/*.pem

Key Compromise

If a private key is compromised:

1. Revoke the registration immediately
2. Generate new certificate on the server
3. Pre-register new thumbprint
4. Investigate the compromise

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

# Pre-register new thumbprint
mantisctl cert pre-register --name "compromised-server" \
  --thumbprint "new-thumbprint-here"

Comparison: Thumbprint vs Token

Aspect	Thumbprint	Token
Security	Higher (per-agent)	Lower (shared secret)
Setup effort	Higher	Lower
Automation	More complex	Simpler
Revocation scope	Single agent	All using token
Best for	High security	Bulk deployment

When to Use Thumbprints

• Production environments
• High-security requirements
• Compliance requirements
• Individual server tracking

When to Use Tokens

• Development environments
• CI/CD pipelines
• Large-scale deployments
• Ephemeral infrastructure

Best Practices

1. Secure Thumbprint Exchange

Always use secure channels:

# Generate thumbprint on server
tarsus show-thumbprint > /tmp/thumbprint.txt

# Securely transfer (example using SSH)
scp /tmp/thumbprint.txt admin@mantis:/tmp/

# Clean up
rm /tmp/thumbprint.txt

2. Document Pre-Registrations

Maintain records of:

• Who requested the pre-registration
• Purpose of the server
• When it should be reviewed
• Associated tickets/approvals

3. Regular Cleanup

Remove stale pre-registrations:

# List approved registrations and identify stale entries
mantisctl cert list --status approved --verbose

# Revoke stale entries individually (by ID or thumbprint prefix)
mantisctl cert revoke <registration-id> \
  --reason "Pre-registration expired - server not provisioned"

4. Verify Before Production

Always verify thumbprint for production servers:

# On the server
tarsus show-thumbprint

# Compare with pre-registered value in Mantis
mantisctl cert show <registration-id>

Troubleshooting

Thumbprint Mismatch

Cause: Certificate was regenerated

Solution:

1. Get new thumbprint from server
2. Update or re-create pre-registration
3. Ensure certificate wasn’t inadvertently regenerated

# Check current thumbprint
tarsus show-thumbprint

# Update pre-registration if needed (revoke + re-pre-register)
mantisctl cert revoke <registration-id>
mantisctl cert pre-register --name "server-name" --thumbprint "new-thumbprint"

Invalid Thumbprint Format

Cause: Wrong format or characters

Solution:

# Ensure lowercase hex, no colons, 64 characters
echo "ABCDEF12:34:56..." | tr -d ':' | tr '[:upper:]' '[:lower:]'

# Verify length
thumbprint="abcdef..."
echo ${#thumbprint}  # Should be 64

Pre-Registration Not Found

Cause: Thumbprint wasn’t pre-registered or was cancelled

Solution:

1. Check if pre-registration exists
2. Verify thumbprint matches exactly
3. Re-create pre-registration if needed

Agent Connects but Registration Shows Pending

Cause: The agent connected with a thumbprint that does not match any pre-registration, so it was created as a new Pending registration instead.

Solution:

1. Verify the agent’s thumbprint matches the pre-registered value exactly: tarsus show-thumbprint
2. Check that the correct pre-registration exists in Mantis: mantisctl cert list --status approved
3. If the thumbprint has changed (certificate was regenerated), revoke the stale entry and pre-register the new thumbprint
4. Approve the pending registration manually if needed

Pre-Registered Client Not Connecting

Cause: Pre-registered registration was revoked before the agent connected.

Solution:

1. Check the registration status: mantisctl cert list
2. If revoked, create a new pre-registration for the client’s thumbprint

Next Steps

• Registration Tokens - Token-based registration
• Approving Registrations - Manual approval
• Overview - Return to registration overview