Zum Hauptinhalt springen

7. Certificate Management (Zertifikatsverwaltung) - Part 2

(Fortsetzung von Kapitel 7 Part 1)

7.1.4. Authorization Objects (Autorisierungsobjekte)​

Ein ACME-Autorisierungsobjekt stellt die Autorisierung des Servers dar, dass ein Konto für einen Identifikator handeln darf. Neben dem Identifikator enthält eine Autorisierung mehrere Metadatenfelder, wie z. B. den Status der Autorisierung (z. B. „pending", „valid" oder „revoked") und welche Herausforderungen zur Validierung des Besitzes des Identifikators verwendet werden.

Eine ACME-Autorisierungsressource hat die folgende Struktur:

identifier (erforderlich, Objekt): Der Identifikator, für den das Konto autorisiert ist zu handeln.

  • type (erforderlich, Zeichenkette): Der Typ des Identifikators (siehe unten und Abschnitt 9.7.7).

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

status (erforderlich, Zeichenkette): Der Status dieser Autorisierung. Mögliche Werte sind „pending", „valid", „invalid", „deactivated", „expired" und „revoked". Siehe Abschnitt 7.1.6.

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

challenges (erforderlich, Objektarray): Für ausstehende Autorisierungen die Herausforderungen, die der Client abschließen kann, um den Besitz des Identifikators nachzuweisen. Für gültige Autorisierungen die validierten Herausforderungen. Für ungültige Autorisierungen die versuchten, aber fehlgeschlagenen Herausforderungen. Jeder Array-Eintrag ist ein Objekt, dessen Parameter für die Validierung der Herausforderung erforderlich sind. Der Client SOLLTE (SHOULD) versuchen, eine der Herausforderungen abzuschließen, und der Server SOLLTE (SHOULD) jede einzelne Herausforderung als ausreichend betrachten, um die Autorisierung gültig zu machen.

wildcard (optional, Boolean): Für Autorisierungen, die als Ergebnis einer newOrder-Anforderung erstellt wurden, die einen DNS-Identifikator mit einem Wildcard-Domainnamen als Wert enthält, MUSS (MUST) dieses Feld vorhanden und true sein. Für andere Autorisierungen DARF (MUST NOT) es nicht vorhanden sein. Wildcard-Domainnamen werden in Abschnitt 7.1.3 beschrieben.

Der einzige in dieser Spezifikation definierte Identifikatortyp ist der vollqualifizierte Domainname (Typ: „dns"). Domainnamen MÜSSEN (MUST) in der Form kodiert werden, in der sie im Zertifikat erscheinen. Das heißt, sie MÜSSEN (MUST) gemäß den Regeln in Abschnitt 7 von [RFC5280] kodiert werden. Der Server MUSS (MUST) überprüfen, ob Identifikatorwerte, die mit dem in [RFC5890] definierten ASCII-kompatiblen Kodierungspräfix „xn--" beginnen, korrekt kodiert sind. Wildcard-Domainnamen (bei denen das erste Label „*" ist) DÜRFEN NICHT (MUST NOT) in Autorisierungsobjekten enthalten sein. Wenn ein Autorisierungsobjekt die Autorisierung für die Basisdomain eines newOrder-DNS-Identifikators überträgt, der einen Wildcard-Domainnamen enthält, MUSS (MUST) das optionale Autorisierungsfeld „wildcard" vorhanden sein und den Wert true haben.

Abschnitt 8 beschreibt eine Reihe von Herausforderungen für die Domainvalidierung.

{
  "status": "valid",
  "expires": "2015-03-01T14:09:07.99Z",

  "identifier": {
    "type": "dns",
    "value": "www.example.org"
  },

  "challenges": [
    {
      "url": "https://example.com/acme/chall/prV_B7yEyA4",
      "type": "http-01",
      "status": "valid",
      "token": "DGyRejmCefe7v4NfDGDKfA",
      "validated": "2014-12-01T12:05:58.16Z"
    }
  ],

  "wildcard": false
}

7.1.5. Challenge Objects (Herausforderungsobjekte)​

Ein ACME-Herausforderungsobjekt stellt einen vom Server bereitgestellten Vorschlag dar, den Besitz eines Identifikators durch den Client auf eine bestimmte Weise zu validieren. Im Gegensatz zu den anderen oben aufgeführten Objekten haben Herausforderungsobjekte keine einheitliche Standardstruktur. Der Inhalt eines Herausforderungsobjekts hängt von der verwendeten Validierungsmethode ab. Die allgemeine Struktur von Herausforderungsobjekten und eine Reihe von anfänglichen Validierungsmethoden werden in Abschnitt 8 beschrieben.

7.1.6. Status Changes (Statusänderungen)​

Jeder ACME-Objekttyp durchläuft während seines Lebenszyklus eine einfache Zustandsmaschine. Das „status"-Feld eines Objekts gibt an, in welchem Zustand sich das Objekt aktuell befindet.

Herausforderungsobjekte werden im Zustand „pending" erstellt. Sie wechseln in den Zustand „processing", wenn der Client auf die Herausforderung antwortet (siehe Abschnitt 7.5.1) und der Server beginnt, zu überprüfen, ob der Client die Herausforderung abgeschlossen hat. Beachten Sie, dass der Server im Zustand „processing" möglicherweise mehrmals versucht, die Herausforderung zu validieren (siehe Abschnitt 8.2). Ebenso führt eine Client-Anforderung zum Wiederholen nicht zu einer Statusänderung. Wenn die Validierung erfolgreich ist, wechselt die Herausforderung in den Zustand „valid"; wenn ein Fehler auftritt, wechselt sie in den Zustand „invalid".

        pending
           |
           | Receive
           | response
           V
       processing <-+
           |   |    | Server retry or
           |   |    | client retry request
           |   +----+
           |
           |
Successful  |   Failed
validation  |   validation
 +---------+---------+
 |                   |
 V                   V
valid              invalid

          State Transitions for Challenge Objects

Autorisierungsobjekte werden im Zustand „pending" erstellt. Wenn eine der in der Autorisierung aufgeführten Herausforderungen in den Zustand „valid" wechselt, ändert sich auch die Autorisierung in den Zustand „valid". Wenn der Client versucht, eine Herausforderung abzuschließen, aber scheitert, oder wenn ein Fehler auftritt, während die Autorisierung noch aussteht, wechselt die Autorisierung in den Zustand „invalid". Sobald eine Autorisierung im Zustand „valid" ist, kann sie ablaufen („expired"), vom Client deaktiviert werden („deactivated", siehe Abschnitt 7.5.2) oder vom Server widerrufen werden („revoked").

                  pending --------------------+
                     |                        |
   Challenge failure |                        |
          or         |                        |
         Error       |  Challenge valid       |
           +---------+---------+              |
           |                   |              |
           V                   V              |
        invalid              valid            |
                               |              |
                               |              |
                               |              |
                +--------------+--------------+
                |              |              |
                |              |              |
         Server |       Client |   Time after |
         revoke |   deactivate |    "expires" |
                V              V              V
             revoked      deactivated      expired

            State Transitions for Authorization Objects

Bestellungsobjekte werden im Zustand „pending" erstellt. Sobald alle im Bestellungsobjekt aufgeführten Autorisierungen im Zustand „valid" sind, wechselt die Bestellung in den Zustand „ready". Nachdem der Client eine Anforderung an die „finalize"-URL der Bestellung gesendet hat und die CA mit der Zertifikatsausstellung beginnt, wechselt die Bestellung in den Zustand „processing". Sobald das Zertifikat ausgestellt ist, wechselt die Bestellung in den Zustand „valid". Wenn in einer dieser Phasen ein Fehler auftritt, wechselt die Bestellung in den Zustand „invalid". Die Bestellung wechselt auch in den Zustand „invalid", wenn sie abläuft oder wenn eine ihrer Autorisierungen in einen anderen Endzustand als „valid" wechselt („expired", „revoked" oder „deactivated").

pending --------------+
   |                  |
   | All authz        |
   | "valid"          |
   V                  |
 ready ---------------+
   |                  |
   | Receive          |
   | finalize         |
   | request          |
   V                  |
processing ------------+
   |                  |
   | Certificate      | Error or
   | issued           | Authorization failure
   V                  V
 valid             invalid

            State Transitions for Order Objects

Kontoobjekte werden im Zustand „valid" erstellt, da nach einer erfolgreichen newAccount-Anforderung keine weiteren Maßnahmen zur Kontoerstellung erforderlich sind. Wenn ein Konto vom Client deaktiviert oder vom Server widerrufen wird, wechselt es in den entsprechenden Zustand.

                 valid
                   |
                   |
       +-----------+-----------+
Client |                Server |
deactiv.|                revoke |
       V                       V
  deactivated               revoked

           State Transitions for Account Objects

Beachten Sie, dass je nach Serververhalten einige dieser Zustände möglicherweise nie im „status"-Feld erscheinen. Beispielsweise zeigt ein Server, der synchron ausstellt, niemals eine Bestellung im Zustand „processing". Ein Server, der abgelaufene Autorisierungen sofort löscht, zeigt niemals eine Autorisierung im Zustand „expired".

7.2. Getting a Nonce (Abrufen einer Nonce)​

Bevor ein ACME-Client eine POST-Anforderung an den Server sendet, benötigt er eine frische Anti-Replay-Nonce, die in den „nonce"-Header des JWS eingefügt werden soll. In den meisten Fällen erhält der Client eine Nonce aus einer vorherigen Anforderung. Manchmal muss ein Client jedoch eine neue Nonce abrufen, z. B. bei der ersten Anforderung an den Server oder wenn eine vorhandene Nonce nicht mehr gültig ist.

Um eine frische Nonce abzurufen, sendet der Client eine HEAD-Anforderung an die newNonce-Ressource auf dem Server. Die Antwort des Servers MUSS (MUST) ein Replay-Nonce-Headerfeld mit einer frischen Nonce enthalten und SOLLTE (SHOULD) den Statuscode 200 (OK) haben. Der Server MUSS (MUST) auch auf GET-Anforderungen an diese Ressource antworten und einen leeren Körper zurückgeben (während er weiterhin den Replay-Nonce-Header bereitstellt), mit dem Statuscode 204 (No Content).

HEAD /acme/new-nonce HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA
Cache-Control: no-store
Link: `https://example.com/acme/directory`;rel="index"

Das Proxy-Caching von Antworten der newNonce-Ressource kann dazu führen, dass Clients wiederholt dieselbe Nonce erhalten, was zu „badNonce"-Fehlern führt. Der Server MUSS (MUST) ein Cache-Control-Headerfeld mit der „no-store"-Direktive in Antworten auf die newNonce-Ressource aufnehmen, um das Caching dieser Ressource zu verhindern.

7.3. Account Management (Kontoverwaltung)​

In diesem Abschnitt beschreiben wir, wie ACME-Clients Konten auf einem ACME-Server erstellen und nach der Erstellung einige Änderungen an Konten vornehmen.

Ein Client erstellt ein neues Konto, indem er eine POST-Anforderung an die newAccount-URL des Servers sendet. Der Körper der Anforderung ist ein Stub-Kontoobjekt, das eine Teilmenge der folgenden Felder enthält:

contact (optional, Zeichenkettenarray): Gleiche Bedeutung wie das entsprechende Serverfeld, wie in Abschnitt 7.1.2 definiert.

termsOfServiceAgreed (optional, Boolean): Gleiche Bedeutung wie das entsprechende Serverfeld, wie in Abschnitt 7.1.2 definiert.

onlyReturnExisting (optional, Boolean): Wenn dieses Feld vorhanden ist und den Wert „true" hat, DARF (MUST NOT) der Server kein neues Konto erstellen, wenn noch keines existiert. Dies ermöglicht es Clients, eine Konto-URL anhand eines Kontoschlüssels nachzuschlagen (siehe Abschnitt 7.3.1).

externalAccountBinding (optional, Objekt): Gleiche Bedeutung wie das entsprechende Serverfeld, wie in Abschnitt 7.1.2 definiert.

POST /acme/new-account HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/new-account"
  }),
  "payload": base64url({
    "termsOfServiceAgreed": true,
    "contact": [
      "mailto:[email protected]",
      "mailto:[email protected]"
    ]
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

Der Server MUSS (MUST) alle Werte ignorieren, die im „orders"-Feld des vom Client gesendeten Kontoobjekts angegeben sind, sowie alle anderen Felder, die er nicht erkennt. Wenn zukünftig neue Felder spezifiziert werden, MÜSSEN (MUST) die Spezifikationen dieser Felder beschreiben, ob Clients sie bereitstellen können. Der Server DARF NICHT (MUST NOT) das „onlyReturnExisting"-Feld oder nicht erkannte Felder im resultierenden Kontoobjekt widerspiegeln. Dies ermöglicht es Clients zu erkennen, wann der Server keine Erweiterungsfelder unterstützt.

Der Server SOLLTE (SHOULD) überprüfen, ob die Kontakt-URLs im „contact"-Feld gültig und vom Server unterstützt sind. Wenn der Server Kontakt-URLs validiert, MUSS (MUST) er das „mailto"-Schema unterstützen. Clients DÜRFEN NICHT (MUST NOT) „mailto"-URLs im „contact"-Feld angeben, die „hfields" [RFC6068] oder mehrere „addr-spec" in der „to"-Komponente enthalten. Wenn der Server auf eine „mailto"-Kontakt-URL stößt, die diesen Kriterien nicht entspricht, SOLLTE (SHOULD) er sie als ungültig ablehnen.

Wenn der Server eine Kontakt-URL aufgrund der Verwendung eines nicht unterstützten Schemas ablehnt, MUSS (MUST) er einen Fehler vom Typ „unsupportedContact" zurückgeben, der eine Fehlerbeschreibung und die Arten von Kontakt-URLs enthält, die der Server als akzeptabel betrachtet. Wenn der Server eine Kontakt-URL ablehnt, weil ein unterstütztes Schema verwendet wird, der Wert aber ungültig ist, MUSS (MUST) der Server einen Fehler vom Typ „invalidContact" zurückgeben.

Wenn der Server verlangen möchte, dass Clients den Nutzungsbedingungen für die Nutzung des ACME-Dienstes zustimmen, MUSS (MUST) er eine URL angeben, unter der solche Bedingungen abgerufen werden können, im „termsOfService"-Unterfeld des „meta"-Felds des Verzeichnisobjekts, und der Server MUSS (MUST) newAccount-Anforderungen ablehnen, bei denen das „termsOfServiceAgreed"-Feld nicht auf „true" gesetzt ist. Clients SOLLTEN NICHT (SHOULD NOT) standardmäßig automatisch den Bedingungen zustimmen. Stattdessen SOLLTEN (SHOULD) sie eine Benutzerinteraktion erfordern, um den Bedingungen zuzustimmen.

Der Server erstellt das Konto und speichert den öffentlichen Schlüssel, der zur Validierung des JWS verwendet wird (d. h. das „jwk"-Element des JWS-Headers), um zukünftige Anforderungen des Kontos zu authentifizieren. Der Server gibt dieses Kontoobjekt in einer 201 (Created)-Antwort zurück, wobei die Konto-URL im Location-Headerfeld angegeben ist. Die Konto-URL wird als „kid"-Wert im JWS verwendet, um nachfolgende Anforderungen für dieses Konto zu authentifizieren (siehe Abschnitt 6.2). Die Konto-URL wird auch für Anforderungen für Verwaltungsoperationen an diesem Konto verwendet, wie unten beschrieben.

HTTP/1.1 201 Created
Content-Type: application/json
Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
Link: `https://example.com/acme/directory`;rel="index"
Location: https://example.com/acme/acct/evOfKhNU60wg

{
  "status": "valid",

  "contact": [
    "mailto:[email protected]",
    "mailto:[email protected]"
  ],

  "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders"
}

7.3.1. Finding an Account URL Given a Key (Suchen einer Konto-URL anhand eines Schlüssels)​

Wenn der Server eine newAccount-Anforderung erhält, die mit einem Schlüssel signiert ist, für den er bereits ein Konto mit dem bereitgestellten Kontoschlüssel registriert hat, MUSS (MUST) er eine Antwort mit dem Statuscode 200 (OK) zurückgeben und die URL dieses Kontos im Location-Headerfeld angeben. Der Körper dieser Antwort stellt das Kontoobjekt dar, das vor dieser Anforderung auf dem Server vorhanden war; alle Felder im Anforderungsobjekt MÜSSEN (MUST) ignoriert werden. Dies ermöglicht es Clients, die einen Kontoschlüssel, aber keine entsprechende Konto-URL haben, die Konto-URL wiederherzustellen.

Wenn ein Client die URL eines bestehenden Kontos nachschlagen möchte und kein Konto erstellen möchte, wenn keines existiert, SOLLTE (SHOULD) er dies tun, indem er eine POST-Anforderung an die newAccount-URL sendet, deren JWS-Nutzlast das „onlyReturnExisting"-Feld auf „true" gesetzt hat ({"onlyReturnExisting": true}). Wenn der Client eine solche Anforderung sendet und kein Konto existiert, MUSS (MUST) der Server den Statuscode 400 (Bad Request) und eine Fehlerantwort vom Typ „urn:ietf:params:acme:error:accountDoesNotExist" zurückgeben.

7.3.2. Account Update (Kontoaktualisierung)​

Wenn ein Client diese Informationen in Zukunft aktualisieren möchte, sendet er eine POST-Anforderung mit den aktualisierten Informationen an die Konto-URL. Der Server MUSS (MUST) alle Aktualisierungen des „orders"-Felds, des „termsOfServiceAgreed"-Felds (siehe Abschnitt 7.3.3), des „status"-Felds (außer wie in Abschnitt 7.3.6 erlaubt) oder anderer Felder, die er nicht erkennt, ignorieren. Wenn der Server die Aktualisierung akzeptiert, MUSS (MUST) er eine Antwort mit dem Statuscode 200 (OK) und dem resultierenden Kontoobjekt zurückgeben.

Um beispielsweise die Kontaktinformationen im obigen Konto zu aktualisieren, könnte der Client die folgende Anforderung senden:

POST /acme/acct/evOfKhNU60wg HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "ax5RnthDqp_Yf4_HZnFLmA",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
  "payload": base64url({
    "contact": [
      "mailto:[email protected]",
      "mailto:[email protected]"
    ]
  }),
  "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o"
}

7.3.3. Changes of Terms of Service (Änderungen der Nutzungsbedingungen)​

Wie oben beschrieben, kann ein Client seine Zustimmung zu den Nutzungsbedingungen der CA angeben, indem er das „termsOfServiceAgreed"-Feld in seinem Kontoobjekt auf „true" setzt.

Wenn der Server seine Nutzungsbedingungen seit der ursprünglichen Zustimmung des Clients geändert hat und der Server nicht bereit ist, Anforderungen ohne ausdrückliche Zustimmung zu den neuen Bedingungen zu verarbeiten, MUSS (MUST) er den Statuscode 403 (Forbidden) und eine Fehlerantwort vom Typ „urn:ietf:params:acme:error:userActionRequired" zurückgeben. Diese Antwort MUSS (MUST) ein Link-Headerfeld mit der Linkrelation „terms-of-service" und der URL der aktuellen Nutzungsbedingungen enthalten.

Das mit dem Fehler zurückgegebene Problemdokument MUSS (MUST) auch ein „instance"-Feld enthalten, das die URL angibt, zu der der Client einen menschlichen Benutzer weiterleiten SOLLTE, um Anweisungen zur Zustimmung zu den Bedingungen zu erhalten.

HTTP/1.1 403 Forbidden
Replay-Nonce: T81bdZroZ2ITWSondpTmAw
Link: `https://example.com/acme/directory`;rel="index"
Link: `https://example.com/acme/terms/2017-6-02`;rel="terms-of-service"
Content-Type: application/problem+json
Content-Language: en

{
  "type": "urn:ietf:params:acme:error:userActionRequired",
  "detail": "Terms of service have changed",
  "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8"
}

7.3.4. External Account Binding (Externe Kontobindung)​

Der Server KANN (MAY) verlangen, dass ein Wert für das „externalAccountBinding"-Feld in „newAccount"-Anforderungen vorhanden ist. Dies kann verwendet werden, um ein ACME-Konto mit einem bestehenden Konto in einem Nicht-ACME-System zu verknüpfen, z. B. einer CA-Kundendatenbank.

Um die ACME-Kontobindung zu ermöglichen, muss die CA, die den ACME-Server betreibt, dem ACME-Client über einen Mechanismus außerhalb von ACME einen MAC-Schlüssel und eine Schlüsselkennung bereitstellen. Die Schlüsselkennung MUSS (MUST) eine ASCII-Zeichenkette sein. Der MAC-Schlüssel SOLLTE (SHOULD) in base64url-kodierter Form bereitgestellt werden, um die Kompatibilität zwischen Nicht-ACME-Bereitstellungssystemen und ACME-Clients zu maximieren.

Der ACME-Client berechnet dann ein Bindungs-JWS, um anzuzeigen, dass der Inhaber des externen Kontos den ACME-Kontoschlüssel genehmigt. Die Nutzlast dieses JWS ist der ACME-Kontoschlüssel, der registriert wird, in JWK-Form. Der Protected Header des JWS MUSS (MUST) die folgenden Kriterien erfüllen:

  • Das „alg"-Feld MUSS (MUST) einen MAC-basierten Algorithmus angeben
  • Das „kid"-Feld MUSS (MUST) die von der CA bereitgestellte Schlüsselkennung enthalten
  • Das „nonce"-Feld DARF NICHT (MUST NOT) vorhanden sein
  • Das „url"-Feld MUSS (MUST) auf denselben Wert wie das äußere JWS gesetzt sein

Das „signature"-Feld des JWS enthält den MAC-Wert, der mit dem von der CA bereitgestellten MAC-Schlüssel berechnet wurde.

(Aufgrund des Umfangs werden die Abschnitte 7.3.5–7.6 in der nächsten Datei fortgesetzt)

Letztes Update am