Documentation SDK Python

SDK Python Sharokey pour le partage sécurisé de secrets avec chiffrement Zero Knowledge. Support async/await avec nommage de méthodes compatible CLI.

Installation

bash

# Installer via pip
pip install sharokey

# Tester l'installation et la connectivité
python -c "
import asyncio
from sharokey import SharokeyClient
client = SharokeyClient(token='votre_token_api_ici')
asyncio.run(client.test())
"

Commandes

Méthode	Équivalent CLI	Description	Exemple
`create()`	`sharokey create`	Créer un secret	`await client.create("motdepasse", 24, 1)`
`list()`	`sharokey list`	Lister les secrets	`await client.list(limit=10, status='active')`
`get()`	`sharokey get`	Obtenir les détails d'un secret	`await client.get('ABC123')`
`delete()`	`sharokey delete`	Expirer un secret (efface le contenu)	`await client.delete('ABC123')`
`stats()`	`sharokey stats`	Afficher les statistiques	`await client.stats()`
`test()`	`sharokey test`	Tester la connectivité	`await client.test()`

Requêtes de Secrets

Méthode	Équivalent CLI	Description	Exemple
`create_request()`	`sharokey create-request`	Créer une requête	`await client.create_request(message="Partager identifiants", secret_expiration_hours=24, request_expiration_hours=48, maximum_views=1, locale="fr")`
`list_requests()`	`sharokey list-requests`	Lister les requêtes	`await client.list_requests(status='active', limit=10)`
`get_request()`	`sharokey get-request`	Obtenir les détails d'une requête	`await client.get_request('abc123token456')`
`delete_request()`	`sharokey delete-request`	Expirer une requête (annule)	`await client.delete_request('abc123token456')`
`request_stats()`	`sharokey request-stats`	Statistiques des requêtes	`await client.request_stats()`

Paramètres

Créer un Secret

Paramètre	Description	Exemple
`content`	Contenu du secret (255 caractères max)	`"Mot de passe base de données : admin123"`
`hours`	Heures d'expiration (1-8760)	`24`
`views`	Vues maximum (1-1000)	`1`
`description`	Description du secret (255 caractères max)	`description="Identifiants BD"`
`message`	Message pour le visualiseur (255 caractères max)	`message="Utiliser avec précaution"`
`password`	Protection additionnelle (4-100 caractères)	`password="secret123"`
`captcha`	Activer la vérification CAPTCHA	`captcha=True`
`otp_email`	OTP par email (format valide)	`otp_email="[email protected]"`
`otp_phone`	OTP par SMS (format international)	`otp_phone="+33674747474"`
`ip_whitelist`	IPs autorisées (255 caractères max)	`ip_whitelist="203.0.113.5,198.51.100.10"`
`geolocation`	Pays autorisés (255 caractères max)	`geolocation="FR,US,DE"`
`attachments`	Liste de chemins de fichiers (10 fichiers, 10MB max)	`attachments=["file1.pdf", "file2.docx"]`

Priorité de Sécurité

Si plusieurs options de sécurité sont spécifiées, seul le niveau le plus élevé est appliqué :
captcha < password < otp_email < otp_phone (le plus élevé)

Exemple : password="secret", captcha=True, otp_phone="+33123456789" → Seul l'OTP téléphone sera utilisé

Configuration

Paramètre	Description	Exemple
`token`	Token API (requis)	`SharokeyClient(token='abcd1234...')`
`timeout`	Timeout de requête en secondes	`SharokeyClient(timeout=60)`

Format de Sortie

Toutes les méthodes retournent des objets JSON (même structure que la sortie JSON CLI).

Exemples

Utilisation de Base

python

import asyncio
from sharokey import SharokeyClient

