Zum Hauptinhalt springen

RFC 8555 - Automatische Zertifikatsverwaltungsumgebung (ACME)

  • Status: Proposed Standard
  • Veröffentlicht: March 2019
  • Stream: IETF
  • Errata: Keine Errata

Zusammenfassung​

Public Key Infrastructure using X.509 (PKIX)-Zertifikate werden für verschiedene Zwecke verwendet, wobei die Authentifizierung von Domainnamen am wichtigsten ist. Daher wird Zertifizierungsstellen (CAs) im Web-PKI vertraut, zu überprüfen, dass ein Antragsteller für ein Zertifikat die Domainnamen im Zertifikat rechtmäßig vertritt. Zum Zeitpunkt dieser Schrift wird diese Überprüfung durch eine Sammlung von Ad-hoc-Mechanismen durchgeführt. Dieses Dokument beschreibt ein Protokoll, das eine CA und ein Antragsteller verwenden können, um den Überprüfungs- und Zertifikatsausstellungsprozess zu automatisieren. Das Protokoll bietet auch Funktionen für andere Zertifikatsverwaltungsfunktionen wie Zertifikatswiderruf.

Status dieses Memos​

Dies ist ein Internet Standards Track-Dokument.

Dieses Dokument ist ein Produkt der Internet Engineering Task Force (IETF). Es stellt den Konsens der IETF-Community dar. Es wurde öffentlich überprüft und von der Internet Engineering Steering Group (IESG) zur Veröffentlichung genehmigt.

Hauptmerkmale​

