Aller au contenu
Universal Commerce Protocol Universal Commerce Protocol Protocol registry / fr
Le standard UCPUCP vs ACPImplémenterCommerce agentiqueFramework
ConceptGEOllms.txtLexiquePaiement agentiqueAP2Visa et MastercardCommerce agentique B2BMéthodologieCas d'usagePourquoi maintenantPour quiManifesteFAQRessourcesSourcesÉcosystèmeValidateurDiagnostic readinessÀ proposContact
EN Lancer le diagnostic →

Note de référence

Signatures UCP : vérifier requêtes et webhooks

Guide des signatures UCP avec RFC 9421 : digest, ES256, clés JWK, rotation, vérification des requêtes et protection des webhooks.

Publiée le . Rattachée à le guide d'implémentation UCP.

UCP utilise les signatures de messages HTTP pour prouver l’origine et l’intégrité des échanges. La base est RFC 9421, complétée par un digest du corps, des clés JWK publiées dans le manifeste et des clés d’idempotence contre les rejouements.

En bref

  • Tout vérificateur doit prendre en charge ES256 ; ES384 et EdDSA sont optionnels.
  • Le corps est protégé par Content-Digest selon RFC 9530.
  • Tous les webhooks UCP doivent être signés.

Que protège une signature UCP ?

La spécification des signatures vise quatre risques : usurpation, modification en transit, rejeu sur une autre requête et confusion entre méthodes ou chemins. La signature couvre donc plus que le JSON.

Les composants signés incluent selon le message la méthode, l’autorité, le chemin, le digest et la clé d’idempotence. Modifier POST /checkout en une autre route invalide la signature, même si le corps est identique.

Quels standards et formats sont imposés ?

Élément Règle UCP
format de signature RFC 9421
digest du corps RFC 9530, octets bruts
algorithme vérification ES256 requise, ES384 et EdDSA optionnels
format de clé JWK, RFC 7517
découverte keys[] dans /.well-known/ucp
anti-rejeu clé d’idempotence au niveau métier

Les clés publiques du manifeste UCP sont identifiées par kid. Le vérificateur sélectionne la clé correspondante, reconstruit la base signée et vérifie la signature elliptique.

Depuis la version 2026-08-25, le profil publie ces JWK dans le tableau racine keys[]. Le champ signing_keys[] appartient au schéma historique 2026-04-08 et ne doit pas être utilisé dans un profil annoncé comme compatible avec la version courante.

Comment vérifier une requête REST ?

  1. Extraire les composants annoncés dans Signature-Input.
  2. Exiger les composants requis pour l’opération.
  3. Résoudre keyid dans le profil validé de l’émetteur.
  4. Recalculer Content-Digest sur les octets reçus, avant tout reformatage JSON.
  5. Reconstruire la base RFC 9421 dans l’ordre déclaré.
  6. Vérifier la signature avec la clé publique.
  7. Appliquer ensuite la logique d’idempotence.

Recalculer le digest après avoir parsé puis sérialisé le JSON est une erreur. Les espaces ou l’ordre des clés peuvent changer. RFC 9530 protège les octets effectivement transmis.

Signatures et idempotence ne font pas le même travail

La signature répond à « qui a envoyé quoi ? ». La clé d’idempotence répond à « cette opération a-t-elle déjà produit un effet ? ». UCP place la protection contre le rejeu au niveau métier, pas dans l’horodatage de la signature.

Une opération modifiant l’état inclut une clé ayant au moins 128 bits d’entropie. Le serveur la conserve au minimum 24 heures, 48 heures étant recommandées. Un doublon renvoie la réponse mise en cache. La même clé avec un corps différent produit HTTP 409.

Quels messages doivent être signés ?

Les plateformes devraient signer leurs requêtes lorsqu’elles choisissent ce mécanisme. Les webhooks doivent toujours être signés, car le destinataire ne peut pas autrement authentifier une notification initiée par le serveur.

La signature est recommandée pour les autorisations de paiement et les réponses de finalisation du checkout. Elle est optionnelle pour les lectures Catalog, les opérations Cart à faible risque et certaines erreurs. OAuth, mTLS ou une clé API peuvent aussi authentifier une requête, selon la capacité.

Rotation et cache des clés

Le kid permet de publier plusieurs clés pendant une rotation. Le vérificateur doit rafraîchir le manifeste lorsqu’une clé est inconnue, sans accepter automatiquement un profil non validé. Retirer une clé compromise du profil est le mécanisme prévu pour invalider les anciennes signatures.

Un cache trop long peut maintenir une clé retirée. Un cache absent peut rendre chaque requête dépendante du manifeste distant. La stratégie doit combiner durée courte, rafraîchissement sur key_not_found et conservation du dernier profil validé pendant une panne temporaire clairement bornée.

Pour replacer cette vérification dans le déploiement complet, voir implémenter UCP côté marchand.

Sources

Revenir à le guide d'implémentation UCP · Toutes les notes · Read in English