async def main():
    client = SharokeyClient(token='votre-token')
    
    # Secret simple
    secret = await client.create("Mot de passe base de données : admin123", 24, 1)
    print('URL de partage :', secret['data']['share_url'])
    
    # Avec description et message
    secret2 = await client.create(
        "Identifiants API", 
        48,  # heures
        3,   # vues
        description="Accès API de production",
        message="Valable jusqu'à la fin du projet"
    )
    
    # Protection CAPTCHA
    secret3 = await client.create(
        "Accès serveur", 
        12,  # Heures d'expiration
        1,   # Vues maximum
        captcha=True
    )
    
    # Protection par mot de passe  
    secret4 = await client.create(
        "Données sensibles", 
        6,   # Heures d'expiration
        2,   # Vues maximum
        password="monMotDePasseSecret123"
    )
    
    # Protection OTP email (priorité plus élevée que le mot de passe)
    secret5 = await client.create(
        "Détails bancaires", 
        24,  # Heures d'expiration
        1,   # Vues maximum
        password="sauvegarde",
        otp_email="[email protected]"
    )
    
    # Protection OTP SMS (priorité la plus élevée - remplacera tous les autres)
    secret6 = await client.create(
        "Accès critique", 
        2,   # Heures d'expiration
        1,   # Vues maximum
        password="sauvegarde",
        captcha=True,
        otp_email="[email protected]",
        otp_phone="+33674747474"
    )
    
    # Restriction IP
    secret7 = await client.create(
        "Accès externe", 
        48,  # Heures d'expiration
        10,  # Vues maximum
        ip_whitelist="203.0.113.5,198.51.100.10"
    )
    
    # Restriction géolocalisation
    secret8 = await client.create(
        "Données UE uniquement", 
        72,  # Heures d'expiration
        5,   # Vues maximum
        geolocation="FR,DE,BE,IT,ES"
    )
    
    # Restrictions combinées
    secret9 = await client.create(
        "Accès restreint", 
        24,  # Heures d'expiration
        2,   # Vues maximum
        password="secure123",
        ip_whitelist="203.0.113.100",
        geolocation="FR,US"
    )

asyncio.run(main())

Pièces Jointes de Fichiers

python

import asyncio
from pathlib import Path
from sharokey import SharokeyClient

async def share_files():
    client = SharokeyClient(token='votre-token')
    
    # Pièce jointe unique
    secret = await client.create(
        "Fichiers contrat", 
        48,  # Heures d'expiration
        5,   # Vues maximum
        description="Documents client XYZ",
        attachments=["contrat.pdf"]
    )
    
    # Pièces jointes multiples
    secret2 = await client.create(
        "Bundle projet",
        72,  # Heures d'expiration
        3,   # Vues maximum
        description="Fichiers projet complets",
        attachments=[
            "contrat.pdf",
            "conditions.pdf", 
            "specifications.docx",
            "budget.xlsx"
        ]
    )
    
    # Pièces jointes multiples avec sécurité
    secret3 = await client.create(
        "Rapports confidentiels",
        168,  # Heures d'expiration (1 semaine)
        3,    # Vues maximum
        attachments=[
            "rapport.pdf",
            "donnees.xlsx", 
            "resume.docx"
        ],
        password="rapports2024",
        ip_whitelist="203.0.113.50,198.51.100.25"
    )
    
    print(f"Fichiers partagés : {secret['data']['share_url']}")
    print(f"Pièces jointes : {secret['data']['attachments_count']} fichiers")

asyncio.run(share_files())

Requêtes de Secrets

python

import asyncio
from sharokey import SharokeyClient

async def request_workflow():
    client = SharokeyClient(token='votre-token')
    
    # Créer une requête avec livraison par email (sortie JSON par défaut - réponse API directe)
    request = await client.create_request(
        message="Veuillez partager les identifiants VPN",
        email_to="[email protected]",
        email_reply="[email protected]",
        request_expiration_hours=48,
        secret_expiration_hours=24,
        maximum_views=3,
        locale="fr"
    )
    print('URL de requête :', request['data']['request']['url'])
    
    # Obtenir les détails d'une requête par token (JSON par défaut - réponse API directe)
    request_details = await client.get_request('abc123token456')
    
    # Lister les requêtes avec filtres (JSON par défaut - réponse API directe)
    requests = await client.list_requests(
        status='active',
        limit=20
    )
    
    # Expirer une requête par token (annule et la rend inactive)
    await client.delete_request('abc123token456')
    
    # Voir les statistiques des requêtes (JSON uniquement - réponse API directe)
    stats = await client.request_stats()
    
    # Paramètres de requête : secret_expiration_hours (1-8760), request_expiration_hours (1-8760), maximum_views (1-1000)
    # Champs email : email_to et email_reply (format email valide requis)
    # Locale : "fr" ou "en" - définit la langue de l'email lors de l'envoi de notifications

asyncio.run(request_workflow())

