Skip to main content

Licensing Flow

This document describes how licensing works between Portal Backend and QuantumLock.

Overview​

QuantumLock is the source of truth for all licensing operations:

  • License generation with quantum signatures
  • Validation and verification
  • Revocation and CRL management
  • Evidence signing (KMS)

Portal Backend acts as a gateway:

  • Maps customers/contracts to entitlements
  • Calls QuantumLock via M2M authentication
  • Stores commercial context (but not license logic)

License Generation Flow​

sequenceDiagram
    autonumber
    participant AF as Admin Frontend
    participant PB as Portal Backend
    participant DB as Portal DB
    participant QSA as QSA (IdP)
    participant QL as QuantumLock

    AF->>PB: POST /api/contracts/{id}/issue-license
    PB->>QSA: Validate admin JWT + roles
    
    PB->>DB: Get contract details
    DB-->>PB: Contract + entitlements
    
    PB->>QSA: POST /oauth2/token (client_credentials)
    QSA-->>PB: M2M access_token
    
    PB->>QL: POST /api/v1/licenses/generate
    Note over PB,QL: {end_customer_id, features, valid_days}
    
    QL->>QL: Generate quantum state
    QL->>QL: Create license key
    QL->>QL: Sign with quantum signature
    
    QL-->>PB: License details
    
    PB->>DB: Store license reference
    PB-->>AF: License issued + download link

License Validation Flow​

sequenceDiagram
    autonumber
    participant App as Customer App
    participant PB as Portal Backend
    participant QL as QuantumLock

    App->>PB: POST /api/licenses/validate
    Note over App,PB: {license_key, customer_id}
    
    PB->>QL: POST /api/v1/licenses/validate
    
    QL->>QL: Parse license key
    QL->>QL: Verify quantum signature
    QL->>QL: Check expiration
    QL->>QL: Check revocation status
    
    QL-->>PB: Validation result
    PB-->>App: {valid: true/false, features}

QuantumLock API​

Generate License​

POST /api/v1/licenses/generate
Authorization: Bearer <m2m_token>
Content-Type: application/json

{
  "end_customer_id": "user@company.com",
  "features": ["premium", "api_access", "analytics"],
  "valid_days": 365,
  "metadata": {
    "contract_id": "contract_abc123",
    "tenant_id": "tenant_xyz"
  }
}

Response (201):

{
  "license_key": "QCOS-41FB-639F-C30B-14E3-6342-7B3E-6426-9320",
  "quantum_signature": "sha3-512:a1b2c3d4e5f6...",
  "end_customer_id": "user@company.com",
  "features": ["premium", "api_access", "analytics"],
  "valid_until": "2026-01-04T00:00:00Z",
  "quantum_verified": true,
  "qcos_fidelity": 0.9876,
  "security_level": "quantum-grade",
  "generated_at": "2025-01-04T10:00:00Z"
}

Validate License​

POST /api/v1/licenses/validate
Authorization: Bearer <m2m_token>
Content-Type: application/json

{
  "license_key": "QCOS-41FB-639F-C30B-14E3-6342-7B3E-6426-9320",
  "end_customer_id": "user@company.com"
}

Response (200):

{
  "valid": true,
  "end_customer_id": "user@company.com",
  "quantum_verified": true,
  "message": "License is valid and quantum-verified"
}

Revoke License​

POST /api/v1/licenses/{license_key}/revoke
Authorization: Bearer <m2m_token>
Content-Type: application/json

{
  "reason": "Customer cancelled subscription"
}

Response (200):

{
  "success": true,
  "license_key": "QCOS-41FB-639F-C30B-14E3-6342-7B3E-6426-9320",
  "revoked_at": "2025-01-04T10:00:00Z",
  "reason": "Customer cancelled subscription",
  "message": "License has been revoked"
}

List Revocations​

GET /api/v1/revocations
Authorization: Bearer <m2m_token>

Response (200):

{
  "revocations": [
    {
      "license_key": "QCOS-XXXX-****",
      "revoked_at": "2025-01-04T10:00:00Z",
      "reason": "Customer cancelled"
    }
  ],
  "total": 1
}

Cryptographic Signing (KMS)​

QuantumLock also provides signing services for Evidence bundles.

Sign​

POST /api/v1/quantum/crypto/sign
Authorization: Bearer <m2m_token>
Content-Type: application/json

{
  "message": "base64-encoded-hash",
  "key_id": "ql_key_prod_001",
  "algorithm": "ML-DSA-65"
}

Response (200):

{
  "signature": "base64-encoded-signature",
  "key_id": "ql_key_prod_001",
  "algorithm": "ML-DSA-65",
  "signed_at": "2025-01-04T10:00:00Z",
  "public_key": "base64-encoded-public-key"
}

Verify​

POST /api/v1/quantum/crypto/verify
Authorization: Bearer <m2m_token>
Content-Type: application/json

{
  "message": "base64-encoded-hash",
  "signature": "base64-encoded-signature",
  "key_id": "ql_key_prod_001",
  "algorithm": "ML-DSA-65"
}

Response (200):

{
  "valid": true,
  "key_id": "ql_key_prod_001",
  "algorithm": "ML-DSA-65",
  "verified_at": "2025-01-04T10:00:00Z"
}

License Key Format​

QCOS-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
 │    └─────────────────────────────────────── Quantum-derived segments
 └───────────────────────────────────────────── Prefix

Each segment is derived from the quantum state, making licenses:

  • Unique - Quantum randomness ensures no collisions
  • Unforgeable - Tied to quantum signature
  • Verifiable - Can be validated online or offline

Security Model​

flowchart TB
    subgraph QuantumLock[QuantumLock - Root of Trust]
        QGen[License Generation]
        QSign[Quantum Signing]
        QVal[Validation Engine]
        QRev[Revocation List]
        Keys[(Signing Keys)]
    end
    
    subgraph Portal[Portal Backend - Gateway]
        Contracts[Contract Logic]
        Entitlements[Entitlements]
        Gateway[API Gateway]
    end
    
    Contracts --> Entitlements
    Entitlements --> Gateway
    Gateway -->|M2M| QGen
    Gateway -->|M2M| QVal
    
    QGen --> QSign
    QSign --> Keys
    QVal --> QRev

Offline Validation​

For air-gapped environments, QuantumLock supports:

  1. Embedded verification - SDK validates signature locally
  2. CRL caching - Revocation list can be synced periodically
  3. License files - Signed .qlicense files for offline use
from quantumlock import LicenseValidator

validator = LicenseValidator(
    public_key="...",  # Embedded public key
    revocation_list="./revocations.crl"  # Cached CRL
)

result = validator.validate_offline(
    license_file="./license.qlicense"
)

Rate Limits​

PlanLicenses/MonthValidation/Minute
Free100100
Startup10,0001,000
Business100,00010,000
EnterpriseUnlimitedUnlimited