PKI and Fleet Licensing

LOGAR implements a hierarchical, cryptographically enforced dynamic PKI architecture that seamlessly manages machine authentication, mutual TLS transport security, and enterprise seat licensing.

1. Cryptographic Hierarchy

graph TD
    ROOT[Master Root CA<br/>logar.eibl.tech<br/>RSA-4096 / SHA-256]
    SUB[Subordinate CA<br/>LOGAR Server Hub<br/>RSA-4096 / SHA-256]
    SRV[Server TLS Certificate<br/>Port 9443 mTLS Listener]
    CLI_WIN[Client Cert: Win_Client<br/>CN: win-dc-01.corp.internal]
    CLI_LIN[Client Cert: Linux_Client<br/>CN: db-node-01.corp.internal]

    ROOT -->|Signs with custom OID_LOGAR_SEATS| SUB
    SUB -->|Issues on first run| SRV
    SUB -->|Issues on /api/client/enroll| CLI_WIN
    SUB -->|Issues on /api/client/enroll| CLI_LIN

2. Custom Enterprise X.509 OIDs

LOGAR embeds license metadata directly into the Subordinate CA certificate X.509 extensions under enterprise OID prefix 1.3.6.1.4.1.59999.1:

OID	Constant Name	Description	Example Value
`1.3.6.1.4.1.59999.1.1`	`OID_LOGAR_SEATS`	Maximum approved forwarder seat quota	`100`
`1.3.6.1.4.1.59999.1.2`	`OID_LOGAR_LICENSE_ID`	Unique enterprise license identifier	`LIC-A1B2C3D4E5F6`
`1.3.6.1.4.1.59999.1.3`	`OID_LOGAR_ISSUER_URL`	WebSocket authority endpoint	`wss://logar.eibl.tech/ws/license`

When the LOGAR server loads its certificate chain, it parses these custom extensions using cryptography.x509 and dynamically enforces the extracted seat limit in its SQLite database (config.max_seats).

3. Bootstrap `.lic` Packages

To initialize a new server hub without manual key transfers, the Master Authority issues a Bootstrap .lic Package (OpenPGP-encrypted JSON envelope):

Master Root CA Certificate: Installs authority trust anchor.
Dedicated Communication Keypair: Mutual TLS credentials used strictly for communicating with the Master Authority.
Sub-CA CSR Template: Pre-configured Subject Distinguished Names and assigned enterprise tenant.
Endpoint Coordinates: Pre-configured WebSocket URI (wss://logar.eibl.tech/ws/license).

Importing a `.lic` Package

CLI: python src/Server.py --import-lic <package.lic>
WebUI: Navigate to 📜 Sub-CA & Licensing tab \rightarrow Drag-and-drop or paste .lic file.

Upon import, the server hub connects to the Master Authority over WebSocket, submits its local Sub-CA CSR, verifies hardware fingerprints, receives the signed certificate, and immediately activates its mTLS listeners.

4. In-Flight Watchdog & Hot SSLContext Reloading

The server hub runs a continuous background watchdog coroutine (cert_validity_watchdog, running every 12 hours):

Checks the expiration date of ca.crt and server.crt.
If remaining validity is less than 30 days:
- Initiates automated certificate renewal with the Master License Authority.
- Replaces certificate files atomically on disk.
- Dynamically reloads the active ssl.SSLContext in-memory.
Active mTLS client connections and log streams remain completely uninterrupted (Zero Downtime).

5. WebUI Sub-CA & Licensing Dashboard

The Server Hub WebUI includes a dedicated 📜 Sub-CA & Licensing management tab:

Authority Connection Badge: Real-time status indicator of Master Authority WebSocket connection.
Hardware Fingerprint: Machine binding fingerprint displayed for license validation.
Seat Progress Gauge: Visual representation of active seats leased vs. maximum quota.
Interactive Actions:
- Export .lic Request: Downloads a signed request bundle for air-gapped environments.
- View & Copy CA CSR: Displays the current Subordinate CA CSR for external signing.
- Sync & Renew via WebSocket: Triggers immediate upstream synchronization and seat expansion.