Codes d'erreur ​

Voici les codes d'erreur communs aux bibliothèques de service officiellement prises en charge par DAT.

Chaque code porte deux valeurs — impact et nouvelle tentative — et certains reçoivent en plus l'étiquette suspect.

Impact — ce que le service encaisse ​

C'est le critère pour déclencher une alerte. On ne regarde qu'une chose : « le service est-il à l'arrêt en ce moment ? »

Aucun impact n'est pas un cas d'alerte. Si toute l'équipe d'astreinte devait vérifier parce qu'une entrée erronée est arrivée une fois, l'alerte perdrait tout son sens.

Suspect — enquêter si cela persiste ​

Les codes portant l'étiquette Suspect font partie du fonctionnement normal lorsqu'ils sont isolés. Un client peut envoyer une valeur erronée à tout moment, et le rôle de la bibliothèque est précisément de la filtrer.

Mais si ces erreurs surviennent de façon persistante, ou en rafale depuis une source précise, il s'agit de l'un de ces deux cas.

• Anomalie de configuration — un déploiement incorrect, des clients d'une ancienne version encore en service, ou des certificats désalignés.
• Tentative d'intrusion — une tentative de passer la vérification avec des tokens ou des clés falsifiés, ou un balayage à la recherche de valeurs valides.

C'est pourquoi il convient, pour ces codes, de suivre le nombre d'occurrences comme métrique. Il suffit d'alerter au franchissement d'un seuil.

Nouvelle tentative ​

Token ​

Problèmes portant sur la chaîne du token reçu elle-même.

Certificat ​

Le format de la chaîne du certificat, et la question de savoir si ce certificat est utilisable maintenant.

DAT_CERT_NOT_FOUND et DAT_CERT_NOT_SYNCED présentent les mêmes symptômes, mais appellent des réactions différentes. Le premier concerne un cid que nous n'avons jamais émis : attendre n'y changera rien. Le second se résout dès que la synchronisation a lieu.

Un DAT_CERT_NOT_FOUND isolé se filtre sans plus ; si le nombre augmente brusquement, c'est que le déploiement est désaligné ou que des tokens falsifiés circulent.

Signature ​

Chiffrement ​

Problèmes de chiffrement et de déchiffrement de la charge utile secure.

Une charge utile secure vide n'est pas une erreur. Une entrée vide donne une sortie vide, et aucun code n'est émis.

Sur le chemin qui saute la vérification de signature, le tag GCM est le seul contrôle d'intégrité. C'est pourquoi DAT_CRYPTO_TAG_MISMATCH n'est pas regroupé avec les autres échecs de déchiffrement sous un même code.

Clé ​

Trois cas qui se ressemblent mais diffèrent :

Gestionnaire ​

L'état de l'objet qui détient les certificats et sert à émettre et vérifier.

La cause (cause) de DAT_MANAGER_NO_ISSUABLE_CERTIFICATE est l'une des quatre suivantes. Ce qu'il faut faire diffère complètement selon l'origine.

Si le serveur émetteur est configuré pour ne recevoir que des certificats de vérification, DAT_CERT_VERIFY_ONLY apparaît. Attendre n'y changera jamais rien : ce n'est donc pas un cas de nouvelle tentative.

Configuration ​

Problèmes portant sur les valeurs transmises par l'appelant. La famille CONFIG regroupe uniquement des erreurs à corriger dans le code ; si elles surviennent en exploitation, c'est que le déploiement est incorrect.

Interne ​

Problèmes de l'environnement d'exécution et du runtime.

DAT_INTERNAL_UNAVAILABLE se résout en corrigeant l'environnement de déploiement ; DAT_INTERNAL_UNKNOWN relève généralement d'une défaillance du runtime ou d'un bug de la bibliothèque.

Synchronisation CMS ​

Sans synchronisation CMS, ces codes n'apparaissent pas.

Les codes pour lesquels la synchronisation est jugée définitivement en échec (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED) sont tous critiques. Réessayer n'y change rien alors que les certificats continuent d'expirer : laissé sans réaction, le service finira nécessairement par s'arrêter.

À l'inverse, UNREACHABLE et SERVER_ERROR sont partiels. Tout continue avec les certificats en place et la synchronisation se rétablit d'elle-même au cycle suivant — mais si les échecs se répètent, on bascule à terme en critique. Placez l'alerte sur le nombre d'échecs consécutifs.

Serveur ​

Codes émis par le serveur CMS. Les clients ne les produisent pas, ils les reçoivent seulement.

Enveloppe de réponse :

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

Pour les erreurs survenant lors de la création et de la manipulation des certificats, le serveur utilise tels quels les codes communs ci-dessus (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

À la réception d'un code serveur ​

Le client enveloppe le code serveur dans son propre code CMS et conserve l'original dans cause.

Rechercher par symptôme ​

Annexe ​

Syntaxe des codes ​

DAT_<domaine>_<cause>

• Lorsqu'une même cause survient dans des domaines différents, le nom de la cause est identique. DAT_TOKEN_MALFORMED et DAT_CERT_MALFORMED ne diffèrent que par l'objet concerné, le sens est le même.
• _UNKNOWN est réservé au repli de chaque domaine. Il n'est pas employé dans un autre sens, par exemple « algorithme inconnu » (c'est _UNSUPPORTED qui sert à cela).
• La chaîne de code est un contrat public. Le message peut être modifié librement, le code non.

Accès selon le client ​

Événement de sécurité ne renvoie true que pour les deux cas où la falsification ou l'altération est avérée (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). L'étiquette suspect de ce document couvre un périmètre plus large (jusqu'aux tokens, clés et requêtes falsifiés) ; il ne s'agit pour l'instant que d'une classification documentaire, non exposée par l'API cliente.

Le niveau d'impact est lui aussi une classification documentaire. Un même code peut frapper différemment selon l'endroit où il survient — DAT_KEY_INVALID n'a par exemple aucun impact lorsqu'il sert à filtrer un token entrant, mais fait échouer toute la synchronisation lorsqu'il survient à la lecture d'un certificat pendant la synchronisation CMS.

Les causes sous-jacentes ne sont pas perdues. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE et DAT_CMS_IMPORT_FAILED transmettent l'origine via le chaînage d'exceptions propre à chaque langage (cause / __cause__ / InnerException / Unwrap()).