ACME-Protokoll-Vorteile:

  • ⚡ Vollständig automatisiert: Keine manuelle Intervention von der Anfrage bis zur Erneuerung
  • 🔄 Häufige Updates: Unterstützt kurzlebige Zertifikate (Let's Encrypt Standard: 90 Tage)
  • 💰 Kostenreduzierung: Eliminiert Kosten manueller Prozesse
  • 🔒 Erhöhte Sicherheit: Kurzlebige Zertifikate reduzieren Expositionsrisiken

Typischer ACME-Workflow:

Client (ACME-Client)                    ACME-Server (CA)
       |                                        |
       |  1. Konto erstellen                    |
       |--------------------------------------->|
       |     <-- Konto-URL                      |
       |                                        |
       |  2. Zertifikatsbestellung senden       |
       |--------------------------------------->|
       |     <-- Bestellungsobjekt + Challenges |
       |                                        |
       |  3. Domain-Validierung abschließen     |
       |     (HTTP-01 oder DNS-01)             |
       |--------------------------------------->|
       |     <-- Validierung erfolgreich        |
       |                                        |
       |  4. Abschließen (CSR senden)           |
       |--------------------------------------->|
       |     <-- Zertifikats-URL                |
       |                                        |
       |  5. Zertifikat herunterladen           |
       |--------------------------------------->|
       |     <-- PEM-Format Zertifikatskette    |

Kernkomponenten​

Ressourcentypen​

  1. Directory: Verzeichnis der Server-API-Endpunkte
  2. Account: Client-Kontoinformationen
  3. Order: Zertifikatsbestellung
  4. Authorization: Domain-Autorisierung
  5. Challenge: Validierungs-Challenge
  6. Certificate: Ausgestelltes Zertifikat

Validierungsmethoden​

  • HTTP-01 Challenge: Datei unter spezifischem HTTP-Pfad bereitstellen
  • DNS-01 Challenge: Spezifischen DNS-TXT-Eintrag bereitstellen

Beliebte ACME-Clients​

  • Certbot (EFF Offiziell)
  • acme.sh (Shell-Skript)
  • Lego (Go-Sprache)
  • win-acme (Windows)

Verwandte RFCs​

  • RFC 7515 - JSON Web Signature
  • RFC 5280 - X.509-Zertifikate
  • RFC 6797 - HSTS
  • RFC 7807 - Problem Details für HTTP-APIs

Referenzen​

Für detaillierte technische Spezifikationen siehe bitte das offizielle RFC 8555-Dokument.

1. Introduction (Einführung)​

Zertifikate (Certificates) im Web-PKI [RFC5280] werden am häufigsten zur Authentifizierung von Domainnamen (Domain Names) verwendet. Daher werden Zertifizierungsstellen (Certification Authorities, CAs) im Web-PKI als vertrauenswürdig angesehen, um zu überprüfen, ob Zertifikatsantragsteller die in einem Zertifikat enthaltenen Domainnamen rechtmäßig vertreten.

Verschiedene Zertifikatstypen spiegeln unterschiedliche Validierungsstufen wider, die eine CA für die im Zertifikat enthaltenen Informationen über den Zertifikatsinhaber durchführt. „Domainvalidierte" (Domain Validation, DV) Zertifikate sind bei weitem der häufigste Typ. Bei der Ausstellung von DV-Zertifikaten ist die einzige Validierung, die eine CA durchführen muss, die Bestätigung, dass der Antragsteller die betreffende Domain effektiv kontrolliert [CABFBR]. Die CA muss nicht versuchen, die tatsächliche Identität des Antragstellers zu überprüfen. (Dies steht im Gegensatz zu „organisationsvalidierten" (Organization Validation, OV) und „erweitert validierten" (Extended Validation, EV) Zertifikaten, deren Prozesse auch darauf abzielen, die tatsächliche Identität des Antragstellers zu überprüfen.)

Bestehende Web-PKI-Zertifizierungsstellen neigen dazu, eine Reihe von Ad-hoc-Protokollen (Ad Hoc Protocols) für die Zertifikatsausstellung und -identitätsprüfung zu verwenden. Für DV-Zertifikate sieht die typische Benutzererfahrung wie folgt aus:

  • Generierung einer PKCS#10 [RFC2986] Zertifikatsignierungsanforderung (Certificate Signing Request, CSR).

  • Kopieren und Einfügen des CSR in eine Webseite der CA.

  • Nachweis der Kontrolle über den Domainnamen im CSR durch eine der folgenden Methoden:

    • Platzierung einer von der CA bereitgestellten Herausforderung (Challenge) an einem bestimmten Ort auf einem Webserver.

    • Platzierung einer von der CA bereitgestellten Herausforderung in einem DNS-Eintrag, der der Zieldomain entspricht.

    • Empfang einer von der CA bereitgestellten Herausforderung an einer (hoffentlich) vom Administrator kontrollierten E-Mail-Adresse für die Domain und anschließende Antwort auf der Webseite der CA.

  • Herunterladen des ausgestellten Zertifikats und Installation auf dem Webserver des Benutzers.

Abgesehen vom CSR selbst und dem ausgestellten Zertifikat sind dies vollständig Ad-hoc-Verfahren, die dadurch abgeschlossen werden, dass menschliche Benutzer den interaktiven Anweisungen der CA in natürlicher Sprache folgen, anstatt durch maschinell implementierte veröffentlichte Protokolle. In vielen Fällen sind diese Anweisungen schwer zu befolgen und führen zu erheblicher Frustration und Verwirrung. Informelle Usability-Tests der Autoren zeigen, dass Website-Administratoren typischerweise 1–3 Stunden benötigen, um ein Zertifikat für eine Domain zu erhalten und zu installieren. Selbst im besten Fall hemmt das Fehlen eines veröffentlichten standardisierten Mechanismus die breite Bereitstellung von HTTPS und anderen auf PKIX basierenden Systemen, da es die Mechanisierung von Aufgaben im Zusammenhang mit der Zertifikatsausstellung, -bereitstellung und -widerrufung unterdrückt.

Dieses Dokument beschreibt ein erweiterbares Framework zur Automatisierung des Zertifikatsausstellungs- und Domainvalidierungsprozesses, das es Server- und Infrastruktursoftware ermöglicht, Zertifikate ohne Benutzerinteraktion zu erhalten. Die Verwendung dieses Protokolls sollte die Bereitstellung von HTTPS sowie die Praktikabilität der PKIX-basierten Authentifizierung in anderen auf Transport Layer Security (TLS) [RFC8446] basierenden Protokollen erheblich vereinfachen.

Es ist zu beachten, dass ACME, obwohl sich dieses Dokument auf die Validierung von Domainnamen für die Zertifikatsausstellung im Web-PKI konzentriert, Erweiterungen für die Verwendung anderer Identifikatoren in anderen PKI-Kontexten unterstützt. Zum Zeitpunkt der Erstellung dieses Dokuments laufen beispielsweise Arbeiten zur Verwendung von ACME für die Ausstellung von Web-PKI-Zertifikaten, die IP-Adressen [ACME-IP] und Telefonnummern über Secure Telephone Identity Revisited (STIR) [ACME-TELEPHONE] belegen.

ACME kann auch zur Automatisierung bestimmter Aspekte des Zertifikatsmanagements verwendet werden, selbst in Fällen, in denen nicht-automatisierte Prozesse noch erforderlich sind. Beispielsweise kann die Funktion zur externen Kontobindung (External Account Binding) (siehe Abschnitt 7.3.4) es einem ACME-Konto ermöglichen, Autorisierungen zu nutzen, die einem externen Nicht-ACME-Konto gewährt wurden. Dies ermöglicht es ACME, Ausstellungsszenarien zu handhaben, die noch nicht vollständig automatisiert werden können, wie z. B. die Ausstellung von „erweitert validierten" Zertifikaten.

2. Deployment Model and Operator Experience (Bereitstellungsmodell und Betreibererfahrung)​

Der maßgebliche Anwendungsfall für ACME ist die Beschaffung von Zertifikaten für Websites (HTTPS [RFC2818]). In diesem Kontext soll ein Webserver eine oder mehrere Domains repräsentieren, und der Zertifikatsausstellungsprozess soll überprüfen, dass der Webserver diese Domains tatsächlich repräsentiert.

Die DV-Zertifikatsvalidierung prüft typischerweise Behauptungen über Eigenschaften, die mit der Domainkontrolle zusammenhängen – Eigenschaften, die der Zertifikatsaussteller in einer rein online durchgeführten Interaktion beobachten kann. Das bedeutet, dass im typischen Fall alle Schritte im Anforderungs-, Validierungs- und Ausstellungsprozess über Internetprotokolle dargestellt und ausgeführt werden können, ohne manuelle Eingriffe außerhalb des Bandes.

Vor ACME wurde ein Serverbetreiber beim Bereitstellen eines HTTPS-Servers typischerweise aufgefordert, ein selbstsigniertes Zertifikat (Self-Signed Certificate) zu generieren. Wenn der Betreiber stattdessen einen HTTPS-Server mit ACME bereitstellt, würde die Erfahrung wie folgt aussehen:

  • Der ACME-Client des Betreibers fordert den Betreiber auf, die beabsichtigten Domainnamen einzugeben, die der Webserver repräsentieren soll.

  • Der ACME-Client präsentiert dem Betreiber eine Liste von CAs, von denen Zertifikate bezogen werden können. (Diese Liste wird sich im Laufe der Zeit ändern, wenn sich die Fähigkeiten der CAs und die ACME-Konfiguration ändern.) Der ACME-Client kann den Betreiber zu diesem Zeitpunkt nach Zahlungsinformationen fragen.

  • Der Betreiber wählt eine CA aus.

  • Im Hintergrund kontaktiert der ACME-Client die CA und fordert sie auf, ein Zertifikat für die beabsichtigten Domainnamen auszustellen.

  • Die CA überprüft, ob der Client die angeforderten Domainnamen kontrolliert, indem sie den ACME-Client bestimmte Operationen durchführen lässt, die nur möglich sind, wenn man die Domain kontrolliert. Beispielsweise kann die CA einen Client, der example.com anfordert, auffordern, einen DNS-Eintrag unter example.com oder eine HTTP-Ressource unter http://example.com zu konfigurieren.

  • Sobald die CA zufrieden ist, stellt sie das Zertifikat aus, und der ACME-Client lädt es automatisch herunter und installiert es, wobei er den Betreiber möglicherweise per E-Mail, SMS oder auf andere Weise benachrichtigt.

  • Der ACME-Client kontaktiert die CA regelmäßig, um aktualisierte Zertifikate, geheftete Online Certificate Status Protocol (OCSP) Antworten [RFC6960] oder alles andere zu erhalten, was erforderlich ist, um den Webserver funktionsfähig zu halten und seine Anmeldeinformationen aktuell zu halten.

Auf diese Weise ist die Bereitstellung mit einem von einer CA ausgestellten Zertifikat fast so einfach wie die Verwendung eines selbstsignierten Zertifikats. Darüber hinaus erfordert die Pflege dieses von der CA ausgestellten Zertifikats minimale manuelle Eingriffe. Diese enge Integration von ACME mit dem HTTPS-Server ermöglicht eine sofortige automatische Bereitstellung bei der Zertifikatsausstellung und befreit menschliche Administratoren von einem Großteil der zeitaufwändigen Arbeit, die im vorherigen Abschnitt beschrieben wurde.

3. Terminology (Terminologie)​

Die Schlüsselwörter „MUST" (MUSS), „MUST NOT" (DARF NICHT), „REQUIRED" (ERFORDERLICH), „SHALL" (SOLL), „SHALL NOT" (SOLL NICHT), „SHOULD" (SOLLTE), „SHOULD NOT" (SOLLTE NICHT), „RECOMMENDED" (EMPFOHLEN), „NOT RECOMMENDED" (NICHT EMPFOHLEN), „MAY" (KANN) und „OPTIONAL" (OPTIONAL) in diesem Dokument sind gemäß BCP 14 [RFC2119] [RFC8174] zu interpretieren, wenn und nur wenn sie in Großbuchstaben erscheinen, wie hier gezeigt.

Die zwei Hauptrollen in ACME sind „Client" (Client) und „Server" (Server). Der ACME-Client verwendet das Protokoll, um Zertifikatsverwaltungsoperationen wie Ausstellung oder Widerruf anzufordern. Ein ACME-Client kann auf einem Webserver, einem Mailserver oder einem anderen Serversystem ausgeführt werden, das ein gültiges X.509-Zertifikat benötigt. Alternativ kann er auf einem separaten Server ausgeführt werden, der das Zertifikat nicht selbst verwendet, aber autorisiert ist, auf von der CA bereitgestellte Herausforderungen zu antworten. Der ACME-Server läuft bei der Zertifizierungsstelle und antwortet auf Client-Anfragen, indem er die angeforderten Operationen ausführt, wenn der Client dazu autorisiert ist.

Ein ACME-Client authentifiziert sich beim Server über ein „Kontoschlüsselpaar" (Account Key Pair). Der Client signiert alle an den Server gesendeten Nachrichten mit dem privaten Schlüssel dieses Schlüsselpaars. Der Server verwendet den öffentlichen Schlüssel, um die Authentizität und Integrität der Nachrichten vom Client zu überprüfen.

5. Character Encoding (Zeichenkodierung)​

Alle Anforderungen und Antworten, die von ACME-Clients, ACME-Servern und Validierungsservern über HTTP gesendet werden, sowie alle Eingaben für Digest-Berechnungen MÜSSEN (MUST) mit dem UTF-8-Zeichensatz [RFC3629] kodiert werden. Beachten Sie, dass Identifikatoren, die in Zertifikaten erscheinen, möglicherweise eigene Kodierungsüberlegungen haben (z. B. werden DNS-Namen mit Nicht-ASCII-Zeichen als A-Labels statt als U-Labels dargestellt). Solche Kodierungsüberlegungen SOLLTEN (SHOULD) vor der oben genannten UTF-8-Kodierung angewendet werden.

6. Message Transport (Nachrichtenübertragung)​

Die Kommunikation zwischen ACME-Clients und ACME-Servern erfolgt über HTTPS, wobei JSON Web Signature (JWS) [RFC7515] verwendet wird, um einige zusätzliche Sicherheitseigenschaften für Nachrichten bereitzustellen, die vom Client an den Server gesendet werden. HTTPS bietet Server-Authentifizierung und Vertraulichkeit. Mit einigen ACME-spezifischen Erweiterungen bietet JWS Authentifizierung der Client-Anforderungsnutzlast, Replay-Schutz und Integrität der HTTPS-Anforderungs-URL.

6.1. HTTPS Requests (HTTPS-Anforderungen)​

Jede ACME-Funktion wird durch eine Reihe von HTTPS-Anforderungen des Clients an den Server [RFC2818] ausgeführt, die JSON-Nachrichten [RFC8259] tragen. Die Verwendung von HTTPS ist ERFORDERLICH (REQUIRED). Jeder Unterabschnitt von Abschnitt 7 unten beschreibt das Nachrichtenformat, das für diese Funktion verwendet wird, und die Reihenfolge, in der Nachrichten gesendet werden.

In den meisten HTTPS-Transaktionen, die ACME verwendet, ist der ACME-Client der HTTPS-Client und der ACME-Server der HTTPS-Server. Der ACME-Server agiert als Client bei der Validierung von Herausforderungen: als HTTP-Client bei der Validierung von 'http-01'-Herausforderungen, als DNS-Client bei der Validierung von 'dns-01' usw.

ACME-Server SOLLTEN (SHOULD) bei der Konfiguration ihrer TLS-Implementierung den Empfehlungen von [RFC7525] folgen. ACME-Server, die TLS 1.3 unterstützen, KÖNNEN (MAY) Clients erlauben, Early Data (0-RTT) zu senden. Dies ist sicher, da das ACME-Protokoll selbst in allen Fällen, in denen es benötigt wird, Replay-Schutz enthält (siehe Abschnitt 6.5). Daher gibt es keine Einschränkungen dafür, welche ACME-Daten in 0-RTT übertragen werden können.

ACME-Clients MÜSSEN (MUST) das User-Agent-Headerfeld gemäß [RFC7231] senden. Dieses Headerfeld SOLLTE (SHOULD) neben dem Namen und der Version der zugrunde liegenden HTTP-Client-Software auch den Namen und die Version der ACME-Software enthalten.

ACME-Clients SOLLTEN (SHOULD) das Accept-Language-Headerfeld gemäß [RFC7231] senden, um die Lokalisierung von Fehlermeldungen zu ermöglichen.

ACME-Server, die allgemein zugänglich sein sollen, müssen Cross-Origin Resource Sharing (CORS) verwenden, damit sie von browserbasierten Clients zugänglich sind [W3C.REC-cors-20140116]. Solche Server SOLLTEN (SHOULD) das Access-Control-Allow-Origin-Headerfeld auf den Wert „*" setzen.

Binäre Felder in JSON-Objekten, die von ACME verwendet werden, werden mit der base64url-Kodierung gemäß Abschnitt 5 von [RFC4648] kodiert, entsprechend dem in JSON Web Signature in Abschnitt 2 von [RFC7515] angegebenen Profil. Diese Kodierung verwendet einen URL-sicheren Zeichensatz. Nachgestellte '='-Zeichen MÜSSEN (MUST) entfernt werden. Kodierte Werte, die nachgestellte '='-Zeichen enthalten, MÜSSEN (MUST) als falsch kodiert abgelehnt werden.

6.2. Request Authentication (Anforderungsauthentifizierung)​

Alle ACME-Anforderungen mit einem nicht leeren Körper MÜSSEN (MUST) ihre Nutzlast in einem JSON Web Signature (JWS) [RFC7515]-Objekt einschließen, das mit dem privaten Schlüssel des Kontos signiert ist, sofern nicht anders angegeben. Der Server MUSS (MUST) das JWS validieren, bevor er die Anforderung verarbeitet. Das Einschließen des Anforderungskörpers in ein JWS bietet Authentifizierung der Anforderung.

JWS-Objekte, die als ACME-Anforderungskörper gesendet werden, MÜSSEN (MUST) die folgenden zusätzlichen Kriterien erfüllen:

  • Das JWS MUSS (MUST) die flache JSON-Serialisierung (Flattened JSON Serialization) [RFC7515] verwenden

  • Das JWS DARF NICHT (MUST NOT) mehrere Signaturen haben

  • Die JWS Unencoded Payload Option (JWS Unencoded Payload Option) [RFC7797] DARF NICHT (MUST NOT) verwendet werden

  • Der JWS Unprotected Header (JWS Unprotected Header) [RFC7515] DARF NICHT (MUST NOT) verwendet werden

  • Die JWS-Nutzlast DARF NICHT (MUST NOT) getrennt werden

  • Der JWS Protected Header MUSS (MUST) die folgenden Felder enthalten:

    • „alg" (Algorithmus, Algorithm)

      • Dieses Feld DARF NICHT (MUST NOT) „none" oder einen Message Authentication Code (MAC)-Algorithmus enthalten (z. B. Algorithmen, bei denen die Beschreibung im Algorithmusregister MAC/HMAC erwähnt).

    • „nonce" (definiert in Abschnitt 6.5)

    • „url" (definiert in Abschnitt 6.4)

    • „jwk" (JSON Web Key) oder „kid" (Key ID), wie unten beschrieben

ACME-Server MÜSSEN (MUST) den Signaturalgorithmus „ES256" [RFC7518] implementieren und SOLLTEN (SHOULD) den Signaturalgorithmus „EdDSA" [RFC8037] mit der Variante „Ed25519" (angegeben durch „crv") implementieren.

