🔐 Signatures cryptographiques de blocs

Signez vos blocs pour garantir leur authenticité et non-répudiation

📦 Package NPM @sowasit/signer 📚 API Reference

Introduction

SoWasIt vous permet de signer cryptographiquement vos blocs pour garantir leur authenticité et leur non-répudiation. En utilisant une infrastructure à clés publiques (PKI) avec des algorithmes ECDSA P-256, vous pouvez prouver que c'est bien votre organisation qui a créé un bloc spécifique.

💡 Cas d'usage :

Conformité réglementaire (signature électronique qualifiée)
Preuve légale de création de données
Audit et traçabilité renforcée
Non-répudiation des transactions

Cycle de vie d'une clé

1️⃣ Génération de token d'enrôlement → Le propriétaire de la chaîne génère un token pour un partenaire

2️⃣ Génération de paire de clés → Le partenaire utilise le CLI pour créer ses clés ECDSA

3️⃣ Enregistrement de la clé publique → Le partenaire envoie sa clé publique à SoWasIt

4️⃣ Certification → Le partenaire imprime, signe et uploade le document de certification

5️⃣ Vérification → Le propriétaire de la chaîne vérifie le document du partenaire

6️⃣ Activation → Le propriétaire active la clé, le partenaire peut signer des blocs

7️⃣ Révocation (si nécessaire) → Le propriétaire révoque une clé compromise ou obsolète

Installation du CLI

Le package @sowasit/signer est disponible sur NPM et peut être utilisé comme outil CLI ou bibliothèque JavaScript/TypeScript.

Installation globale (CLI)

npm install -g @sowasit/signer

Installation locale (bibliothèque)

npm install @sowasit/signer

Démarrage rapide

1. Générer et enregistrer une paire de clés (Partenaire)

Récupérez d'abord un token d'enrôlement du propriétaire de la chaîne, puis :

signer add-key \
  --token YOUR_ENROLLMENT_TOKEN \
  --api-key YOUR_API_KEY \
  --passphrase your-secret-passphrase \
  --output ./keys \
  --client-name "Your Company Name" \
  --client-contact "admin@company.com"

Cette commande va :

Générer une paire de clés ECDSA P-256
Enregistrer la clé publique sur SoWasIt
Sauvegarder les clés localement dans ./keys/
Générer un document de certification à imprimer, signer et uploader

2. Compléter la certification (Partenaire)

⚠️ Étape obligatoire : Pour permettre au propriétaire de la chaîne d'activer votre clé, vous devez :

Imprimer le document de certification généré (sowasit.certification.txt)
Le signer et le tamponner (signature légale de votre entreprise)
Le scanner en PDF
L'uploader via l'API ou le dashboard

3. Créer un bloc signé (Partenaire)

Une fois que le propriétaire de la chaîne a activé votre clé (status = active), vous pouvez signer des blocs :

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4d5e6f7g8 \
  --api-key sk_your_api_key \
  --content-file ./data.json \
  --passphrase your-secret-passphrase

Référence CLI

`signer add-key`

Génère une nouvelle paire de clés et l'enregistre sur SoWasIt.

Option	Description	Required
`-t, --token`	Token d'enrôlement depuis SoWasIt	✓
`-k, --api-key`	Votre clé API SoWasIt	✓
`-o, --output`	Répertoire de sortie (défaut: ./keys)
`-p, --passphrase`	Phrase secrète pour chiffrer la clé privée	Recommandé
`--client-name`	Nom de votre entreprise
`--client-contact`	Email de contact

`signer sign`

Signe du contenu avec votre clé privée (sans créer de bloc).

signer sign \
  --key ./keys/sowasit.private.pem \
  --data ./content.json \
  --passphrase secret \
  --output ./signature.json

`signer create-block`

Crée un bloc signé directement sur SoWasIt.

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4 \
  --api-key sk_xxx \
  --content '{"order": "ORD-001", "status": "shipped"}' \
  --passphrase secret

Usage programmatique (JavaScript/TypeScript)

Générer une paire de clés

import { KeyManager } from '@sowasit/signer';

