clavium-q
SDK Python officiel pour l'API CLAVIUM-Q / CERTROPI — clés post-quantiques (ML-KEM FIPS 203, SLH-DSA FIPS 205) générées depuis une graine QRNG-DI certifiée Device-Independent.
Produit distinct d'Alea-Q — service séparé (api.clavium-q.com), clés kg_silv_/kg_plat_, pas de tier Ivory pour la PQC.
Installation
pip install clavium-q
# Avec déchiffrement local des enveloppes post-quantiques
pip install "clavium-q[verify]"
Démarrage rapide
from clavium_q import ClaviumQClient
# Clé API dans le constructeur ou variable d'env CLAVIUM_Q_API_KEY
client = ClaviumQClient(api_key="kg_plat_xxx")
# ML-KEM (FIPS 203) — encapsulation de clé
kp = client.platinum.mlkem_keygen(param_set="ML_KEM_768")
print(kp.ek, kp.dk)
encaps = client.platinum.mlkem_encaps(ek=kp.ek)
print(encaps.shared_key, encaps.ciphertext)
# SLH-DSA (FIPS 205) — génération de clé, signature, vérification
sig_kp = client.silver.slhdsa_keygen(param_set="SLH_DSA_SHAKE_256s")
signed = client.silver.slhdsa_sign(sk=sig_kp.sk, message="document à signer")
verified = client.silver.slhdsa_verify(
pk=sig_kp.pk, signature=signed.signature, message="document à signer",
)
print(verified.valid) # True — ne lève pas d'exception si False
Authentification
# Option 1 — clé dans le constructeur
client = ClaviumQClient(api_key="kg_plat_xxx")
# Option 2 — variable d'environnement
import os
os.environ["CLAVIUM_Q_API_KEY"] = "kg_plat_xxx"
client = ClaviumQClient()
Le tier est détecté automatiquement depuis le préfixe de la clé (kg_silv_ / kg_plat_) :
client = ClaviumQClient(api_key="kg_plat_xxx")
print(client.tier) # "platinum"
Provisioning : les clés kg_* sont attribuées manuellement — pas d'auto-inscription. Contactez le support CERTROPI pour un accès.
Tiers disponibles
| Tier | Source de la graine | Certification |
|---|---|---|
| Platinum | Ordinateur quantique réel | Device-Independent |
| Silver | DRBG seedé quantique | Seed quantique |
Aucun tier gratuit/self-service pour la PQC (contrairement à Alea-Q).
Post-quantique — ML-KEM (FIPS 203)
Disponible sur Silver et Platinum (client.silver.* / client.platinum.*, mêmes méthodes).
kp = client.platinum.mlkem_keygen(param_set="ML_KEM_768")
print(kp.ek, kp.dk)
encaps = client.platinum.mlkem_encaps(ek=kp.ek)
print(encaps.shared_key, encaps.ciphertext)
# Decaps est une opération LOCALE (le serveur ne voit jamais dk) —
# nécessite l'extra 'verify' : pip install 'clavium-q[verify]'
from clavium_q import mlkem_decaps
shared_key = mlkem_decaps(kp.dk, encaps.ciphertext, param_set=kp.param_set)
assert shared_key.hex() == encaps.shared_key # même secret des deux côtés
Post-quantique — SLH-DSA (FIPS 205)
Seule la génération de clé (slhdsa_keygen()) consomme une graine QRNG-DI. slhdsa_sign() / slhdsa_verify() sont des opérations crypto pures côté serveur sur des clés déjà fournies par le client — chaque appel fait un round-trip réseau, mais aucun des deux n'entame de quota d'entropie.
sig_kp = client.platinum.slhdsa_keygen(param_set="SLH_DSA_SHAKE_256s")
print(sig_kp.sk, sig_kp.pk)
signed = client.platinum.slhdsa_sign(
sk=sig_kp.sk,
message="document à signer",
param_set="SLH_DSA_SHAKE_256s",
)
print(signed.signature, signed.sig_size)
verified = client.platinum.slhdsa_verify(
pk=sig_kp.pk,
signature=signed.signature,
message="document à signer",
param_set="SLH_DSA_SHAKE_256s",
)
print(verified.valid)
Fichiers volumineux (sign_file / verify_file)
message/message_b64 sont bornés en taille (protection mémoire) — pour un fichier volumineux, utiliser les variantes multipart :
with open("document.pdf", "rb") as f:
signed = client.platinum.slhdsa_sign_file(sk=sig_kp.sk, file=f, filename="document.pdf")
with open("document.pdf", "rb") as f:
verified = client.platinum.slhdsa_verify_file(
pk=sig_kp.pk, signature=signed.signature, file=f, filename="document.pdf",
)
Livraison sécurisée de clé privée (Platinum, recipient_pk)
Pour ne jamais faire transiter une clé privée en clair, mlkem_keygen() et slhdsa_keygen() acceptent (Platinum uniquement) un recipient_pk — la clé privée générée revient alors enveloppée (ML-KEM + AES-256-GCM + signature SLH-DSA) dans .envelope au lieu d'être renvoyée en clair dans .dk / .sk :
import base64
from clavium_q import mlkem_decaps
kp = client.platinum.slhdsa_keygen(recipient_pk=my_mlkem_pubkey_hex)
if kp.envelope:
# kp.sk est vide — la clé réelle est dans kp.envelope["encrypted_payload"],
# chiffrée pour my_mlkem_pubkey_hex. my_mlkem_dk = dk ML-KEM du
# destinataire (généré localement, jamais transmis au serveur) — la
# décapsulation reste locale, le serveur ne voit jamais ni my_mlkem_dk
# ni le secret déchiffré.
#
# ATTENTION : les champs de l'enveloppe (ciphertext, encrypted_payload,
# nonce, signature, certropi_pk) sont en BASE64 — contrairement à
# dk/ek/shared_key (mlkem_keygen()/mlkem_encaps()) qui sont en HEX.
ciphertext = base64.b64decode(kp.envelope["ciphertext"])
shared_key = mlkem_decaps(my_mlkem_dk, ciphertext, param_set="ML_KEM_768")
# shared_key (32 octets) est la clé AES-256-GCM utilisée pour chiffrer
# kp.envelope["encrypted_payload"] (nonce en base64 lui aussi) —
# déchiffrement AES-GCM restant à la charge de l'appelant, non fourni
# par ce SDK à ce jour.
Génération + signature PQC entièrement locales (conformité ANSSI-PG-083)
Les fonctions ci-dessus (mlkem_keygen(), slhdsa_keygen(), slhdsa_sign()) génèrent la clé côté serveur puis la transmettent (même chiffrée via recipient_pk, la clé existe brièvement côté Certropi). Pour un contexte exigeant que la clé privée ne soit jamais générée ni transmise par un tiers (ANSSI-PG-083 §2.3.1 RègleArchiGénAléa, Annexe A.4.2), clavium_q.pqc_local assemble la clé entièrement sur ce poste :
pip install "clavium-q[local]" # cryptography>=47.0.0 + slh-dsa + alea-q
from alea_q import AleaQClient # fournisseur d'entropie — PAS clavium_q
from clavium_q import mlkem_keygen_local, slhdsa_keygen_local, slhdsa_sign_local
alea = AleaQClient(api_key="sk_plat_xxx") # clé Alea-Q, pas clavium-q
# ML-KEM — dk ne quitte JAMAIS cette fonction
kp = mlkem_keygen_local(alea.platinum, param_set="ML_KEM_768")
print(kp.ek_hex()) # clé publique, partageable
print(kp.dk_hex()) # clé privée — reste ici, jamais envoyée nulle part
# SLH-DSA — sk ne quitte JAMAIS ce process, ni au keygen ni au sign
sig_kp = slhdsa_keygen_local(alea.platinum, param_set="SLH_DSA_SHAKE_256s")
signature = slhdsa_sign_local(sig_kp.sk, b"message a signer", param_set="SLH_DSA_SHAKE_256s")
Ce que fait réellement ce module : chaque graine certifiée Alea-Q (entropie DI-certifiée Bell-CHSH) est mélangée localement avec os.urandom() (XOR) avant d'être utilisée — conformité à l'exigence ANSSI de combiner plusieurs sources d'aléa via un retraitement local, pas une simple relocalisation du calcul. mlkem_keygen_local() utilise pyca/cryptography (MLKEM768PrivateKey.from_seed_bytes(), même mécanisme que mlkem_decaps() ci-dessus) ; slhdsa_keygen_local()/slhdsa_sign_local() utilisent le package slh-dsa, exactement le même moteur crypto que le serveur QRNG-DI.
Différence avec les fonctions distantes : alea.platinum/alea.silver (package alea-q, PAS clavium_q) ne fournit QUE de l'entropie brute — jamais de clé. Ces fonctions locales ne sollicitent jamais api.clavium-q.com, quel que soit le tier.
slhdsa_sign_local() ne prend même pas de client en paramètre — c'est structurellement impossible pour elle de faire un appel réseau.
Facturation : ces fonctions appellent l'endpoint /v1/{tier}/generate générique (tarif plein), pas kyber/keygen/slhdsa/keygen (tarif "produit" avec remise — 256 bits facturés pour 512/768 consommés). mlkem_keygen_local() facture donc 2× le tarif de mlkem_keygen() distant, slhdsa_keygen_local() 3×. Choix délibéré, pas une inefficacité à corriger : le mode local vend une garantie que le mode distant ne peut offrir à aucun prix (la clé n'est jamais générée ni transmise par un tiers) — c'est un service distinct, facturé en conséquence. slhdsa_sign_local() reste gratuit en bits dans les deux cas (signer ne consomme pas de graine QRNG-DI, ni en local ni à distance).
Context manager
with ClaviumQClient(api_key="kg_plat_xxx") as client:
kp = client.platinum.mlkem_keygen()
Client asynchrone
import asyncio
from clavium_q import AsyncClaviumQClient
async def main():
async with AsyncClaviumQClient(api_key="kg_plat_xxx") as client:
kp = await client.platinum.mlkem_keygen()
print(kp.ek, kp.dk)
asyncio.run(main())
Gestion des erreurs
from clavium_q import ClaviumQClient
from clavium_q.exceptions import AuthenticationError, BackendUnavailable, PermissionError
client = ClaviumQClient()
try:
kp = client.platinum.mlkem_keygen()
except BackendUnavailable as e:
print(f"Source d'entropie indisponible — réessayer dans {e.retry_after}s")
except AuthenticationError:
print("Clé API invalide")
except PermissionError:
print("Tier insuffisant, ou abonnement suspendu/expiré")
Configuration
| Variable d'env | Description | Défaut |
|---|---|---|
CLAVIUM_Q_API_KEY |
Clé API | — |
CLAVIUM_Q_BASE_URL |
URL de base de l'API | https://api.clavium-q.com |
CLAVIUM_Q_TIMEOUT |
Timeout HTTP en secondes | 60 |
CLAVIUM_Q_MAX_RETRIES |
Tentatives automatiques sur échec transitoire | 2 |
Retry automatique
CLAVIUM_Q_MAX_RETRIES (ou max_retries= au constructeur de ClaviumQClient/
AsyncClaviumQClient) déclenche un nouvel essai uniquement sur un échec
transitoire :
- Erreur réseau (timeout, connexion refusée, DNS…)
RateLimitError(429 rate-limit)BackendUnavailable(503 — backend QPU temporairement indisponible)ServerError(5xx)
Jamais retenté (échec déterministe — un nouvel essai identique échouerait
pareil) : AuthenticationError, PermissionError, ValidationError, et
QuotaExceeded (429 quota applicatif — distinct du rate-limit malgré
le même code HTTP : un quota ne se réinitialise pas en quelques secondes).
Backoff exponentiel (ou Retry-After du serveur si fourni), plafonné à
30 secondes dans tous les cas. max_retries=0 désactive le retry.
Développement
pip install -e ".[dev]"
# Suite de tests (mock HTTP via respx — aucun accès réseau requis)
pytest
# Tests contre l'API réelle (marqués `smoke`, nécessitent CLAVIUM_Q_API_KEY
# et un accès réseau — exclus par défaut)
pytest -m smoke
Licence
Propriétaire — CERTROPI © 2026
Metadata
Release files for clavium-q 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clavium_q-0.3.0.tar.gz | 35.2 kB | Without provenance | Details for clavium_q-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clavium_q-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for clavium_q-0.3.0-py3-none-any.whl |
Total release size: 62.3 kB
Release files / clavium_q-0.3.0.tar.gz
| Download URL | clavium_q-0.3.0.tar.gz |
|---|---|
| Size | 35.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0247a1382a716aaa91a5b2466f89854be9f5e614ab3b4c4910808822287006f1
|
|
BLAKE2b-256 checksum How to use checksums |
4a6f5d8fde35f72b52c7f1fa607d8bae9b699dd51321fa8807c46b9421b18132
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / clavium_q-0.3.0-py3-none-any.whl
| Download URL | clavium_q-0.3.0-py3-none-any.whl |
|---|---|
| Size | 27.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
83641ad7deb49303847ff4a8f4f4b9e1d11bcd6ad139b2f73bac4b476e1484b2
|
|
BLAKE2b-256 checksum How to use checksums |
5d4b141661d0fcb019779fce6fac52dbdc56f16ad9bbac8532f90c5bdef6eb9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for clavium-q 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.