Die Felder „jwk" und „kid" schließen sich gegenseitig aus. Der Server MUSS (MUST) Anforderungen ablehnen, die beide enthalten.

Für newAccount-Anforderungen sowie revokeCert-Anforderungen, die durch den Zertifikatsschlüssel authentifiziert werden, MUSS (MUST) ein „jwk"-Feld vorhanden sein. Dieses Feld MUSS (MUST) den öffentlichen Schlüssel enthalten, der dem privaten Schlüssel entspricht, der zum Signieren des JWS verwendet wurde.

Für alle anderen Anforderungen wird die Anforderung mit einem bestehenden Konto signiert, und es MUSS (MUST) ein „kid"-Feld vorhanden sein. Dieses Feld MUSS (MUST) die Konto-URL enthalten, die durch POST an die newAccount-Ressource empfangen wurde.

Wenn ein Client ein JWS sendet, das mit einem Algorithmus signiert ist, den der Server nicht unterstützt, MUSS (MUST) der Server den Statuscode 400 (Bad Request) und einen Fehler vom Typ „urn:ietf:params:acme:error:badSignatureAlgorithm" zurückgeben. Das mit dem Fehler zurückgegebene Problemdokument MUSS (MUST) ein „algorithms"-Feld enthalten, das ein Array der unterstützten „alg"-Werte enthält. Weitere Details zur Fehlerantwortstruktur finden Sie in Abschnitt 6.7.

Wenn der Server den Signaturalgorithmus „alg" unterstützt, aber den öffentlichen Schlüssel „jwk" nicht unterstützt oder ablehnt, MUSS (MUST) der Server den Statuscode 400 (Bad Request) und einen Fehler vom Typ „urn:ietf:params:acme:error:badPublicKey" zurückgeben. Die Details des Problemdokuments SOLLTEN (SHOULD) den Grund für die Ablehnung des öffentlichen Schlüssels beschreiben; einige Beispielgründe sind:

  • „alg" ist „RS256", aber der Modulus „n" ist zu klein (z. B. 512 Bit)

  • „alg" ist „ES256", aber „jwk" enthält keinen gültigen P-256-öffentlichen Schlüssel

  • „alg" ist „EdDSA" und „crv" ist „Ed448", aber der Server unterstützt nur „EdDSA" mit „Ed25519"

  • Der entsprechende private Schlüssel ist bekanntermaßen kompromittiert

Da Client-Anforderungen in ACME JWS-Objekte in der flachen JSON-Serialisierung tragen, MÜSSEN sie das Content-Type-Headerfeld auf „application/jose+json" setzen. Wenn eine Anforderung diese Anforderung nicht erfüllt, MUSS (MUST) der Server mit dem Statuscode 415 (Unsupported Media Type) antworten.

6.3. GET and POST-as-GET Requests (GET- und POST-as-GET-Anforderungen)​

Beachten Sie, dass die Authentifizierung über einen signierten JWS-Anforderungskörper bedeutet, dass Anforderungen ohne Entitätskörper nicht authentifiziert sind, insbesondere GET-Anforderungen. Außer in den in diesem Abschnitt beschriebenen Fällen MUSS (MUST) der Server, wenn er eine GET-Anforderung erhält, den Statuscode 405 (Method Not Allowed) und einen Fehler vom Typ „malformed" zurückgeben.

Wenn ein Client eine Ressource vom Server abrufen möchte (was sonst mit GET erfolgen würde), MUSS (MUST) er eine POST-Anforderung mit einem JWS-Körper wie oben beschrieben senden, wobei die Nutzlast des JWS eine Zeichenkette mit null Oktetten ist. Mit anderen Worten, das „payload"-Feld des JWS-Objekts MUSS (MUST) vorhanden und auf die leere Zeichenkette („") gesetzt sein.

Diese werden als „POST-as-GET"-Anforderungen bezeichnet. Beim Empfang einer Anforderung mit einer null langen (und damit nicht-JSON) Nutzlast MUSS (MUST) der Server den Absender authentifizieren und alle Zugriffssteuerungsregeln überprüfen. Andernfalls MUSS (MUST) der Server diese Anforderung so behandeln, als hätte sie dieselbe Semantik wie eine GET-Anforderung an dieselbe Ressource.

Der Server MUSS (MUST) GET-Anforderungen an die Verzeichnis- und newNonce-Ressourcen (siehe Abschnitt 7.1) sowie POST-as-GET-Anforderungen an diese Ressourcen zulassen. Dies ermöglicht es Clients, sich in das ACME-Authentifizierungssystem einzuführen.

6.4. Request URL Integrity (Anforderungs-URL-Integrität)​

In Bereitstellungen ist es üblich, dass die Entität, die TLS für HTTPS beendet, sich von der Entität unterscheidet, die den logischen HTTPS-Server betreibt, mit einer „Anforderungsrouting"-Schicht dazwischen. Beispielsweise könnte eine ACME-CA ein Content Delivery Network haben, das TLS-Verbindungen von Clients beendet, damit es Client-Anforderungen auf Denial-of-Service (DoS)-Schutz überprüfen kann.

Diese Vermittler können auch nicht signierte Anforderungswerte in HTTPS-Anforderungen ändern, wie z. B. die Anforderungs-URL und Headerfelder. ACME verwendet JWS, um einen Integritätsmechanismus bereitzustellen, der verhindert, dass Vermittler die Anforderungs-URL in eine andere ACME-URL ändern.

Wie in Abschnitt 6.2 beschrieben, tragen alle ACME-Anforderungsobjekte einen „url"-Headerparameter in ihrem Protected Header. Dieser Headerparameter kodiert die URL, an die der Client die Anforderung richtet. Beim Empfang eines solchen Objekts in einer HTTP-Anforderung MUSS (MUST) der Server den „url"-Headerparameter mit der Anforderungs-URL vergleichen. Wenn sie nicht übereinstimmen, MUSS (MUST) der Server die Anforderung als nicht autorisiert ablehnen.

Mit Ausnahme der Verzeichnisressource werden alle ACME-Ressourcen über URLs adressiert, die der Server dem Client bereitstellt. In POST-Anforderungen an diese Ressourcen MUSS (MUST) der Client den „url"-Headerparameter auf die genaue Zeichenkette setzen, die der Server bereitgestellt hat (ohne URL-Neukodierung durchzuführen). Der Server SOLLTE (SHOULD) eine entsprechende Zeichenkettengleichheitsprüfung durchführen, indem er für jede Ressource die dem Client bereitgestellte URL-Zeichenkette konfiguriert und die Ressource prüfen lässt, ob die Anforderung dieselbe Zeichenkette in ihrem „url"-Headerparameter hat. Wenn die Zeichenkettengleichheitsprüfung fehlschlägt, MUSS (MUST) der Server die Anforderung als nicht autorisiert ablehnen.

6.4.1. "url" (URL) JWS Header Parameter ("url" (URL) JWS-Headerparameter)​

Der „url"-Headerparameter gibt die URL [RFC3986] an, für die dieses JWS-Objekt bestimmt ist. Der „url"-Headerparameter MUSS (MUST) im Protected Header des JWS enthalten sein. Der Wert des „url"-Headerparameters MUSS (MUST) eine Zeichenkette sein, die die Ziel-URL darstellt.

6.5. Replay Protection (Replay-Schutz)​

Um ACME-Ressourcen vor möglichen Replay-Angriffen zu schützen, haben ACME-POST-Anforderungen einen obligatorischen Anti-Replay-Mechanismus. Dieser Mechanismus basiert darauf, dass der Server eine Liste der von ihm ausgestellten Nonces pflegt und verlangt, dass jede signierte Anforderung eines Clients eine solche Nonce enthält.

ACME-Server stellen Clients Nonces über das HTTP Replay-Nonce-Headerfeld bereit, wie in Abschnitt 6.5.1 beschrieben. Der Server MUSS (MUST) ein Replay-Nonce-Headerfeld in jede erfolgreiche Antwort auf eine POST-Anforderung aufnehmen und SOLLTE (SHOULD) es auch in Fehlerantworten bereitstellen.

Jedes von einem ACME-Client gesendete JWS MUSS (MUST) einen „nonce"-Headerparameter in seinem Protected Header enthalten, dessen Inhalt wie in Abschnitt 6.5.2 definiert ist. Als Teil der JWS-Validierung MUSS (MUST) der ACME-Server überprüfen, ob der Wert des „nonce"-Headers ein Wert ist, den der Server zuvor in einem Replay-Nonce-Headerfeld bereitgestellt hat. Sobald ein Nonce-Wert in einer ACME-Anforderung erscheint, MUSS (MUST) der Server ihn als ungültig behandeln, als ob er nie ausgestellt worden wäre.

Wenn der Server eine Anforderung aufgrund eines nicht akzeptablen (oder fehlenden) Nonce-Werts ablehnt, MUSS (MUST) er den HTTP-Statuscode 400 (Bad Request) mit dem ACME-Fehlertyp „urn:ietf:params:acme:error:badNonce" angeben. Eine Fehlerantwort mit dem Fehlertyp „badNonce" MUSS (MUST) ein Replay-Nonce-Headerfeld enthalten, das eine frische Nonce enthält, die der Server bei einem Wiederholungsversuch der ursprünglichen Abfrage akzeptieren wird (und möglicherweise bei anderen Anforderungen, gemäß der Nonce-Bereichsrichtlinie des Servers). Beim Empfang einer solchen Antwort SOLLTE (SHOULD) der Client die Anforderung mit der neuen Nonce wiederholen.

Die genaue Methode zur Generierung und Verfolgung von Nonces liegt im Ermessen des Servers. Beispielsweise kann ein Server für jede Antwort einen zufälligen 128-Bit-Wert generieren, eine Liste der ausgestellten Nonces führen und Nonces bei Verwendung aus dieser Liste entfernen.

Abgesehen von den oben genannten Einschränkungen bezüglich der in „badNonce"-Antworten ausgestellten Nonces schränkt ACME nicht ein, wie Server den Bereich von Nonces einschränken. Clients KÖNNEN (MAY) davon ausgehen, dass Nonces einen breiten Bereich haben, z. B. indem sie einen einzigen Nonce-Pool für alle Anforderungen verwenden. Bei der Wiederholung als Reaktion auf einen „badNonce"-Fehler MUSS (MUST) der Client jedoch die in der Fehlerantwort bereitgestellte Nonce verwenden. Server SOLLTEN den Bereich von Nonces so weit setzen, dass Wiederholungen selten erforderlich sind.

