TLS Automatisierung mit DNS-API

In diesem Ablauf bestellst du ein Zertifikat über die TLS API, liest die benötigten DCV-DNS-Einträge direkt aus der Antwort aus, legst diese per DNS API an und prüfst anschließend den Bestellstatus, bis das Zertifikat bereit zum Download ist.

Für die meisten Linux-Deployments ist heute regfish certbro der schnellere und praxisnähere Einstieg, weil Bestellung, DNS-DCV, Schlüsselrotation, Deployment und Verlängerung bereits in einer CLI gebündelt sind. Dieses manuelle Rezept ist vor allem dann sinnvoll, wenn du den Ablauf bewusst direkt auf API-Ebene in eigene Integrationen, Jobs oder andere Laufzeitumgebungen einbauen willst.

Voraussetzungen

• ein gültiger API-Key mit Zugriff auf TLS- und DNS-Endpunkte
• eine Zone, die bereits über Regfish DNS verwaltet wird
• ein vorbereiteter CSR für den gewünschten Common Name
• ein Prozess, der den Status der Bestellung in Intervallen erneut abfragt

Schritt 1: Zertifikat bestellen oder Verlängerung anstoßen

Die Anfrage an POST /tls/certificate liefert neben der Bestell-ID bereits die Informationen für die Domainvalidierung zurück. Für automatisiertes DCV ist vor allem validation.dns_records relevant.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token"
}
'

Wenn dieselbe Anfrage explizit als Verlängerung eines bestehenden Zertifikats laufen soll, ergänzt du renewal_of_certificate_id. Die API erzeugt dann eine neue Bestellung, verknüpft sie aber fachlich mit dem bisherigen Zertifikat unter Anrechnung der Restlaufzeit.

{
  "renewal_of_certificate_id": "7K9QW3M2ZT8HJ"
}

Bei Verlängerungsaufträgen gilt außerdem: validity_days bleibt die gekaufte Basislaufzeit. Sobald das Zertifikat tatsächlich ausgestellt ist, ist valid_until für die effektive Laufzeit maßgeblich, und renewal_bonus_days kann erscheinen, wenn der Provider Restlaufzeit des vorherigen Zertifikats gutgeschrieben hat.

Typischerweise enthält die Antwort einen Block wie diesen:

{
  "success": true,
  "response": {
    "id": "9M4TR8C6X2HP7",
    "status": "pending",
    "common_name": "www.example.com",
    "validation": {
      "method": "dns-cname-token",
      "dns_records": [
        {
          "name": "_dnsauth.example.com.",
          "type": "CNAME",
          "value": "0123456789abcdef.dcv.digicert.com."
        }
      ]
    }
  }
}

Schritt 2: DCV-Eintrag per DNS API anlegen

Nimm den zurückgegebenen Record aus validation.dns_records und schreibe ihn direkt in die passende Zone. Genau dieser Schritt macht den Ablauf automatisierbar, auch wenn Zertifikate künftig immer kürzere Laufzeiten haben.

curl --request POST \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "CNAME",
  "name": "_dnsauth.example.com",
  "data": "0123456789abcdef.dcv.digicert.com.",
  "ttl": 300
}
'

Schritt 3: Bestellstatus pollen

Nachdem der DNS-Eintrag veröffentlicht wurde, prüfst du den Zertifikatsstatus regelmäßig. Sobald die CA den Eintrag gesehen hat, wechselt der Status in einen auslieferbaren Zustand.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/9M4TR8C6X2HP7' \
  --header 'x-api-key: YOUR_API_KEY'

Achte dabei insbesondere auf:

• status
• order_state
• valid_until
• renewal_bonus_days, falls es sich um eine providerseitig verknüpfte Verlängerung handelt
• Hinweise, ob certificate_pem_available bereits true ist

Schritt 4: Zertifikat herunterladen

Sobald die Bestellung erfolgreich validiert und ausgestellt wurde, kannst du das Zertifikat direkt abrufen und in deine weiteren Deployment-Schritte übergeben.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/9M4TR8C6X2HP7/download/pem' \
  --header 'x-api-key: YOUR_API_KEY' \
  --output 'certificate-9M4TR8C6X2HP7.pem'

Praxishinweise für produktive Abläufe

• Lege DNS-DCV-Records mit kurzer TTL an, damit Korrekturen schneller greifen
• speichere die Zertifikats-ID unmittelbar nach der Bestellung für spätere Polling- und Download-Schritte
• trenne Bestellung, DNS-Update und Statusprüfung in eigene Jobs oder Queues
• logge alle von der CA geforderten DNS-Records, damit Fehlerbilder schnell nachvollziehbar bleiben

Ergebnis

Mit diesem Ablauf automatisierst du nicht nur die eigentliche Bestellung, sondern auch den DCV-Schritt, der bei kürzeren Laufzeiten künftig immer wichtiger wird. Dasselbe Muster funktioniert dabei sowohl für Erstbestellungen als auch für explizite Verlängerungen über renewal_of_certificate_id.