Gestion

python

import asyncio
from sharokey import SharokeyClient

async def management_examples():
    client = SharokeyClient(token='votre-token')
    
    # Lister tous les secrets
    all_secrets = await client.list()
    
    # Lister avec filtres
    filtered = await client.list(
        status='active',
        creator='[email protected]',
        limit=20
    )
    
    # Sortie JSON (par défaut)
    secrets = await client.list(limit=5)
    # Sortie : {"success": true, "data": {"items": [{"slug": "ABC123", "maximum_views": 1, ...}]}}
    
    # Obtenir les détails d'un secret
    secret = await client.get('ABC123')
    
    # Expirer un secret (efface le contenu, force l'expiration)
    await client.delete('ABC123')
    
    # Statistiques
    stats = await client.stats()
    print(f"Total des secrets : {stats['data']['total_secrets']}")
    print(f"Actifs : {stats['data']['active_secrets']}")

asyncio.run(management_examples())

Limites & Contraintes

Contenu & Texte

Contenu du secret : 255 caractères max (avant chiffrement)
Description : 255 caractères max
Message : 255 caractères max
Mot de passe : 4-100 caractères
Liste blanche IP : 255 caractères max (IPs publiques uniquement, séparées par des virgules)
Géolocalisation : 255 caractères max (codes pays ISO)

Pièces Jointes

Fichiers maximum : 10 par secret
Taille totale : 10MB pour tous les fichiers
Formats supportés : Documents, Images, Audio, Vidéo, Archives
Chiffrement : Fichiers chiffrés côté client avant téléchargement

Temps & Accès

Expiration : 1-8760 heures
Vues maximum : 1-1000 vues

Sécurité

Architecture Zero Knowledge

