Integração QuantumLock para Produtos QCOS
Guia técnico completo para integração do sistema de licenciamento QuantumLock em produtos comerciais SoftQuantus.
📋 Índice
- Visão Geral
- Arquitetura
- Configuração
- Fluxo de Validação
- API Reference
- Exemplos de Código
- Troubleshooting
Visão Geral
O QuantumLock é o sistema de licenciamento da SoftQuantus que protege todos os produtos comerciais (QCOS SDK, CLI, SynapseX, etc.) usando criptografia quântica e pós-quântica.
Características
- Validação Híbrida: Online + offline com grace period
- Criptografia PQC: Suporte a ML-DSA (Dilithium)
- Anti-Rollback: Proteção contra manipulação de data
- Revogação: Lista de revogação em tempo real
- Feature Gating: Controle granular de funcionalidades
Arquitetura
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENTE (End Customer) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ Produto QCOS │ SDK Python / CLI │
│ │ (softqcos-sdk, cli-softqcos)│ │
│ └──────────┬──────────┘ │
│ │ │
│ │ 1. Carrega ~/.softqcos/license.qlicense │
│ │ 2. Valida assinatura (offline) │
│ │ 3. Verifica com API (online) │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ license_loader.py │ Ponto de entrada unificado │
│ │ quantumlock_ │ │
│ │ validator.py │ │
│ └──────────┬──────────┘ │
│ │ │
└─────────────┼───────────────────────────────────────────────────────────────┘
│
│ HTTPS (TLS 1.3)
│ POST /api/v1/licenses/validate
│ Header: X-API-Key (opcional)
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SOFTQUANTUS CLOUD │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ quantumlock.softquantus.com │ │
│ │ │ │
│ │ Endpoints: │ │
│ │ ├── POST /api/v1/licenses/validate → Valida licença │ │
│ │ ├── POST /api/v1/licenses/activate → Ativa nova licença │ │
│ │ ├── GET /api/v1/revocation → Lista de revogações │ │
│ │ └── POST /api/v1/artifacts/issue → Emite LicenseArtifact │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Configuração
Variáveis de Ambiente
# ============================================================================
# QUANTUMLOCK - Configurações de Licenciamento Comercial
# ============================================================================
# API URL do QuantumLock
QUANTUMLOCK_API_URL=https://quantumlock.softquantus.com
# Chave de API (para ISVs, não para end-customers)
QUANTUMLOCK_API_KEY=ql_live_xxxxxxxxxxxxxxxx
# Caminho para arquivo de licença local
QUANTUMLOCK_LICENSE_PATH=~/.softqcos/license.qlicense
# Modo de validação: online, offline, hybrid
QUANTUMLOCK_VALIDATION_MODE=hybrid
# Período de graça (dias) se API inacessível
QUANTUMLOCK_GRACE_PERIOD_DAYS=7
# Exigir assinatura PQC (ML-DSA)
QUANTUMLOCK_REQUIRE_PQC=false
# Anti-rollback
QUANTUMLOCK_ENABLE_ANTI_ROLLBACK=true
QUANTUMLOCK_ANTI_ROLLBACK_PATH=~/.softqcos/.ql_epoch
# Produto
QUANTUMLOCK_PRODUCT_ID=softqcos
QUANTUMLOCK_PRODUCT_SKU=QCOS-PROFESSIONAL
# Cache
QUANTUMLOCK_ENABLE_CACHE=true
QUANTUMLOCK_CACHE_TTL=3600
# Network
QUANTUMLOCK_TIMEOUT=30.0
QUANTUMLOCK_MAX_RETRIES=3
Arquivo de Configuração (quantumlock_config.py)
from licensing.quantumlock_config import QuantumLockConfig, get_config
# Obter configuração singleton
config = get_config()
# Acessar valores
print(config.API_URL) # https://quantumlock.softquantus.com
print(config.VALIDATION_MODE) # hybrid
print(config.GRACE_PERIOD_DAYS) # 7
# Verificar modo
if config.is_hybrid_mode():
print("Usando validação híbrida")
# Encontrar arquivo de licença
license_path = config.get_license_path()
Fluxo de Validação
Modo Hybrid (Recomendado)
┌──────────────┐ ┌─────────────────┐ ┌──────────────────────┐
│ Startup │────▶│ Load License │────▶│ Validate Signature │
│ do App │ │ (arquivo .ql) │ │ (offline, RSA+PQC) │
└──────────────┘ └─────────────────┘ └──────────┬───────────┘
│
▼
┌─────────────────────┐
│ Signature Valid? │
└──────────┬──────────┘
│
┌──────────────┬──────────┴──────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌──────────┐
│ NO │ │ YES │ │ EXPIRED │
│ REJECT │ │ CONTINUE │ │ REJECT │
└────────┘ └────┬─────┘ └──────────┘
│
▼
┌─────────────────────┐
│ Check Online │
│ (API call) │
└──────────┬──────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────────┐
│ API OK │ │ API FAIL │ │ REVOKED │
│ ✅ ALLOW │ │ (timeout) │ │ ❌ REJECT │
└────────────┘ └─────┬──────┘ └────────────────┘
│
▼
┌─────────────────────┐
│ Grace Period? │
│ (7 days default) │
└──────────┬──────────┘
│
┌─────────────┴─────────────┐
│ │
▼ ▼
┌────────────┐ ┌────────────┐
│ IN GRACE │ │ EXPIRED │
│ ⚠️ WARN │ │ ❌ REJECT │
└────────────┘ └────────────┘
Comparativo de Modos
| Modo | Internet | Segurança | Grace Period | Uso |
|---|---|---|---|---|
| online | Sempre | Alta | Não | SaaS |
| offline | Nunca | Média | Não | Air-gapped |
| hybrid | Quando possível | Alta | Sim (7 dias) | Recomendado |
API Reference
POST /api/v1/licenses/validate
Valida uma licença.
Request:
{
"license_key": "QLOCK-XXXX-YYYY-ZZZZ-AAAA",
"end_customer_id": "cliente@empresa.com",
"device_fingerprint": {
"hostname": "workstation-01",
"hostname_hash": "a1b2c3d4..."
}
}
Response (válida):
{
"valid": true,
"end_customer_id": "cliente@empresa.com",
"quantum_verified": true,
"features": ["qcos_basic", "qcos_advanced", "50_qubits", "vqe"],
"expires_at": "2026-12-30T23:59:59Z",
"message": null
}
Response (inválida):
{
"valid": false,
"end_customer_id": "cliente@empresa.com",
"quantum_verified": false,
"features": null,
"expires_at": null,
"message": "License has expired."
}
POST /api/v1/licenses/activate
Ativa uma licença em um dispositivo.
Request:
{
"license_key": "QLOCK-XXXX-YYYY-ZZZZ-AAAA",
"device_fingerprint": {
"hostname": "workstation-01"
},
"product_id": "softqcos"
}
Response:
{
"success": true,
"license": {
"license_key": "QLOCK-XXXX-YYYY-ZZZZ-AAAA",
"product_id": "softqcos",
"sku": "QCOS-PROFESSIONAL",
"features": ["..."],
"expires_at": "2026-12-30T23:59:59Z"
}
}
GET /api/v1/revocation
Lista licenças revogadas.
Response:
{
"epoch": 1704067200,
"revoked_licenses": [
"QLOCK-AAAA-BBBB-CCCC-DDDD",
"QLOCK-EEEE-FFFF-GGGG-HHHH"
]
}
Exemplos de Código
Validação Básica
from licensing import validate_license
# Validar licença
result = validate_license()
if result.valid:
print(f"✅ Licenciado: {result.licensee}")
print(f" Features: {result.features}")
print(f" Expira: {result.expires_at}")
else:
print(f"❌ {result.message}")
sys.exit(1)
Com Arquivo Específico
from licensing import validate_license
result = validate_license(license_file="/path/to/license.qlicense")
Com License Key (Ativação)
from licensing import validate_license
result = validate_license(license_key="QLOCK-XXXX-YYYY-ZZZZ-AAAA")
if result.valid:
print("Licença ativada com sucesso!")
Decorators para Proteção
from licensing import require_license
from licensing.quantumlock_config import ProductFeatures
# Exigir licença válida
@require_license()
def protected_function():
pass
# Exigir feature específica
@require_license(features=[ProductFeatures.VQE])
def vqe_optimization():
pass
# Exigir múltiplas features
@require_license(features=[ProductFeatures.QCOS_ADVANCED, ProductFeatures.QUBITS_50])
def advanced_50qubit_optimization():
pass
Verificação Manual de Features
from licensing import validate_license
from licensing.quantumlock_config import ProductFeatures
result = validate_license()
if result.valid:
if ProductFeatures.VQE in result.features:
print("VQE disponível!")
run_vqe()
else:
print("VQE não incluído no seu plano. Upgrade para Professional.")
Integração no SDK
# qcos_sdk/client.py
from licensing import validate_license, LicenseRequiredError
class QCOSClient:
def __init__(self, api_key: str, license_file: str = None):
self.api_key = api_key
# Validar licença na inicialização
result = validate_license(license_file=license_file)
if not result.valid:
raise LicenseRequiredError(result.message)
self._license = result
self._features = result.features
def optimize(self, qasm: str, max_qubits: int = 10):
# Verificar limite de qubits
if max_qubits > 50 and "unlimited_qubits" not in self._features:
raise FeatureNotLicensedError("Upgrade para Enterprise para >50 qubits")
# ... resto da implementação
Troubleshooting
Erro: "Arquivo de licença não encontrado"
# Verificar se arquivo existe
ls -la ~/.softqcos/license.qlicense
# Ativar licença
softqcosactivate QLOCK-XXXX-YYYY-ZZZZ-AAAA
# Ou configurar path
export QUANTUMLOCK_LICENSE_PATH=/custom/path/license.qlicense
Erro: "Licença expirada"
# Verificar status
softqcosstatus
# Renovar licença em portal.softquantus.com
Erro: "Feature não licenciada"
# Verificar features disponíveis
softqcosstatus --features
# Fazer upgrade em portal.softquantus.com
Erro: "API inacessível" (mas funcionando)
Se está no modo hybrid e dentro do grace period:
⚠️ Licença válida (grace period até 2025-01-15)
Isso é normal. A licença continua válida por 7 dias sem internet.
Verificar Configuração
from licensing.quantumlock_config import get_config
config = get_config()
print(config.to_dict())
🔗 Referências
- PRODUCT_CATALOG.md - Catálogo de produtos
- SKUS_AND_FEATURES.md - SKUs e features
- QuantumLock API Docs - API completa
- Portal SoftQuantus - Comprar/renovar licenças