6.5.1. Replay-Nonce (Replay-Nonce-Headerfeld)​

Das Replay-Nonce-HTTP-Headerfeld enthält einen vom Server generierten Wert, den der Server verwenden kann, um nicht autorisierte Wiederholungen in zukünftigen Client-Anforderungen zu erkennen. Der Server MUSS (MUST) die im Replay-Nonce-Headerfeld bereitgestellten Werte so generieren, dass sie für jede Nachricht mit hoher Wahrscheinlichkeit eindeutig und für jeden außer dem Server unvorhersehbar sind. Beispielsweise ist die zufällige Generierung von Replay-Nonces akzeptabel.

Der Wert des Replay-Nonce-Headerfelds MUSS (MUST) eine Oktettenfolge sein, die gemäß der in Abschnitt 2 von [RFC7515] beschriebenen base64url-Kodierung kodiert ist. Clients MÜSSEN (MUST) ungültige Replay-Nonce-Werte ignorieren. Die ABNF [RFC5234] für das Replay-Nonce-Headerfeld lautet:

base64url = ALPHA / DIGIT / "-" / "_"

Replay-Nonce = 1*base64url

Das Replay-Nonce-Headerfeld SOLLTE NICHT (SHOULD NOT) in HTTP-Anforderungsnachrichten enthalten sein.

6.5.2. "nonce" (Nonce) JWS Header Parameter ("nonce" (Nonce) JWS-Headerparameter)​

Der „nonce"-Headerparameter stellt einen eindeutigen Wert bereit, der es dem Prüfer des JWS ermöglicht, zu erkennen, wann eine Wiederholung aufgetreten ist. Der „nonce"-Headerparameter MUSS (MUST) im Protected Header des JWS enthalten sein.

Der Wert des „nonce"-Headerparameters MUSS (MUST) eine Oktettenfolge sein, die gemäß der in Abschnitt 2 von [RFC7515] beschriebenen base64url-Kodierung kodiert ist. Wenn der Wert des „nonce"-Headerparameters gemäß dieser Kodierung ungültig ist, MUSS (MUST) der Prüfer das JWS als fehlerhaft ablehnen.

6.6. Rate Limits (Ratenbegrenzungen)​

ACME-Server KÖNNEN (MAY) die Ressourcenerstellung ratenbegrenzen, um eine faire Nutzung zu gewährleisten und Missbrauch zu verhindern. Sobald eine Ratenbegrenzung überschritten wird, MUSS (MUST) der Server mit einem Fehler vom Typ „urn:ietf:params:acme:error:rateLimited" antworten. Darüber hinaus SOLLTE (SHOULD) der Server ein Retry-After-Headerfeld [RFC7231] senden, das angibt, wann die aktuelle Anforderung möglicherweise wieder erfolgreich sein wird. Wenn mehrere Ratenbegrenzungen vorhanden sind, ist dies der Zeitpunkt, zu dem alle Ratenbegrenzungen die aktuelle Anforderung mit genau denselben Parametern erneut zulassen würden.

Zusätzlich zum menschenlesbaren „detail"-Feld der Fehlerantwort KANN (MAY) der Server einen oder mehrere Links im Link-Headerfeld [RFC8288] senden, die den Linkrelationstyp „help" verwenden, um auf Dokumentation über die ausgelöste spezifische Ratenbegrenzung zu verweisen.

6.7. Errors (Fehler)​

Fehler können auf der HTTP-Ebene und in Herausforderungsobjekten gemeldet werden, wie in Abschnitt 8 definiert. ACME-Server KÖNNEN (MAY) Antworten mit HTTP-Fehlerantwortcodes (4XX oder 5XX) zurückgeben. Wenn ein Client beispielsweise eine Anforderung mit einer in diesem Dokument nicht erlaubten Methode einreicht, KANN (MAY) der Server den Statuscode 405 (Method Not Allowed) zurückgeben.

Wenn der Server mit einem Fehlerstatus antwortet, SOLLTE (SHOULD) er zusätzliche Informationen über ein Problemdokument [RFC7807] bereitstellen. Um automatische Reaktionen auf Fehler zu erleichtern, definiert dieses Dokument die folgenden Standardtoken für das „type"-Feld (innerhalb des ACME-URN-Namensraums „urn:ietf:params:acme:error:"):

TypBeschreibung
accountDoesNotExistDas in der Anforderung angegebene Konto existiert nicht
alreadyRevokedDas in der Anforderung zum Widerruf angegebene Zertifikat wurde bereits widerrufen
badCSRDer CSR ist nicht akzeptabel (z. B. wegen zu kurzem Schlüssel)
badNonceDer Client hat eine nicht akzeptable Anti-Replay-Nonce gesendet
badPublicKeyDas JWS wurde mit einem öffentlichen Schlüssel signiert, den der Server nicht unterstützt
badRevocationReasonDer angegebene Widerrufsgrund ist vom Server nicht erlaubt
badSignatureAlgorithmDas JWS wurde mit einem Algorithmus signiert, den der Server nicht unterstützt
caaEin Certification Authority Authorization (CAA)-Eintrag verbietet der CA die Ausstellung des Zertifikats
compoundSpezifische Fehlerbedingungen sind im „subproblems"-Array angegeben
connectionDer Server konnte keine Verbindung zum Validierungsziel herstellen
dnsBei der DNS-Abfrage während der Identifikatorvalidierung ist ein Problem aufgetreten
externalAccountRequiredDie Anforderung muss einen Wert für das Feld „externalAccountBinding" enthalten
incorrectResponseDie empfangene Antwort stimmt nicht mit den Anforderungen der Herausforderung überein
invalidContactDie Kontakt-URL des Kontos ist ungültig
malformedDie Anforderungsnachricht ist fehlerhaft
orderNotReadyDie Anforderung versucht, eine Bestellung abzuschließen, die noch nicht bereit ist
rateLimitedDie Anforderung überschreitet eine Ratenbegrenzung
rejectedIdentifierDer Server stellt für diesen Identifikator kein Zertifikat aus
serverInternalDer Server hat einen internen Fehler festgestellt
tlsDer Server hat während der Validierung einen TLS-Fehler erhalten
unauthorizedDem Client fehlt die ausreichende Autorisierung
unsupportedContactDie Kontakt-URL des Kontos verwendet ein nicht unterstütztes Protokollschema
unsupportedIdentifierDer Identifikator ist ein nicht unterstützter Typ
userActionRequiredBesuchen Sie die „instance"-URL und führen Sie dort die angegebene Aktion durch

Diese Liste ist nicht erschöpfend. Server KÖNNEN (MAY) Fehler zurückgeben, deren „type"-Feld auf andere URIs als die oben definierten gesetzt ist. Server DÜRFEN NICHT (MUST NOT) den ACME-URN-Namensraum für Fehler verwenden, die nicht im entsprechenden IANA-Register aufgeführt sind (siehe Abschnitt 9.6). Clients SOLLTEN (SHOULD) das „detail"-Feld aller Fehler anzeigen.

Im Rest dieses Dokuments verwenden wir die Token aus der obigen Tabelle, um auf Fehlertypen zu verweisen, anstatt den vollständigen URN. Beispielsweise bezieht sich „ein Fehler vom Typ 'badCSR'" auf ein Fehlerdokument, dessen „type"-Wert „urn:ietf:params:acme:error:badCSR" ist.

6.7.1. Subproblems (Teilprobleme)​

Manchmal muss eine CA auf eine Anforderung mit mehreren Fehlern antworten. Darüber hinaus muss eine CA möglicherweise Fehler bestimmten Identifikatoren zuordnen. Beispielsweise kann eine newOrder-Anforderung mehrere Identifikatoren enthalten, für die die CA keine Zertifikate ausstellen kann. In diesem Fall KANN (MAY) das ACME-Problemdokument ein „subproblems"-Feld enthalten, das ein JSON-Array von Problemdokumenten enthält, von denen jedes ein „identifier"-Feld enthalten KANN (MAY). Wenn vorhanden, MUSS (MUST) das „identifier"-Feld einen ACME-Identifikator enthalten (Abschnitt 9.7.7).

Das „identifier"-Feld DARF NICHT (MUST NOT) auf der obersten Ebene eines ACME-Problemdokuments erscheinen. Es darf nur in Teilproblemen erscheinen. Teilprobleme müssen nicht alle denselben Typ haben, und sie müssen nicht mit dem Typ der obersten Ebene übereinstimmen.

ACME-Clients KÖNNEN (MAY) das „identifier"-Feld eines Teilproblems als Hinweis verwenden, dass die Operation erfolgreich wäre, wenn dieser Identifikator weggelassen würde. Wenn eine Bestellung beispielsweise zehn DNS-Identifikatoren enthält und die newOrder-Anforderung ein Problemdokument mit zwei Teilproblemen zurückgibt (die auf zwei dieser Identifikatoren verweisen), KANN (MAY) der ACME-Client eine weitere Bestellung einreichen, die nur die acht Identifikatoren enthält, die nicht im Problemdokument aufgeführt sind.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Link: `https://example.com/acme/directory`;rel="index"

{
    "type": "urn:ietf:params:acme:error:malformed",
    "detail": "Some of the identifiers requested were rejected",
    "subproblems": [
        {
            "type": "urn:ietf:params:acme:error:malformed",
            "detail": "Invalid underscore in DNS name \"_example.org\"",
            "identifier": {
                "type": "dns",
                "value": "_example.org"
            }
        },
        {
            "type": "urn:ietf:params:acme:error:rejectedIdentifier",
            "detail": "This CA will not issue for \"example.net\"",
            "identifier": {
                "type": "dns",
                "value": "example.net"
            }
        }
    ]
}

7. Certificate Management (Zertifikatsverwaltung)​

In diesem Abschnitt beschreiben wir die von ACME ermöglichten Zertifikatsverwaltungsfunktionen:

  • Kontoerstellung (Account Creation)
  • Bestellung eines Zertifikats (Ordering a Certificate)
  • Identifikatorautorisierung (Identifier Authorization)
  • Zertifikatsausstellung (Certificate Issuance)
  • Zertifikatswiderruf (Certificate Revocation)

7.1. Resources (Ressourcen)​