Chiffrement côté client : AES-GCM-256 avec PBKDF2 (10 000 itérations)
Clés divisées : CléA (envoyée au serveur) + CléB (dans le fragment d'URL)
Pas d'accès serveur : Le serveur ne peut pas déchiffrer les secrets
Perfect Forward Secrecy : Les clés ne sont jamais stockées côté serveur

Meilleures Pratiques

Utiliser des temps d'expiration courts pour les données sensibles
Limiter le nombre de vues de manière appropriée
Choisir le niveau de sécurité approprié : OTP téléphone (le plus élevé) > OTP email > mot de passe > CAPTCHA
Combiner avec des restrictions IP et géographiques pour le contrôle d'accès
Seul le niveau de sécurité le plus élevé sera appliqué si plusieurs sont spécifiés

Exigences Python

Python : 3.7+
aiohttp : Pour les requêtes HTTP async
cryptography : Pour les opérations de chiffrement

Utilitaires

Test de Connectivité

python

import asyncio
from sharokey import SharokeyClient

async def test_examples():
    client = SharokeyClient(token='votre-token')
    
    # Test simple (booléen)
    is_connected = await client.test_connection()
    print('Connecté :', is_connected)
    
    # Test détaillé (comme CLI)
    results = await client.test()
    print(f"Tests réussis : {results['passed']}/{results['total']}")
    for detail in results['details']:
        status = "✅" if detail['success'] else "❌"
        print(f"  {status} {detail['name']}: {detail['message']}")
    
    # Vérification de santé
    health = await client.health()
    print('Statut API :', health.get('status', 'inconnu'))
    
    # Informations de configuration
    config = client.get_config()
    print(f"URL API : {config['api_url']}")
    print(f"Timeout : {config['timeout']}s")
    print(f"A un token : {config['has_token']}")

asyncio.run(test_examples())

Gestion d'Erreurs

python

import asyncio
from sharokey import (
    SharokeyClient,
    SharokeyError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    AttachmentError,
    NetworkError
)

async def error_examples():
    client = SharokeyClient(token='votre-token')
    
    try:
        secret = await client.create("secret test", 24, 1)
        print('Succès :', secret['data']['slug'])
    except ValidationError as e:
        print(f"Erreur de validation : {e}")
        # Paramètres invalides (contenu vide, heures/vues hors limites, etc.)
    except AuthenticationError as e:
        print(f"Erreur d'authentification : {e}")
        # Token invalide ou authentification échouée
    except AttachmentError as e:
        print(f"Erreur de fichier : {e}")
        # Fichier non trouvé, trop volumineux, traitement échoué
    except NotFoundError as e:
        print(f"Erreur non trouvé : {e}")
        # Secret ou requête non trouvé
    except NetworkError as e:
        print(f"Erreur réseau : {e}")
        # Timeout, limite de taux, erreurs serveur
    except SharokeyError as e:
        print(f"Erreur Sharokey : {e}")
        # Toute autre erreur API

# Exemples de validation
async def validation_examples():
    client = SharokeyClient(token='votre-token')
    
    try:
        await client.create("", 24, 1)  # Contenu vide
    except ValidationError:
        print("Contenu vide non autorisé")
    
    try:
        await client.create("test", 0, 1)  # Heures invalides
    except ValidationError:
        print("Les heures doivent être entre 1 et 8760")
    
    try:
        await client.create("test", 24, 0)  # Vues invalides
    except ValidationError:
        print("Les vues doivent être entre 1 et 1000")

asyncio.run(error_examples())

Test & Diagnostics

Test de Connectivité

La méthode test() effectue des diagnostics complets côté client :

python

# Test de connectivité complet (6 tests)
results = await client.test()

# Vérification de santé rapide
health = await client.health()

Détails du Test :

Configuration - Valide la présence du token API
Réseau - Teste la connectivité serveur via l'endpoint de santé
Authentification - Vérifie la validité du token avec l'API
Accès Lecture - Teste les permissions de listage des secrets
Accès Écriture - Vérifie les capacités de création de secrets
Statistiques - Teste l'accès à l'endpoint d'analyse

Format de Sortie :

Réponse JSON avec résultats de test détaillés
Indicateurs de succès booléens pour chaque test

Détails de la Méthode Test

La méthode test() effectue des diagnostics complets côté client incluant la vérification de la santé du serveur, la validation de l'authentification, et les vérifications de permissions. Cela va au-delà d'une simple vérification de statut serveur pour garantir une fonctionnalité complète.

Dépannage

Problèmes courants et solutions :

"Token is required" : Initialiser avec SharokeyClient(token='votre-token')
"ValidationError: Content is required" : Fournir une chaîne de contenu non vide
"ValidationError: Hours must be between 1 and 8760" : Utiliser des heures d'expiration valides
"AttachmentError: File not found" : Vérifier que les chemins de fichiers existent et sont lisibles
"AttachmentError: Total attachments size too large" : Garder les fichiers sous 10MB au total
"AuthenticationError: Invalid token" : Vérifier que votre token API est correct et actif
"NetworkError: Request timeout" : Augmenter le timeout ou vérifier la connexion réseau

Ressources Connexes

Documentation CLI - Référence de l'interface en ligne de commande
CDN JavaScript - Version navigateur légère
Structures de Réponse - Documentation complète des réponses JSON
Comparaison de Fonctionnalités - Comparer toutes les librairies Sharokey

Sharokey fournit le SDK Python le plus complet pour le partage sécurisé de secrets avec support async/await complet et chiffrement Zero Knowledge. 🔐

Documentation SDK Python ​

Installation ​

Commandes ​

Requêtes de Secrets ​

Paramètres ​

Créer un Secret ​

Configuration ​

Format de Sortie ​

Exemples ​

Utilisation de Base ​

Pièces Jointes de Fichiers ​

Requêtes de Secrets ​

Gestion ​

Limites & Contraintes ​

Contenu & Texte ​

Pièces Jointes ​

Temps & Accès ​

Sécurité ​

Architecture Zero Knowledge ​

Meilleures Pratiques ​

Exigences Python ​

Utilitaires ​

Test de Connectivité ​

Gestion d'Erreurs ​

Test & Diagnostics ​

Test de Connectivité ​

Dépannage ​

Ressources Connexes ​

Documentation SDK Python

Installation

Commandes

Requêtes de Secrets

Paramètres

Créer un Secret

Configuration

Format de Sortie

Exemples

Utilisation de Base

Pièces Jointes de Fichiers

Requêtes de Secrets

Gestion

Limites & Contraintes

Contenu & Texte

Pièces Jointes

Temps & Accès

Sécurité

Architecture Zero Knowledge

Meilleures Pratiques

Exigences Python

Utilitaires

Test de Connectivité

Gestion d'Erreurs

Test & Diagnostics

Test de Connectivité

Dépannage

Ressources Connexes