Fehlercodes ​

Dies sind die gemeinsamen Fehlercodes der offiziell von DAT unterstützten Service-Bibliotheken.

Jeder Code trägt zwei Werte — Auswirkung und Wiederholung — und einige zusätzlich die Markierung Verdacht.

Auswirkung — was der Dienst abbekommt ​

Das ist der Maßstab für Alarme. Betrachtet wird nur: „Steht der Dienst gerade still?"

Keine Auswirkung ist kein Alarmfall. Wenn die gesamte Bereitschaft nachsehen müsste, weil einmal eine fehlerhafte Eingabe eintraf, wird der Alarm bedeutungslos.

Verdacht — bei Dauerhaftigkeit untersuchen ​

Codes mit der Markierung Verdacht sind im Einzelfall Teil des normalen Betriebs. Clients können jederzeit falsche Werte senden, und es ist genau die Aufgabe der Bibliothek, diese auszusortieren.

Treten solche Fehler jedoch dauerhaft oder gehäuft aus einer bestimmten Quelle auf, liegt einer von zwei Fällen vor.

• Konfigurationsfehler — ein fehlerhaftes Deployment, verbliebene Clients einer alten Version oder nicht zueinander passende Zertifikate.
• Angriffsversuch — der Versuch, mit manipulierten Tokens oder Schlüsseln die Prüfung zu bestehen, oder das Abtasten nach gültigen Werten.

Deshalb ist es richtig, für diese Codes die Anzahl als Metrik zu erfassen. Gemeldet wird erst beim Überschreiten eines Schwellenwerts.

Wiederholung ​

Token ​

Probleme mit der empfangenen Token-Zeichenkette selbst.

Zertifikat ​

Das Format der Zertifikatszeichenkette und die Frage, ob dieses Zertifikat jetzt verwendbar ist.

DAT_CERT_NOT_FOUND und DAT_CERT_NOT_SYNCED sehen gleich aus, erfordern aber unterschiedliche Reaktionen. Beim ersten handelt es sich um eine cid, die wir nie ausgestellt haben — Warten hilft nicht. Der zweite löst sich, sobald die Synchronisierung erfolgt ist.

Ein einzelnes DAT_CERT_NOT_FOUND sortiert man einfach aus; steigt die Zahl plötzlich, ist entweder das Ausrollen aus dem Tritt geraten oder es kursieren gefälschte Tokens.

Signatur ​

Verschlüsselung ​

Probleme bei der Ver- und Entschlüsselung der secure-Payload.

Eine leere secure-Payload ist kein Fehler. Leere Eingabe wird zu leerer Ausgabe, und es wird kein Code erzeugt.

Auf dem Pfad ohne Signaturprüfung ist das GCM-Tag die einzige Integritätsprüfung. Deshalb wird DAT_CRYPTO_TAG_MISMATCH nicht mit anderen Entschlüsselungsfehlern in einen Code zusammengefasst.

Schlüssel ​

Drei ähnlich aussehende, aber verschiedene Fälle:

Manager ​

Der Zustand des Objekts, das Zertifikate hält und zum Ausstellen und Prüfen verwendet.

Der Grund (cause) von DAT_MANAGER_NO_ISSUABLE_CERTIFICATE ist einer von vieren. Je nach Ursache ist das Vorgehen völlig unterschiedlich.

Ist der ausstellende Server so konfiguriert, dass er nur reine Prüfzertifikate erhält, erscheint DAT_CERT_VERIFY_ONLY. Warten hilft hier nie, deshalb ist dies kein Fall für eine Wiederholung.

Konfiguration ​

Probleme mit den vom Aufrufer übergebenen Werten. Die CONFIG-Familie besteht durchweg aus Fehlern, die im Code behoben werden müssen; treten sie im Betrieb auf, ist das Deployment fehlerhaft.

Intern ​

Probleme der Ausführungsumgebung und der Laufzeit.

DAT_INTERNAL_UNAVAILABLE löst sich, indem die Deployment-Umgebung korrigiert wird; DAT_INTERNAL_UNKNOWN ist meist eine Laufzeitstörung oder ein Bibliotheksfehler.

CMS-Synchronisierung ​

Ohne CMS-Synchronisierung treten diese Codes nicht auf.

Die Codes, bei denen die Synchronisierung als dauerhaft fehlgeschlagen gilt (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED), sind allesamt kritisch. Eine Wiederholung löst nichts, während die Zertifikate weiter ablaufen — bleibt es unbeachtet, kommt der Dienst zwangsläufig zum Stillstand.

UNREACHABLE und SERVER_ERROR sind dagegen teilweise. Mit den vorhandenen Zertifikaten läuft alles weiter, und im nächsten Zyklus erholt sich die Synchronisierung von selbst — schlägt sie jedoch dauerhaft fehl, geht sie am Ende in „kritisch" über. Setzen Sie den Alarm auf die Anzahl aufeinanderfolgender Fehlschläge.

Server ​

Codes, die der CMS-Server erzeugt. Clients erzeugen sie nicht, sondern empfangen sie nur.

Antwortumschlag:

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

Fehler, die beim Erzeugen und Verarbeiten von Zertifikaten auftreten, verwendet auch der Server unverändert aus den obigen gemeinsamen Codes (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

Wenn ein Servercode eintrifft ​

Der Client hüllt den Servercode in seinen eigenen CMS-Code und bewahrt das Original in cause auf.

Nach Symptom suchen ​

Anhang ​

Code-Syntax ​

DAT_<Bereich>_<Ursache>

• Tritt dieselbe Ursache in verschiedenen Bereichen auf, lautet der Ursachenname gleich. DAT_TOKEN_MALFORMED und DAT_CERT_MALFORMED unterscheiden sich nur im Gegenstand, die Bedeutung ist dieselbe.
• _UNKNOWN ist ausschließlich der Fallback des jeweiligen Bereichs. Es wird nicht in anderer Bedeutung verwendet, etwa für „unbekannter Algorithmus" (dafür steht _UNSUPPORTED).
• Die Code-Zeichenkette ist ein öffentlicher Vertrag. Die Meldung darf frei geändert werden, der Code nicht.

Zugriff je Client ​

Sicherheitsereignis liefert nur für die beiden Fälle true, bei denen Fälschung oder Manipulation feststeht (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). Die Markierung Verdacht in diesem Dokument reicht weiter (bis hin zu manipulierten Tokens, Schlüsseln und Anfragen); sie ist derzeit nur eine Klassifikation der Dokumentation und wird nicht über die Client-API bereitgestellt.

Auch die Stufe Auswirkung ist eine Klassifikation der Dokumentation. Derselbe Code kann je nach Fundort unterschiedlich hart treffen — DAT_KEY_INVALID etwa hat keine Auswirkung, wenn damit ein eingehendes Token aussortiert wird, lässt aber die gesamte Synchronisierung scheitern, wenn er beim Lesen eines Zertifikats während der CMS-Synchronisierung auftritt.

Untergeordnete Ursachen gehen nicht verloren. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE und DAT_CMS_IMPORT_FAILED reichen den Grund über die Ausnahmeverkettung der jeweiligen Sprache weiter (cause / __cause__ / InnerException / Unwrap()).