ACME ist als HTTP-basierte Anwendung mit den folgenden Ressourcentypen aufgebaut:

  • Kontoressourcen (Account Resources), die Informationen über ein Konto darstellen (Abschnitt 7.1.2, Abschnitt 7.3)
  • Bestellressourcen (Order Resources), die Anforderungen eines Kontos zur Zertifikatsausstellung darstellen (Abschnitt 7.1.3)
  • Autorisierungsressourcen (Authorization Resources), die die Autorisierung eines Kontos darstellen, für einen Identifikator zu handeln (Abschnitt 7.1.4)
  • Herausforderungsressourcen (Challenge Resources), die Herausforderungen zum Nachweis der Kontrolle über einen Identifikator darstellen (Abschnitt 7.5, Abschnitt 8)
  • Zertifikatsressourcen (Certificate Resources), die ausgestellte Zertifikate darstellen (Abschnitt 7.4.2)
  • Die „directory"-Ressource (Abschnitt 7.1.1)
  • Die „newNonce"-Ressource (Abschnitt 7.2)
  • Die „newAccount"-Ressource (Abschnitt 7.3)
  • Die „newOrder"-Ressource (Abschnitt 7.4)
  • Die „revokeCert"-Ressource (Abschnitt 7.6)
  • Die „keyChange"-Ressource (Abschnitt 7.3.5)

Der Server MUSS (MUST) die „directory"- und „newNonce"-Ressourcen bereitstellen.

ACME verwendet verschiedene URLs für verschiedene Verwaltungsfunktionen. Jede Funktion ist zusammen mit ihrer entsprechenden URL im Verzeichnis aufgeführt, sodass Clients nur die Verzeichnis-URL konfigurieren müssen. Diese URLs sind über mehrere verschiedene Linkrelationen [RFC8288] verbunden.

Die „up"-Linkrelation wird mit Herausforderungsressourcen verwendet, um die Autorisierungsressource anzugeben, zu der die Herausforderung gehört. Bei einigen Medientypen wird sie auch von Zertifikatsressourcen verwendet, um die Ressource anzugeben, von der der Client eine CA-Zertifikatskette abrufen kann, die zur Validierung des Zertifikats in der ursprünglichen Ressource verwendet werden kann.

Die „index"-Linkrelation erscheint auf allen Ressourcen außer dem Verzeichnis und gibt die URL des Verzeichnisses an.

Das folgende Diagramm veranschaulicht die Beziehungen zwischen Ressourcen auf einem ACME-Server. In den meisten Fällen werden diese Beziehungen durch URLs dargestellt, die als Zeichenketten in der JSON-Darstellung der Ressource bereitgestellt werden. Linien mit zitierten Beschriftungen stellen HTTP-Linkrelationen dar.

                              directory
                                  |
                                  +--> newNonce
                                  |
      +----------+----------+-----+-----+------------+
      |          |          |           |            |
      |          |          |           |            |
      V          V          V           V            V
 newAccount   newAuthz   newOrder   revokeCert   keyChange
      |          |          |
      |          |          |
      V          |          V
   account       |        order --+--> finalize
                 |          |     |
                 |          |     +--> cert
                 |          V
                 +---> authorization
                           | ^
                           | | "up"
                           V |
                         challenge

                 ACME-Ressourcen und Beziehungen

Die folgende Tabelle veranschaulicht die typische Abfolge von Anforderungen, die erforderlich sind, um ein neues Konto beim Server einzurichten, die Kontrolle über einen Identifikator nachzuweisen, ein Zertifikat auszustellen und zu einem späteren Zeitpunkt nach der Ausstellung ein aktualisiertes Zertifikat zu erhalten. „->" ist ein Mnemonic für das Location-Headerfeld, das auf die erstellte Ressource zeigt.

VorgangAnforderungAntwort
Verzeichnis abrufenGET directory200
Nonce abrufenHEAD newNonce200
Konto erstellenPOST newAccount201 -> account
Bestellung einreichenPOST newOrder201 -> order
Herausforderungen abrufenPOST-as-GET order's authorization urls200
Auf Herausforderungen antwortenPOST authorization challenge urls200
Status abfragenPOST-as-GET order200
Bestellung abschließenPOST order's finalize url200
Status abfragenPOST-as-GET order200
Zertifikat herunterladenPOST-as-GET order's certificate url200

Der Rest dieses Abschnitts enthält Details darüber, wie diese Ressourcen aufgebaut sind und wie das ACME-Protokoll sie verwendet.

7.1.1. Directory (Verzeichnis)​

Um Clients bei der Konfiguration der richtigen URL für jede ACME-Operation zu helfen, stellt der ACME-Server ein Verzeichnisobjekt bereit. Dies sollte die einzige URL sein, die zur Konfiguration eines Clients erforderlich ist. Es ist ein JSON-Objekt, dessen Feldnamen aus dem Ressourcenregister (Abschnitt 9.7.5) stammen und dessen Werte die entsprechenden URLs sind.

FeldURL in Wert
newNonceNeue Nonce
newAccountNeues Konto
newOrderNeue Bestellung
newAuthzNeue Autorisierung
revokeCertZertifikat widerrufen
keyChangeSchlüsselwechsel

Die URL des Verzeichnisses ist nicht eingeschränkt, außer dass sie sich von den URLs anderer ACME-Serverressourcen unterscheiden und nicht mit anderen Diensten in Konflikt geraten sollte. Zum Beispiel:

  • Ein Host, der sowohl als ACME- als auch als Webserver fungiert, möchte möglicherweise den Stammpfad „/" für eine HTML-„Startseite" reservieren und das ACME-Verzeichnis unter dem Pfad „/acme" platzieren.
  • Ein Host, der nur als ACME-Server fungiert, kann das Verzeichnis unter dem Pfad „/" platzieren.

Wenn der ACME-Server keine Vorautorisierung (Pre-authorization) (Abschnitt 7.4.1) implementiert, MUSS (MUST) er das „newAuthz"-Feld des Verzeichnisses weglassen.

Das Objekt KANN (MAY) zusätzlich ein „meta"-Feld enthalten. Wenn vorhanden, MUSS (MUST) es ein JSON-Objekt sein; jedes Feld im Objekt ist ein Metadatenelement, das sich auf den vom ACME-Server bereitgestellten Dienst bezieht.

Die folgenden Metadatenelemente sind definiert (Abschnitt 9.7.6), alle sind OPTIONAL:

termsOfService (optional, Zeichenkette): Eine URL, die die aktuellen Nutzungsbedingungen identifiziert.

website (optional, Zeichenkette): Eine HTTP- oder HTTPS-URL, die eine Website findet, die weitere Informationen über den ACME-Server bereitstellt.

caaIdentities (optional, Zeichenkettenarray): Hostnamen, die der ACME-Server als Verweis auf sich selbst erkennt, zur Verwendung bei der CAA-Eintragsvalidierung gemäß [RFC6844]. Jede Zeichenkette MUSS (MUST) dieselbe ASCII-Codepunktsequenz darstellen, die der Server im CAA-Issue- oder Issuewild-Attributtag als „Issuer Domain Name" erwartet. Dies ermöglicht es Clients, den richtigen Ausstellerdomainnamen zu bestimmen, der bei der Konfiguration von CAA-Einträgen verwendet werden soll.

externalAccountRequired (optional, Boolean): Wenn dieses Feld vorhanden und auf „true" gesetzt ist, verlangt die CA, dass alle newAccount-Anforderungen ein „externalAccountBinding"-Feld enthalten, das das neue Konto mit einem externen Konto verknüpft.

Clients greifen auf das Verzeichnis zu, indem sie eine GET-Anforderung an die Verzeichnis-URL senden.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "newNonce": "https://example.com/acme/new-nonce",
  "newAccount": "https://example.com/acme/new-account",
  "newOrder": "https://example.com/acme/new-order",
  "newAuthz": "https://example.com/acme/new-authz",
  "revokeCert": "https://example.com/acme/revoke-cert",
  "keyChange": "https://example.com/acme/key-change",
  "meta": {
    "termsOfService": "https://example.com/acme/terms/2017-5-30",
    "website": "https://www.example.com/",
    "caaIdentities": ["example.com"],
    "externalAccountRequired": false
  }
}

7.1.2. Account Objects (Kontoobjekte)​

Eine ACME-Kontoressource stellt eine Reihe von Metadaten dar, die einem Konto zugeordnet sind. Eine Kontoressource hat die folgende Struktur:

status (erforderlich, Zeichenkette): Der Status dieses Kontos. Mögliche Werte sind „valid", „deactivated" und „revoked". Der Wert „deactivated" SOLLTE (SHOULD) verwendet werden, um eine vom Client initiierte Deaktivierung anzuzeigen, während „revoked" für eine vom Server initiierte Deaktivierung verwendet werden SOLLTE (SHOULD). Siehe Abschnitt 7.1.6.

contact (optional, Zeichenkettenarray): Ein Array von URLs, die der Server verwenden kann, um den Client bezüglich Problemen im Zusammenhang mit diesem Konto zu kontaktieren. Beispielsweise möchte der Server den Client möglicherweise über vom Server initiierte Widerrufe oder Zertifikatsabläufe informieren. Informationen zu unterstützten URL-Schemata finden Sie in Abschnitt 7.3.

termsOfServiceAgreed (optional, Boolean): Die Aufnahme dieses Feldes mit dem Wert true in eine newAccount-Anforderung zeigt an, dass der Client den Nutzungsbedingungen zustimmt. Dieses Feld kann vom Client nicht aktualisiert werden.

externalAccountBinding (optional, Objekt): Die Aufnahme dieses Feldes in eine newAccount-Anforderung zeigt an, dass der Inhaber eines bestehenden Nicht-ACME-Kontos die Bindung dieses Kontos an dieses ACME-Konto genehmigt. Dieses Feld kann vom Client nicht aktualisiert werden (siehe Abschnitt 7.3.4).

orders (erforderlich, Zeichenkette): Eine URL, von der eine Liste der von diesem Konto eingereichten Bestellungen über eine POST-as-GET-Anforderung abgerufen werden kann, wie in Abschnitt 7.1.2.1 beschrieben.

{
  "status": "valid",
  "contact": [
    "mailto:[email protected]",
    "mailto:[email protected]"
  ],
  "termsOfServiceAgreed": true,
  "orders": "https://example.com/acme/orders/rzGoeA"
}
7.1.2.1. Orders List (Bestellungsliste)​

