Suche in diesem Bereich

Skip to end of metadata
Go to start of metadata

Die Domain-Robot JSON-API bietet für einige Zertifikats-Produkte die Möglichkeit der Echtzeitausstellung. Dabei ist das bestellte Zertifikat in der Antwort der API enthalten.

Inhaltsverzeichnis dieser Seite

Vorwort

Über die Echtzeitausstellung wird ein Zertifikat in wenigen Sekunden ausgestellt. Die Austellung erfolgt dabei über nur einen einzigen Request. Technisch bedingt gibt es für die Echtzeitausstellung einige Einschränkungen.

  • Die Bestellung erfolgt über die Route POST /certificate/_realtime
  • Es werden aktuell nur folgende Zertifikats-Produkte unterstützt : BASIC_SSL
  • Es werden nur folgende DCV-Methoden unterstützt : DNS, FILE

Anbindung

Für die Anbindung stehen diverse SDKs für verschiedene Programmiersprachen bereit. Alle SDKs stehen als Open Source Software über Github zur Verfügung.

Vorbereitung

Bestellung mit DNS als DCV-Methode

Bei einer Bestellung mit DNS als DCV-Methode muss in der zur Domain gehörenden Zone ein Authentifizierungs-Token hinterlegt werden. Der Token kann vorab über die Route POST /certificate/_prepareOrder generiert werden.

Request
POST /certificate/_prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "BASIC_SSL"
}

Der zu setzende TXT-Record befindet sich in der Antwort unter data[0]->authentication[0]->dns.

Response
{
    "stid": "20180926-test-1",
    "status": {
        "code": "S400110",
        "text": "CSR-Schlüssel wurde erfolgreich geprüft.",
        "type": "SUCCESS"
    },
    "data": [
        {
            "plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "name": "domain.de",
            "keySize": 2048,
            "countryCode": "DE",
            "state": "BY",
            "city": "Regensburg",
            "organization": "Company GmbH",
            "organizationUnit": "Entwicklung",
            "product": "BASIC_SSL",
            "authentication": [
                {
                    "method": "DNS",
                    "dns": "domain.de.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
                },
                {
                    "name": "domain.de",
                    "method": "FILE",
                    "fileName": "domain.de/.well-known/pki-validation/fileauth.txt",
                    "fileContent": "202001151029170zcdikd5mjoy4ppxam11axjt95hv81pepczlnmrmwnwx9wr2by"
                }
            ],
            "algorithm": "RSA",
            "signatureHashAlgorithm": "SHA256"
        }
    ]
}

Bestellung mit FILE als DCV-Methode

Wird FILE als DCV-Methode gewählt, so muss auf dem zur Domain gehörenden Server in einem vorgegebenen Pfad ein Authentifizierungs-Token hinterlegt werden. Der Token kann wie bei DNS vorab über die Route POST /certificate/_prepareOrder generiert werden.

Request
POST /certificate/_prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "BASIC_SSL"
}

Der zu hinterlegende Token und der Pfad befindet sich in der Antwort unter data[0]->authentication[1]→fileContent sowie data[0]->authentication[1]→fileName.

Response
{
    "stid": "20180926-test-1",
    "status": {
        "code": "S400110",
        "text": "CSR-Schlüssel wurde erfolgreich geprüft.",
        "type": "SUCCESS"
    },
    "data": [
        {
            "plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "name": "domain.de",
            "keySize": 2048,
            "countryCode": "DE",
            "state": "BY",
            "city": "Regensburg",
            "organization": "Company GmbH",
            "organizationUnit": "Entwicklung",
            "product": "BASIC_SSL",
            "authentication": [
                {
                    "method": "DNS",
                    "dns": "domain.de.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
                },
                {
                    "name": "domain.de",
                    "method": "FILE",
                    "fileName": "domain.de/.well-known/pki-validation/fileauth.txt",
                    "fileContent": "202001151029170zcdikd5mjoy4ppxam11axjt95hv81pepczlnmrmwnwx9wr2by"
                }
            ],
            "algorithm": "RSA",
            "signatureHashAlgorithm": "SHA256"
        }
    ]
}