// Generate key pair
const keyPair = await KeyManager.generateKeyPair({
  passphrase: 'your-secret-passphrase'
});

// Save to disk
await KeyManager.saveKeyPair(keyPair, './keys', 'my-company');

console.log('Key ID:', keyPair.keyId);
console.log('Fingerprint:', keyPair.fingerprint);

Signer du contenu

import { KeyManager } from '@sowasit/signer';

const content = {
  transaction_id: 'TXN-001',
  amount: 1500.00,
  timestamp: Date.now()
};

const privateKey = await KeyManager.loadPrivateKey(
  './keys/my-company.private.pem',
  'your-passphrase'
);

const { signature, algorithm } = KeyManager.signContent(
  content,
  privateKey
);

console.log('Signature:', signature);

Créer un bloc signé

import { SoWasItClient } from '@sowasit/signer';
import fs from 'node:fs/promises';

const client = new SoWasItClient({
  apiKey: 'sk_your_api_key'
});

const content = {
  event: 'product_shipped',
  order_id: 'ORD-12345',
  timestamp: Date.now()
};

const privateKeyPem = await fs.readFile('./keys/my-company.private.pem', 'utf-8');

const response = await client.createSignedBlock(
  'ch_your_chain_id',
  content,
  privateKeyPem,
  'your_public_key_id',
  'your-passphrase'
);

console.log('Block created:', response.block);

Bonnes pratiques de sécurité

🔒 Protection des clés privées

Toujours utiliser une passphrase pour chiffrer votre clé privée
Ne jamais commiter les clés privées dans Git
Stocker les clés dans un gestionnaire de mots de passe ou un HSM
Les clés privées sont automatiquement sauvegardées avec les permissions 0600

🔄 Rotation des clés

Générez de nouvelles clés régulièrement (tous les 6-12 mois)
Utilisez le mécanisme de remplacement lors de la rotation
Révoquez les anciennes clés après migration

⚠️ En cas de compromission

Révoquez immédiatement la clé compromise
Générez une nouvelle paire de clés
Notifiez l'équipe SoWasIt si nécessaire

Endpoints API

POST /keys/enrollment-tokens

Génère un token d'enrôlement à usage unique (7 jours de validité).

curl -X POST https://api.sowasit.io/keys/enrollment-tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "authorized_by": "admin@company.com"
    },
    "validity_days": 7
  }'

POST /keys/register

Enregistre une clé publique avec un token d'enrôlement.

curl -X POST https://api.sowasit.io/keys/register \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_token": "abc123...",
    "public_key": "-----BEGIN PUBLIC KEY-----\n...",
    "algorithm": "ECDSA-P-256",
    "client_info": {
      "name": "My Company SARL",
      "siret": "12345678901234",
      "contact": "admin@company.com"
    }
  }'

GET /keys

Liste toutes vos clés publiques.

curl https://api.sowasit.io/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /keys/{keyId}/revoke

Révoque une clé publique.

curl -X POST https://api.sowasit.io/keys/abc123/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Key compromised"
  }'

Dépannage

❌ "Block signature is required: tenant has active public keys"

Votre tenant a des clés actives enregistrées, donc tous les blocs doivent être signés.

Solution : Utilisez signer create-block ou signez manuellement avec signer sign.

❌ "Invalid passphrase for encrypted private key"

Votre clé est chiffrée mais vous avez fourni la mauvaise passphrase ou aucune passphrase.

Solution : Fournissez la bonne passphrase avec --passphrase.

❌ "Invalid block signature"

La vérification de la signature a échoué.

Causes possibles :

Le contenu a été modifié après signature
Mauvaise clé privée utilisée
Format de signature invalide
L'ID de clé publique ne correspond pas à la clé qui a signé

❌ "Public key is not active"

La clé n'est pas encore activée ou a été révoquée.

Solution : Vérifiez le statut de la clé dans votre dashboard. Complétez la certification si nécessaire.

Support

Documentation complète : docs.sowasit.io
Package NPM : @sowasit/signer
Dashboard : dashboard.sowasit.io
Email : support@sowasit.io