Jedes Kontoobjekt enthält eine „orders"-URL, von der eine Liste der vom Konto erstellten Bestellungen über eine POST-as-GET-Anforderung abgerufen werden kann. Das Ergebnis der Anforderung MUSS (MUST) ein JSON-Objekt sein, dessen „orders"-Feld ein Array von URLs ist, von denen jede eine Bestellung identifiziert, die zu diesem Konto gehört. Der Server SOLLTE (SHOULD) ausstehende Bestellungen einschließen und SOLLTE NICHT (SHOULD NOT) ungültige Bestellungen in das URL-Array aufnehmen. Der Server KANN (MAY) eine unvollständige Liste zurückgeben, zusammen mit einem Link-Headerfeld mit der „next"-Linkrelation, das angibt, wo weitere Einträge abgerufen werden können.

HTTP/1.1 200 OK
Content-Type: application/json
Link: `https://example.com/acme/directory`;rel="index"
Link: `https://example.com/acme/orders/rzGoeA?cursor=2`;rel="next"

{
  "orders": [
    "https://example.com/acme/order/TOlocE8rfgo",
    "https://example.com/acme/order/4E16bbL5iSw",
    /* Weitere URLs der Kürze halber nicht angezeigt */
    "https://example.com/acme/order/neBHYLfw0mg"
  ]
}

7.1.3. Order Objects (Bestellungsobjekte)​

Ein ACME-Bestellungsobjekt stellt die Anforderung eines Clients für ein Zertifikat dar und wird verwendet, um den Fortschritt dieser Bestellung bis zur Ausstellung zu verfolgen. Daher enthält das Objekt Informationen über das angeforderte Zertifikat, die Autorisierungen, die der Server vom Client verlangt, und alle Zertifikate, die aus dieser Bestellung resultieren.

status (erforderlich, Zeichenkette): Der Status dieser Bestellung. Mögliche Werte sind „pending", „ready", „processing", „valid" und „invalid". Siehe Abschnitt 7.1.6.

expires (optional, Zeichenkette): Der Zeitstempel, nach dem der Server diese Bestellung als ungültig betrachtet, kodiert im in [RFC3339] angegebenen Format. Dieses Feld ist ERFORDERLICH (REQUIRED) für Objekte mit „pending" oder „valid" im Statusfeld.

identifiers (erforderlich, Objektarray): Ein Array von Identifikatorobjekten, auf die sich die Bestellung bezieht.

  • type (erforderlich, Zeichenkette): Der Typ des Identifikators. Dieses Dokument definiert den Identifikatortyp „dns". Für andere Typen siehe das in Abschnitt 9.7.7 definierte Register.

  • value (erforderlich, Zeichenkette): Der Identifikator selbst.

notBefore (optional, Zeichenkette): Der angeforderte Wert für das notBefore-Feld im Zertifikat, im in [RFC3339] definierten Datumsformat.

notAfter (optional, Zeichenkette): Der angeforderte Wert für das notAfter-Feld im Zertifikat, im in [RFC3339] definierten Datumsformat.

error (optional, Objekt): Der Fehler, der bei der Verarbeitung der Bestellung aufgetreten ist, falls vorhanden. Dieses Feld ist als Problemdokument [RFC7807] strukturiert.

authorizations (erforderlich, Zeichenkettenarray): Für ausstehende Bestellungen die Autorisierungen, die der Client abschließen muss, bevor das angeforderte Zertifikat ausgestellt wird (siehe Abschnitt 7.5), einschließlich nicht abgelaufener Autorisierungen, die der Client zuvor für Identifikatoren abgeschlossen hat, die in der Bestellung angegeben sind. Die erforderlichen Autorisierungen werden durch die Serverrichtlinie bestimmt; es gibt möglicherweise keine 1:1-Beziehung zwischen Bestellungsidentifikatoren und erforderlichen Autorisierungen. Für abgeschlossene Bestellungen (im Status „valid" oder „invalid") die abgeschlossenen Autorisierungen. Jeder Eintrag ist eine URL, von der die Autorisierung über eine POST-as-GET-Anforderung abgerufen werden kann.

finalize (erforderlich, Zeichenkette): Sobald alle Autorisierungen der Bestellung erfüllt sind, MUSS (MUST) ein CSR an diese URL gepostet werden, um die Bestellung abzuschließen. Das Ergebnis eines erfolgreichen Abschlusses ist die Zertifikats-URL der Bestellung.

certificate (optional, Zeichenkette): Eine URL für das Zertifikat, das als Antwort auf diese Bestellung ausgestellt wurde.

{
  "status": "valid",
  "expires": "2016-01-20T14:09:07.99Z",

  "identifiers": [
    { "type": "dns", "value": "www.example.org" },
    { "type": "dns", "value": "example.org" }
  ],

  "notBefore": "2016-01-01T00:00:00Z",
  "notAfter": "2016-01-08T00:00:00Z",

  "authorizations": [
    "https://example.com/acme/authz/PAniVnsZcis",
    "https://example.com/acme/authz/r4HqLzrSrpI"
  ],

  "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",

  "certificate": "https://example.com/acme/cert/mAt3xBGaobw"
}

