SSL-CLM Agent

SSL-CLM Operational Agent

The QCecuring SSL-CLM Agent enables secure, distributed certificate lifecycle execution across your infrastructure.

It runs locally on servers to:

• Integrate with on-prem Certificate Authorities (e.g., MSCA)
• Execute certificate issuance and revocation
• Refresh CA inventory and templates
• Submit PKI snapshots to the SSL-CLM platform
• Maintain periodic heartbeat with the backend
• Execute lifecycle jobs in a pull-based model

The agent does not expose inbound ports and does not store CA private keys.

All operations are executed securely via outbound communication.

---

Supported Platforms

• Windows Server 2016+
• Linux (Ubuntu, RHEL, Debian, SUSE)

---

Prerequisites

• Java 21 or later
• Network access to SSL-CLM backend
• Bootstrap token (for first registration)

Optional (Production):

• mTLS client certificate
• HTTPS-enabled backend
• On-prem CA access (e.g., Microsoft ADCS)

---

Installation

Download the agent from:

Agent Management → Download Agent

Or obtain the JAR file:

ssl-clm-agent-0.0.1-SNAPSHOT.jar

---

Running the Agent

java -jar ssl-clm-agent.jar

When started successfully, the agent:

• Registers using bootstrap token
• Receives a unique agentId
• Begins periodic heartbeat
• Starts polling for lifecycle jobs
• Executes assigned certificate operations

---

First-Time Registration (Bootstrap)

The agent requires a bootstrap token for initial registration.

Example:

java -jar ssl-clm-agent.jar \
  --backend.url=http://localhost:8080 \
  --bootstrap.token=YOUR_BOOTSTRAP_TOKEN

Registration flow:

1. Agent sends bootstrap token to backend
2. Backend validates token
3. Backend issues agent identity + access token
4. Agent stores credentials locally
5. Future communication uses mTLS or issued token

---

Configuration

The agent can be configured via:

• agent.properties
• Environment variables
• Command-line arguments

---

Example Configuration (agent.properties)

backend.url=http://localhost:8080

# Job execution
agent.jobs.fixedDelayMs=10000
agent.heartbeat.fixedDelayMs=30000

# Bootstrap
bootstrap.token=CHANGE_ME

# MSCA Integration (optional)
agent.msca.enabled=true
agent.msca.ca-identifier=corp-ca

# Optional mTLS (recommended in production)
backend.mtls.enabled=false
backend.mtls.client-cert-path=
backend.mtls.client-cert-password=
backend.mtls.ca-cert-path=

logging.level=INFO

---

Environment Variables

export BACKEND_URL=http://localhost:8080
export BOOTSTRAP_TOKEN=your_bootstrap_token

In production environments, use secure secret management for tokens and certificates.

---

Job Execution Model (Pull-Based)

The agent uses a secure pull model:

1. Poll backend for jobs
2. Execute job locally
3. Submit result
4. Update job status

No inbound firewall rules required.

---

Supported Job Types

CA_REFRESH

• Fetch certificates from on-prem CA
• Retrieve templates
• Submit PKI snapshot to backend

ISSUE_CERT

• Receive CSR
• Submit to CA
• Retrieve issued certificate
• Return result to backend

REVOKE_CERT

• Receive serial number
• Execute revocation on CA
• Return revocation result

---

Safe Mode

If:

• mTLS certificate is revoked
• Agent identity is invalid
• Backend returns authorization failure

The agent:

• Stops executing jobs
• Stops heartbeat
• Enters fail-closed state
• Requires re-bootstrap

---

Running as a Service

Windows

Install as a Windows service using NSSM or similar.

Start-Service QCecuring-SSL-CLM-Agent
Stop-Service QCecuring-SSL-CLM-Agent
Get-Service QCecuring-SSL-CLM-Agent

---

Linux (systemd)

sudo systemctl start ssl-clm-agent
sudo systemctl status ssl-clm-agent
sudo systemctl enable ssl-clm-agent

---

Communication Model

The agent communicates with backend via:

• HTTPS (default)
• Optional mTLS (recommended in production)
• JWT-based authentication after bootstrap

Default intervals:

• Heartbeat: 30 seconds
• Job polling: 10 seconds
• Health check: 5 minutes

---

Verification

To verify the agent is running:

• Ensure process is active
• Confirm Registered Agents page shows status ACTIVE
• Trigger a CA_REFRESH job and confirm execution
• Monitor job logs in dashboard

---

Security Best Practices

• Enable HTTPS
• Enable mTLS in production
• Rotate bootstrap tokens
• Restrict outbound network access
• Deploy one agent per on-prem CA
• Monitor job execution logs

---

Next Steps

• Configure CA integration
• Create certificate templates
• Test issuance workflow
• Test revocation workflow
• Enable scheduled CA refresh jobs