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.
| Vorgang | Anforderung | Antwort |
|---|---|---|
| Verzeichnis abrufen | GET directory | 200 |
| Nonce abrufen | HEAD newNonce | 200 |
| Konto erstellen | POST newAccount | 201 -> account |
| Bestellung einreichen | POST newOrder | 201 -> order |
| Herausforderungen abrufen | POST-as-GET order's authorization urls | 200 |
| Auf Herausforderungen antworten | POST authorization challenge urls | 200 |
| Status abfragen | POST-as-GET order | 200 |
| Bestellung abschließen | POST order's finalize url | 200 |
| Status abfragen | POST-as-GET order | 200 |
| Zertifikat herunterladen | POST-as-GET order's certificate url | 200 |
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.
| Feld | URL in Wert |
|---|---|
| newNonce | Neue Nonce |
| newAccount | Neues Konto |
| newOrder | Neue Bestellung |
| newAuthz | Neue Autorisierung |
| revokeCert | Zertifikat widerrufen |
| keyChange | Schlü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.