Jeder Identifikator vom Typ „dns" in einer newOrder-Anforderung KANN (MAY) einen Wildcard-Domainnamen als Wert haben. Ein Wildcard-Domainname besteht aus einem einzelnen Sternchen-Zeichen gefolgt von einem einzelnen Punkt-Zeichen („.") gefolgt von einem Domainnamen, wie er in [RFC5280] für die Verwendung in der Subject Alternative Name-Erweiterung definiert ist. Die Autorisierungen, die der Server für Wildcard-Domainname-Identifikatoren zurückgibt, DÜRFEN NICHT (MUST NOT) das Sternchen- und Punkt-Präfix („.") im Autorisierungsidentifikatorwert enthalten. Die zurückgegebenen Autorisierungen MÜSSEN (MUST) das optionale „wildcard"-Feld mit dem Wert true enthalten.

Die Elemente der „authorizations"- und „identifiers"-Arrays sind unveränderlich, sobald sie gesetzt sind. Der Server DARF NICHT (MUST NOT) den Inhalt eines der Arrays nach der Erstellung ändern. Wenn ein Client eine Änderung des Inhalts eines der Arrays beobachtet, SOLLTE (SHOULD) er die Bestellung als ungültig betrachten.

Das „authorizations"-Array einer Bestellung SOLLTE (SHOULD) alle Autorisierungen widerspiegeln, die die CA bei der Entscheidung zur Ausstellung berücksichtigt, auch wenn einige Autorisierungen in früheren Bestellungs- oder Vorautorisierungstransaktionen abgeschlossen wurden. Wenn die CA beispielsweise erlaubt, mehrere Bestellungen auf der Grundlage einer einzigen Autorisierungstransaktion abzuschließen, SOLLTE (SHOULD) sie diese Autorisierung in allen Bestellungen widerspiegeln.

Beachten Sie, dass die bloße Auflistung einer Autorisierungs-URL im „authorizations"-Array eines Bestellungsobjekts nicht bedeutet, dass der Client handeln muss. Es gibt mehrere Gründe, warum eine referenzierte Autorisierung möglicherweise bereits gültig ist:

  • Der Client hat die Autorisierung als Teil einer früheren Bestellung abgeschlossen
  • Der Client hat den Identifikator zuvor vorautorisiert (siehe Abschnitt 7.4.1)
  • Der Server hat dem Client die Autorisierung basierend auf einem externen Konto gewährt

Clients SOLLTEN (SHOULD) das „status"-Feld der Bestellung überprüfen, um festzustellen, ob Maßnahmen erforderlich sind.

Hinweis: Da Kapitel 7 sehr umfangreich ist, enthält diese Datei nur die Abschnitte 7.1–7.1.3. Die Abschnitte 7.1.4–7.3.4 werden in Part 2 fortgesetzt.

8. Identifier Validation Challenges (Identifikator-Validierungsherausforderungen)​

Es gibt nur wenige Identifikatortypen in der Welt, für die es standardisierte Mechanismen gibt, um den Besitz eines bestimmten Identifikators nachzuweisen. In allen praktischen Fällen verlassen sich CAs auf verschiedene Mittel, um zu testen, ob eine Entität, die ein Zertifikat für einen bestimmten Identifikator beantragt, diesen Identifikator tatsächlich kontrolliert.

Herausforderungen geben dem Server die Gewissheit, dass der Kontoinhaber auch die Entität ist, die den Identifikator kontrolliert. Für jeden Herausforderungstyp müssen die folgenden Bedingungen erfüllt sein: Damit eine Entität eine Herausforderung erfolgreich abschließt, muss die Entität gleichzeitig:

  • den privaten Schlüssel des Kontoschlüsselpaars besitzen, das zur Beantwortung der Herausforderung verwendet wird, und
  • den betreffenden Identifikator kontrollieren.

Abschnitt 10 dokumentiert, wie die in diesem Dokument definierten Herausforderungen diese Anforderungen erfüllen. Neue Herausforderungen müssen dokumentieren, wie sie diese erfüllen.

ACME verwendet ein erweiterbares Herausforderungs-/Antwort-Framework für die Identifikatorvalidierung. Der Server präsentiert dem Client eine Reihe von Herausforderungen (als Objekte im „challenges"-Array) im Autorisierungsobjekt, das an den Client gesendet wird, und der Client antwortet, indem er ein Antwortobjekt in einer POST-Anforderung an die Herausforderungs-URL sendet.

Dieser Abschnitt beschreibt eine Reihe von anfänglichen Herausforderungstypen. Die Definition eines Herausforderungstyps umfasst:

  1. Den Inhalt des Herausforderungsobjekts
  2. Den Inhalt des Antwortobjekts
  3. Wie der Server die Herausforderung und die Antwort verwendet, um die Kontrolle über den Identifikator zu validieren

Herausforderungsobjekte enthalten alle die folgenden Basisfelder:

type (erforderlich, Zeichenkette): Der im Objekt kodierte Herausforderungstyp.

url (erforderlich, Zeichenkette): Die URL, an die eine Antwort gesendet werden kann.

status (erforderlich, Zeichenkette): Der Status dieser Herausforderung. Mögliche Werte sind „pending", „processing", „valid" und „invalid" (siehe Abschnitt 7.1.6).

validated (optional, Zeichenkette): Der Zeitpunkt, zu dem der Server diese Herausforderung validiert hat, kodiert im in [RFC3339] angegebenen Format. Dieses Feld ist ERFORDERLICH (REQUIRED), wenn das „status"-Feld „valid" ist.

error (optional, Objekt): Der Fehler, der beim Validieren der Herausforderung durch den Server aufgetreten ist, falls vorhanden, strukturiert als Problemdokument [RFC7807]. Mehrere Fehler können mit Teilproblemen (Abschnitt 6.7.1) angegeben werden. Der Status eines Herausforderungsobjekts mit Fehlern MUSS (MUST) „invalid" sein.

Alle anderen Felder werden durch den Herausforderungstyp angegeben. Wenn der Server den „status" einer Herausforderung auf „invalid" setzt, SOLLTE (SHOULD) er auch das „error"-Feld einschließen, um dem Client bei der Diagnose des Grundes für das Scheitern der Herausforderung zu helfen.

Verschiedene Herausforderungen ermöglichen es dem Server, Nachweise über verschiedene Aspekte der Kontrolle über einen Identifikator zu erhalten. Bei einigen Herausforderungen, wie HTTP und DNS, weist der Client direkt seine Fähigkeit nach, bestimmte Operationen im Zusammenhang mit dem Identifikator durchzuführen. Die Wahl, welche Herausforderungen dem Client unter welchen Umständen angeboten werden, ist eine Frage der Serverrichtlinie.

Die in diesem Abschnitt beschriebenen Identifikator-Validierungsherausforderungen beziehen sich alle auf die Domainvalidierung. Wenn ACME in Zukunft erweitert wird, um andere Identifikatortypen zu unterstützen, werden neue Herausforderungstypen benötigt, und diese müssen angeben, für welche Identifikatortypen sie gelten.

8.1. Key Authorizations (Schlüsselautorisierungen)​

Alle in diesem Dokument definierten Herausforderungen verwenden Schlüsselautorisierungszeichenketten. Eine Schlüsselautorisierung ist eine Zeichenkette, die das Token der Herausforderung mit einem Schlüssel-Fingerabdruck verbindet, getrennt durch ein „."-Zeichen:

keyAuthorization = token || '.' || base64url(Thumbprint(accountKey))

Der „Thumbprint"-Schritt stellt die in [RFC7638] angegebene Berechnung dar, unter Verwendung des SHA-256-Digests [FIPS180-4]. Wie in [RFC7518] beschrieben, MÜSSEN (MUST) alle führenden Null-Oktette in JWK-Objektfeldern vor der Berechnung entfernt werden.

Wie in den einzelnen Herausforderungen unten angegeben, ist das Token einer Herausforderung eine Zeichenkette, die ausschließlich aus Zeichen des URL-sicheren base64-Alphabets besteht. Der „||"-Operator stellt die Verkettung von Zeichenketten dar.

8.2. Retrying Challenges (Wiederholen von Herausforderungen)​

ACME-Herausforderungen erfordern in der Regel, dass der Client eine netzwerkzugängliche Ressource einrichtet, die der Server abfragen kann, um zu überprüfen, ob der Client den Identifikator kontrolliert. In der Praxis ist es nicht ungewöhnlich, dass die Abfrage des Servers beim Einrichten der Ressource fehlschlägt, z. B. weil Informationen sich in einem Cluster verbreiten oder Firewall-Regeln noch nicht in Kraft sind.

Clients SOLLTEN NICHT (SHOULD NOT) auf Herausforderungen antworten, bis sie glauben, dass die Abfrage des Servers erfolgreich sein wird. Wenn die anfängliche Validierungsabfrage des Servers fehlschlägt, SOLLTE (SHOULD) der Server die Abfrage nach einer Weile wiederholen, um Verzögerungen beim Einrichten der Antwort (wie DNS-Einträge oder HTTP-Ressourcen) zu berücksichtigen. Der genaue Wiederholungsplan liegt im Ermessen des Servers, aber Serverbetreiber sollten die Betriebsszenarien im Hinterkopf behalten, die der Plan zu berücksichtigen versucht. Da Wiederholungen darauf abzielen, Probleme wie Ausbreitungsverzögerungen in HTTP- oder DNS-Konfigurationen zu lösen, sollte es in der Regel keinen Grund geben, öfter als alle 5 oder 10 Sekunden zu wiederholen. Während der Server noch versucht, bleibt der Status der Herausforderung „processing"; erst nachdem der Server aufgegeben hat, wird sie als „invalid" markiert.

Der Server MUSS (MUST) dem Client Informationen über seinen Wiederholungsstatus über das „error"-Feld in der Herausforderung und das Retry-After-HTTP-Headerfeld in Antworten auf Herausforderungsressourcenanforderungen bereitstellen. Der Server MUSS (MUST) nach jeder fehlgeschlagenen Validierungsabfrage einen Eintrag zum „error"-Feld in der Herausforderung hinzufügen. Der Server SOLLTE (SHOULD) das Retry-After-Headerfeld auf einen Zeitpunkt nach der nächsten Validierungsabfrage des Servers setzen, da sich der Status der Herausforderung vor diesem Zeitpunkt nicht ändern wird.

Ein Client kann explizit eine Wiederholung anfordern, indem er die Antwort auf die Herausforderung in einer neuen POST-Anforderung erneut sendet (mit einer neuen Nonce usw.). Dies ermöglicht es dem Client, eine Wiederholung anzufordern, wenn sich der Zustand geändert hat (z. B. nach der Aktualisierung von Firewall-Regeln). Der Server SOLLTE (SHOULD) die Anforderung sofort wiederholen, wenn er eine solche POST-Anforderung erhält. Um Denial-of-Service-Angriffe durch clientinitiierte Wiederholungen zu vermeiden, SOLLTE (SHOULD) der Server solche Anforderungen ratenbegrenzen.

8.3. HTTP Challenge (HTTP-Herausforderung)​

Bei der HTTP-Validierung weist der Client in einer ACME-Transaktion seine Kontrolle über einen Domainnamen nach, indem er beweist, dass er eine HTTP-Ressource auf einem unter diesem Domainnamen zugänglichen Server konfigurieren kann. Der ACME-Server fordert den Client auf, eine Datei unter einem bestimmten Pfad zu konfigurieren, mit einer bestimmten Zeichenkette als Inhalt.

Da ein Domainname möglicherweise mehrere IPv4- und IPv6-Adressen auflöst, verbindet sich der Server nach eigenem Ermessen mit mindestens einem der in den DNS-A- und AAAA-Einträgen gefundenen Hosts. Da viele Webserver den Standard-HTTPS-Virtual-Host auf subtile und nicht intuitive Weise bestimmten Mietern mit niedrigen Berechtigungen zuweisen, MUSS die Herausforderung über HTTP und nicht über HTTPS abgeschlossen werden.

type (erforderlich, Zeichenkette): Die Zeichenkette „http-01".

token (erforderlich, Zeichenkette): Ein zufälliger Wert, der die Herausforderung eindeutig identifiziert. Dieser Wert MUSS (MUST) mindestens 128 Bit Entropie haben. Er DARF NICHT (MUST NOT) Zeichen außerhalb des base64url-Alphabets enthalten und DARF NICHT (MUST NOT) base64-Füllzeichen („=") enthalten. Weitere Informationen zu Zufälligkeitsanforderungen finden Sie in [RFC4086].

{
  "type": "http-01",
  "url": "https://example.com/acme/chall/prV_B7yEyA4",
  "status": "pending",
  "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0"
}

Der Client schließt diese Herausforderung ab, indem er eine Schlüsselautorisierung aus dem in der Herausforderung bereitgestellten „token"-Wert und dem Kontoschlüssel des Clients konstruiert. Der Client konfiguriert dann die Schlüsselautorisierung als Ressource auf dem HTTP-Server für den betreffenden Domainnamen.

Der Pfad, unter dem die Ressource konfiguriert wird, besteht aus dem festen Präfix „/.well-known/acme-challenge/" gefolgt vom „token"-Wert in der Herausforderung. Der Wert der Ressource MUSS (MUST) die ASCII-Darstellung der Schlüsselautorisierung sein.

GET /.well-known/acme-challenge/LoqXcYV8...jxAjEuX0
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/octet-stream

LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI

(Im obigen Beispiel zeigt „..." an, dass das Token und der JWK-Fingerabdruck in der Schlüsselautorisierung abgeschnitten wurden, um auf die Seite zu passen.)

Der Client antwortet mit einem leeren Objekt ({}), um zu bestätigen, dass der Server die Herausforderung validieren kann.

POST /acme/chall/prV_B7yEyA4
Host: example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "UQI1PoRi5OuXzxuX7V7wL0",
    "url": "https://example.com/acme/chall/prV_B7yEyA4"
  }),
  "payload": base64url({}),
  "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
}

Beim Empfang der Antwort konstruiert und speichert der Server die Schlüsselautorisierung aus dem Herausforderungs-„token"-Wert und dem aktuellen Kontoschlüssel des Clients.

Anhand des Herausforderungs-/Antwortpaares validiert der Server die Kontrolle des Clients über den Domainnamen, indem er überprüft, ob die Ressource wie erwartet konfiguriert ist.

  1. Konstruieren der URL durch Ausfüllen der URL-Vorlage [RFC6570] „http://{domain}/.well-known/acme-challenge/{token}", wobei:

    • das domain-Feld auf den zu validierenden Domainnamen gesetzt wird; und
    • das token-Feld auf das Token in der Herausforderung gesetzt wird.

  2. Überprüfen, ob die resultierende URL wohlgeformt ist.

  3. Dereferenzieren der URL mit einer HTTP-GET-Anforderung. Diese Anforderung MUSS (MUST) an TCP-Port 80 auf dem HTTP-Server gesendet werden.

  4. Überprüfen, ob der Körper der Antwort eine wohlgeformte Schlüsselautorisierung ist. Der Server SOLLTE (SHOULD) Leerzeichen am Ende des Körpers ignorieren.

  5. Überprüfen, ob die vom HTTP-Server bereitgestellte Schlüsselautorisierung mit der vom Server gespeicherten Schlüsselautorisierung übereinstimmt.

Der Server SOLLTE (SHOULD) beim Dereferenzieren der URL Weiterleitungen folgen. Beispielsweise kann ein Client Weiterleitungen verwenden, damit die Antwort von einem zentralisierten Zertifikatsverwaltungsserver bereitgestellt werden kann. Sicherheitsüberlegungen im Zusammenhang mit Weiterleitungen finden Sie in Abschnitt 10.2.

Wenn alle oben genannten Validierungen erfolgreich sind, ist die Validierung erfolgreich. Wenn die Anforderung fehlschlägt oder der Körper diese Prüfungen nicht besteht, schlägt die Validierung fehl.

Clients SOLLTEN (SHOULD) die für diese Herausforderung konfigurierten Ressourcen nach Abschluss der Herausforderung entfernen, d. h. sobald der Wert des „status"-Felds der Herausforderung „valid" oder „invalid" ist.

Beachten Sie, dass das Token sowohl in der vom ACME-Server gesendeten Anforderung als auch in der Schlüsselautorisierung in der Antwort erscheint, sodass es möglich ist, Clients zu erstellen, die das Token von der Anforderung in die Antwort kopieren. Clients SOLLTEN dieses Verhalten vermeiden, da es zu Cross-Site-Scripting-Schwachstellen führen kann; stattdessen SOLLTEN Clients eine explizite Konfiguration auf Basis jeder Herausforderung vornehmen. Clients, die das Token tatsächlich von der Anforderung in die Antwort kopieren, MÜSSEN (MUST) überprüfen, ob das Token in der Anforderung der oben genannten Token-Syntax entspricht (z. B. enthält es nur Zeichen aus dem base64url-Alphabet).

8.4. DNS Challenge (DNS-Herausforderung)​

Wenn der zu validierende Identifikator ein Domainname ist, kann der Client seine Kontrolle über diesen Domainnamen nachweisen, indem er einen TXT-Ressourceneintrag mit einem angegebenen Wert für einen bestimmten Validierungsdomainnamen konfiguriert.

type (erforderlich, Zeichenkette): Die Zeichenkette „dns-01".

token (erforderlich, Zeichenkette): Ein zufälliger Wert, der die Herausforderung eindeutig identifiziert. Dieser Wert MUSS (MUST) mindestens 128 Bit Entropie haben. Er DARF NICHT (MUST NOT) Zeichen außerhalb des base64url-Alphabets enthalten, einschließlich Füllzeichen („="). Weitere Informationen zu Zufälligkeitsanforderungen finden Sie in [RFC4086].

{
  "type": "dns-01",
  "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
  "status": "pending",
  "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
}

Der Client schließt diese Herausforderung ab, indem er eine Schlüsselautorisierung aus dem in der Herausforderung bereitgestellten „token"-Wert und dem Kontoschlüssel des Clients konstruiert. Der Client berechnet dann den SHA-256-Digest [FIPS180-4] der Schlüsselautorisierung.

Der in DNS konfigurierte Eintrag enthält die base64url-Kodierung dieses Digests. Der Client konstruiert den Validierungsdomainnamen, indem er dem zu validierenden Domainnamen das Label „_acme-challenge" voranstellt, und konfiguriert dann einen TXT-Eintrag mit dem Digest-Wert unter diesem Namen. Wenn der zu validierende Domainname beispielsweise „www.example.org" ist, konfiguriert der Client den folgenden DNS-Eintrag:

_acme-challenge.www.example.org. 300 IN TXT "gfj9Xq...Rg85nM"

Der Client antwortet mit einem leeren Objekt ({}), um zu bestätigen, dass der Server die Herausforderung validieren kann.

POST /acme/chall/Rg5dV14Gh1Q
Host: example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "SS2sSl1PtspvFZ08kNtzKd",
    "url": "https://example.com/acme/chall/Rg5dV14Gh1Q"
  }),
  "payload": base64url({}),
  "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
}