Auftrag und Antwort

Auftrag

Der Auftrag ähnelt weitgehend einer normalen Zertifikats-Bestellung. Das Feld lifetime ist hierbei optional. Wird hier kein Wert angegeben, so wird von einer Laufzeit von 1 Jahr ausgegangen.

{
    "name": "domain.de",
    "lifetime": {
        "unit": "MONTH",
        "period": 12
    },
    "product": "BASIC_SSL",
    "csr": "... csr ...",
    "authentication": {
        "method": "FILE"
    }
}

Antwort

Bei erfolgreicher Bestellung enthält die Antwort das gewünschte Zertifikat, sowie alle Zertifikate der Zertifikats-Kette.

{
    "stid": "20200110-test-1",
    "status": {
        "code": "S4001012",
        "text": "S4001012",
        "type": "SUCCESS"
    },
    "object": {
        "type": "Certificate",
        "value": "domain.de"
    },
    "data": [
        {
            "created": "2020-01-10T00:00:00.000+0100",
            "updated": "2020-01-10T14:05:13.000+0100",
            "owner": {
                "context": 9,
                "user": "jondoe"
            },
            "updater": {
                "context": 9,
                "user": "jondoe"
            },
            "id": 1657639,
            "orderId": "13253275",
            "name": "domain.de",
            "lifetime": {
                "unit": "MONTH",
                "period": 12
            },
            "software": "APACHESSL",
            "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "server": "-----BEGIN CERTIFICATE---- ... -----END CERTIFICATE-----\r\n",
            "serialNumber": "D569DFB6CC87B88F45B1AF0A0054381",
            "product": "BASIC_SSL",
            "certificateType": "FQDN",
            "expire": "2020-02-09T13:00:00.000+0100",
            "certificationAuthority": [
                {
                    "caType": "INTERMEDIATE",
                    "caCertificate": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\r\n"
                },
                {
                    "caType": "ROOT",
                    "caCertificate": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\r\n"
                }
            ],
            "authentication": {
                "method": "FILE"
            }
        }
    ]
}

Beispiel-Implementierung

Anbei eine Implementierung in Dart, die das entsprechende SDK verwendet. Der Ablauf kann mit allen anderen SDKs einfach nachgebaut werden.

Mögliche Fehlermeldungen

Bei einem Aufruf der Route können folgende Fehlermeldungen auftreten:

EF010205 - Das Produkt unterstützt diesen Auftragstyp nicht.

Das ausgewählte Produkt unterstützt keine Echtzeitausstellung. Verwende eines der weiter oben beschriebenen gültigen Produkte.

EF01000 - Fehlender oder falscher Wert.

Diese  Fehlermeldung kann verschiedene Ursachen haben:

  • Die ausgewählte Authentifizierungsmethode wird nicht unterstützt. Wähle hier DNS oder FILE aus.
  • Die gewählte Laufzeit wird von dem gewählten Produkt nicht unterstützt. Wähle eine passende Laufzeit für das Produkt.
  • Der gewählte Name passt nicht mit dem CommonName in dem CSR überein. Verwende einen anderen Namen oder einen anderen CSR.
  • Die Key-Länge des CSR ist ungültig. Einige Produkte unterstützen z.B. keine 4096 Bytes.

EF400139 Domain-Validierung auf Seite der CA fehlgeschlagen.

Die Domain Controll Validation (DCV) ist auf Seiten der Certificate Authority (CA) fehlgeschlagen. Prüfe ob die entsprechenden Token in der Zone oder auf den Server hinterlegt sind.

EF400136 - Es konnte keine Verbindung zum CA hergestellt werden.

Es gab einen Fehler bei der Kommunikation mit der Certificate Authority (CA). Versuche es erneut oder wende dich an unseren Support.