Aucune requête ou réponse ne peut être traitée sans respecter ces règles.
Authentication
Le protocole OAuth 2 est le mécanisme supporté pour cette couche d’authentification :
OAuth 2.0 (client_credentials) : Mécanisme standardisé et recommandé, où les identifiants clients sont échangés contre un jeton JWT (JSON Web Token). Ce jeton est ensuite utilisé dans l’en-tête Authorization: Bearer <token>.
Protection anti-rejeu
Prévention des attaques par relecture de messages
Principe
Chaque message doit contenir :
- un identifiant unique
nonce),
- un horodatage
timestamp).
Règles de validation
- Le
nonce doit être unique
- Le timestamp doit être au format RFC3339 UTC
- La dérive horaire maximale autorisée est configurable (par défaut ±120s)
Comportement attendu
Tout message :
- avec un nonce déjà utilisé,
- ou un timestamp expiré,
doit être rejeté avec une erreur de sécurité.
Idempotence
Garantie d’exécution unique des ordres
Objectif
L’idempotence garantit qu’un même ordre métier ne sera jamais exécuté plus d’une fois.
Clé d’idempotence
Chaque requête doit inclure :
- une clé d’idempotence unique,
- stable sur toute la durée de vie de l’ordre.
Règles
- La Banque doit stocker la clé et le résultat associé
- Toute requête dupliquée retourne le résultat initial
- Aucun retraitement métier ne doit être déclenché
Signature des messages (JWS)
Garantie d’intégrité et de non-répudiation
Objectif
Chaque message échangé doit être **signé numériquement ** afin de garantir :
- l’intégrité du contenu,
- l’authenticité de l’émetteur,
- la non-répudiation.
Standard utilisé
- JSON Web Signature (JWS)
- Algorithmes autorisés :
RS256, PS256
Règles obligatoires
- La signature porte sur l’intégralité du payload métier
- Toute modification invalide la signature
- Une signature invalide entraîne un rejet immédiat
Responsabilités Banque
- Signer les callbacks de statut
- Vérifier les signatures des ordres entrants
En-têtes HTTP de sécurité (Push / Pull)
Ces en-têtes DOIVENT être validés avant tout traitement métier.
| En-tête | Rôle | Format | Générateur |
|---|
X-Client-Id | Identification | String | Les deux |
X-Request-Id | Tracabilité | String opaque | Client |
X-Timestamp | Anti-replay | ISO-8601 UTC | Les deux |
X-Nonce | Anti-replay | String opaque | Les deux |
X-Idempotency-Key | Idempotence | String opaque | Client |
X-Signature | Intégrité / Non-répudiation | JWS detached | Les deux |
4.3 Construction du message par l’émetteur (CRITIQUE)
Cette section décrit exactement comment le body est calculé et signé.
Toute implémentation DOIT suivre ces étapes dans cet ordre.
Étape A — Canonicalisation du payload
- Le payload JSON est canonicalisé via :
- JCS (JSON Canonicalization Scheme – RFC 8785)
- Le hash est calculé :
payloadHash = SHA-256(JCS(payload))
- ordre des champs déterministe
- absence d’ambiguïté cryptographique
La signature DOIT couvrir les éléments suivants :
| Claim JWS | Source | Rôle |
|---|
alg | JWS | Algorithme (ex: ES384) |
kid | JWS | Identifiant de clé |
timestamp | X-Timestamp | Anti-replay |
nonce | X-Nonce | Anti-replay |
idempotency | X-Idempotency-Key | Unicité |
payloadhash | Calculé | Intégrité du body |
Étape C — Génération de la signature (X-Signature)
- La signature est générée avec :
- la clé privée de l’émetteur
- stockée dans un HSM / Vault
- Le format est :
- JWS detached (le payload n’est pas encodé dans la signature)
Le résultat est placé dans :
X-Signature: <jws-detached>
4.4 Validation du message par le destinataire
Les validations sont exécutées dans l’ordre strict ci-dessous.
4.4.1 Contrôles anti-replay et temporels
| En-tête | Règle | Code d’erreur |
|---|
X-Timestamp | now − timestamp ≤ 120s | SEC_TIMESTAMP_EXPIRED |
X-Nonce | Unique sur 300s | SEC_REPLAY_DETECTED |
4.4.2 Contrôle d’intégrité (Signature JWS)
- Identification de la clé publique (
X-Client-Id / kid)
- Vérification de la signature JWS
- Recalcul du
payloadHash
- Comparaison avec le
payloadhash signé
| Échec | Code |
|---|
| Signature invalide | SEC_INVALID_SIGNATURE |
| Hash différent | PAYLOAD_HASH_MISMATCH |
4.4.3 Contrôle d’idempotence métier
- La
X-Idempotency-Key est utilisée comme clé métier
- Si déjà traitée avec un statut final :
- le traitement N’EST PAS rejoué
- le résultat initial est retourné
- Sinon :
- traitement métier
- stockage du résultat avec TTL
4.5 Principe clé
Le body n’est jamais signé directement.C’est le hash du body canonicalisé qui est signé.