Beim Empfang der Antwort konstruiert und speichert der Server die Schlüsselautorisierung aus dem Herausforderungs-„token"-Wert und dem aktuellen Kontoschlüssel des Clients.

Um die DNS-Herausforderung zu validieren, führt der Server die folgenden Schritte aus:

  1. Berechnen des SHA-256-Digests [FIPS180-4] der gespeicherten Schlüsselautorisierung

  2. Abfragen der TXT-Einträge für den Validierungsdomainnamen

  3. Überprüfen, ob der Inhalt eines der TXT-Einträge mit dem Digest-Wert übereinstimmt

Wenn alle oben genannten Validierungen erfolgreich sind, ist die Validierung erfolgreich. Wenn keine DNS-Einträge gefunden werden oder die DNS-Einträge und die Antwortnutzlast diese Prüfungen nicht bestehen, schlägt die Validierung fehl.

Clients SOLLTEN (SHOULD) die für diese Herausforderung konfigurierten Ressourceneinträge nach Abschluss der Herausforderung entfernen, d. h. sobald der Wert des „status"-Felds der Herausforderung „valid" oder „invalid" ist.

RFC 8555 Kapitel 9–12 Zusammenfassung​

Hinweis: Dieses Dokument enthält eine Zusammenfassung der wichtigsten Punkte aus den Kapiteln 9–12 von RFC 8555. Vollständige technische Details finden Sie im offiziellen RFC-8555-Dokument.

9. IANA Considerations (IANA-Überlegungen)​

9.1 Medientypregistrierung​

  • application/pem-certificate-chain: PEM-Format für Zertifikatsketten

9.2 Well-Known URI​

  • /.well-known/acme-challenge: Standardpfad für HTTP-Herausforderungen

9.3 HTTP-Headerfelder​

  • Replay-Nonce: Anti-Replay-Nonce-Headerfeld

9.4–9.5 JWS-Headerparameter​

  • url: URL-Parameter im JWS
  • nonce: Nonce-Parameter im JWS

9.6 URN-Namensraum​

  • urn:ietf:params:acme: URN-Namensraum für das ACME-Protokoll

9.7 Neue Register​

IANA hat für ACME die folgenden Register erstellt:

  1. Account Object Fields (Kontoobjektfelder)
  2. Order Object Fields (Bestellungsobjektfelder)
  3. Authorization Object Fields (Autorisierungsobjektfelder)
  4. Error Types (Fehlertypen)
  5. Resource Types (Ressourcentypen)
  6. Directory Metadata Fields (Verzeichnis-Metadatenfelder)
  7. Identifier Types (Identifikatortypen)
  8. Validation Methods (Validierungsmethoden)

10. Security Considerations (Sicherheitsüberlegungen)​

10.1 Bedrohungsmodell​

Die zwei wichtigsten Sicherheitsziele von ACME:

  1. Nur die Entität, die einen Identifikator kontrolliert, kann eine Autorisierung für diesen Identifikator erhalten.
  2. Nach der Autorisierung kann die Autorisierung eines Kontoschlüssels nicht von einem anderen Konto missbräuchlich verwendet werden.

Kommunikationskanäle:

  • ACME-Kanal: HTTPS-Anforderungen zwischen Client und Server
  • Validierungskanal: Der Kanal, über den der Server Validierungsabfragen durchführt

10.2 Integrität der Autorisierung​

Schlüsselbindung: Alle Herausforderungen binden den privaten Kontoschlüssel über Schlüsselautorisierungen an die Validierungsabfrage.

Mögliche Angriffe:

  • MitM-Angriffe: CDNs oder Reverse-Proxys können als Man-in-the-Middle fungieren
  • DNS-Angriffe: Angreifer können die Validierung durch DNS-Hijacking beeinflussen
  • Risiken durch Hosting-Anbieter: Hosting-Dienstanbieter könnten die Validierung manipulieren

Schutzmaßnahmen:

  • Verwendung von DNSSEC-validierenden Resolvern
  • DNS-Abfragen von mehreren Netzwerkstandorten aus
  • Anwendung von DNS-Schutzmaßnahmen (z. B. DNS0x20)

10.3 Denial-of-Service-Überlegungen​

CAs SOLLTEN implementieren:

  • Ratenbegrenzung
  • Ressourcenkontingente
  • Zeitüberschreitungseinstellungen für Validierungsabfragen

10.4 Server-Side Request Forgery (SSRF)​

HTTP-01-Herausforderungen können für SSRF-Angriffe missbraucht werden. CAs SOLLTEN:

  • Private IP-Adressen ablehnen
  • Weiterleitungen einschränken
  • Angemessene Zeitüberschreitungen festlegen

10.5 CA-Richtlinienüberlegungen​

CAs SOLLTEN Richtlinien zu folgenden Aspekten festlegen:

  • Auswahl der Validierungsmethoden
  • Zertifikatsgültigkeitsdauer
  • Widerrufsbedingungen

11. Operational Considerations (Betriebliche Überlegungen)​

11.1 Schlüsselauswahl​

Empfohlene Schlüsseltypen:

  • ECDSA P-256 oder P-384
  • RSA 2048 Bit oder höher

11.2 DNS-Sicherheit​

Bei Verwendung von DNS-01-Herausforderungen:

  • DNS-Infrastruktur absichern
  • Einsatz von DNSSEC in Betracht ziehen
  • DNS-Verwaltungsschnittstellen schützen

11.3 Token-Entropie​

Herausforderungstoken MÜSSEN ausreichend Entropie aufweisen:

  • Mindestens 128 Bit Entropie
  • Kryptografisch sicheren Zufallszahlengenerator verwenden

11.4 Fehlerhafte Zertifikatsketten​

Clients SOLLTEN:

  • Die Integrität heruntergeladener Zertifikatsketten überprüfen
  • Die Gültigkeitsdauer von Zertifikaten prüfen
  • Den Vertrauenspfad der Zertifikatskette validieren

12. References (Referenzen)​

12.1 Normative Referenzen (Auswahl)​

  • RFC2119: Schlüsselwortdefinitionen (MUST, SHOULD, MAY usw.)
  • RFC5280: X.509-Zertifikate und CRL-Profil
  • RFC7515: JSON Web Signature (JWS)
  • RFC7518: JSON Web Algorithms (JWA)
  • RFC8259: JSON-Datenformat
  • RFC2818: HTTPS
  • RFC3339: Datums- und Zeitformat
  • RFC7807: Problemdetails für HTTP-APIs

12.2 Informative Referenzen (Auswahl)​

  • RFC3552: Leitfaden für Sicherheitsüberlegungen in Internetprotokollen
  • RFC6844: DNS Certification Authority Authorization (CAA) Resource Record
  • RFC7525: Empfehlungen für die sichere Verwendung von TLS und DTLS

Anhang​

Acknowledgements (Danksagungen)​

Die Entwicklung von RFC 8555 wurde durch Beiträge zahlreicher Mitglieder der IETF-Community ermöglicht.

Authors' Addresses (Autorenanschriften)​

Hauptautoren:

  • Richard Barnes (Cisco)
  • Jacob Hoffman-Andrews (EFF)
  • Daniel McCarney (Let's Encrypt)
  • James Kasten (University of Michigan)

Verwandte Ressourcen​