TLS-Laufzeit mit Re-Issue-Zyklus maximieren

Dauer

ca. 15 Minuten

Niveau

Fortgeschritten

Endpunkte

Wenn dein Produkt fachlich mit einer Vertragslaufzeit von einem Jahr arbeitet, die CA aber nur kürzere Zertifikatslaufzeiten ausstellt, kannst du den Ablauf mit dem aktuellen regfish API jetzt deutlich sauberer automatisieren.

Wichtig ist die neue Trennung der Modelle: Folge-Ausstellungen innerhalb derselben Bestellung laufen per POST /tls/certificate/{certificate_id}/reissue auf derselben Zertifikats-id. Der Übergang in die nächste Vertragsperiode läuft dagegen als neue Bestellung über POST /tls/certificate mit renewal_of_certificate_id.

Das API liefert die providerseitige Vertragsgrenze jetzt über contract_valid_from und contract_valid_until mit. Falls dein eigenes Commerce- oder Billing-Modell darüber hinausgeht, kannst du den Ablauf zusätzlich mit eigenen Fachdaten anreichern.

Voraussetzungen

ein API-Key mit Zugriff auf TLS- und DNS-Endpunkte
die aktuelle Zertifikatsantwort inklusive contract_valid_until
optional ein intern gespeichertes kaufmännisches Vertragsende, falls es von der providerseitigen Vertragsgrenze abweicht
eine aktive Zertifikats-id, die aktuell produktiv genutzt wird
ein Job oder Scheduler, der täglich oder mehrfach täglich prüfen kann
ein frischer CSR für jede Folge-Ausstellung
eine Zone, die über Regfish DNS verwaltet wird

Schritt 1: Initial mit maximaler CA-Validity bestellen

Lege die erste Ausstellung direkt mit der maximalen öffentlich dokumentierten validity_days an. Im aktuellen OpenAPI-Stand sind das 199 Tage.

bash

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",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "validity_days": 199
}
'

Speichere neben der API-Antwort direkt deinen internen Steuerdatensatz. Die providerseitige Vertragsgrenze kommt jetzt aus dem API, zusätzlicher kaufmännischer Kontext bei Bedarf weiter aus deinem eigenen System.

json

{
  "contract_valid_from": "2026-03-16T00:00:00Z",
  "contract_valid_until": "2027-03-16T23:59:59Z",
  "active_certificate_id": "7K9QW3M2ZT8HJ",
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "dcv_method": "dns-cname-token"
}

Schritt 2: Erste Ausstellung abschließen und Laufzeit merken

Nimm die von validation.dns_records gelieferten Records und lege sie in DNS an. Danach pollst du die Bestellung, bis valid_until und certificate_pem_available gesetzt sind.

bash

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
}
'

bash

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

Aus der fertigen Antwort speicherst du mindestens:

contract_valid_from
contract_valid_until
valid_from
valid_until
status
certificate_pem_available

Schritt 3: Re-Issue-Fenster berechnen

Der effiziente Ablauf minimiert Überlappung und wartet deshalb bis kurz vor das aktuelle Zertifikatsende. Gleichzeitig darf ein Re-Issue nicht mehr angestoßen werden, wenn die verbleibende providerseitige Vertragslaufzeit praktisch schon aufgebraucht ist.

Ein einfaches Entscheidungsmodell sieht so aus:

text

reissue_lead_days = 7
safety_days = 2

days_until_expiry = floor((valid_until - now) / 86400)
days_until_contract_end = floor((contract_valid_until - now) / 86400)

if days_until_contract_end <= reissue_lead_days + safety_days:
  action = "renew-next-term"
elif days_until_expiry > reissue_lead_days:
  action = "wait"
else:
  action = "reissue-now"

Wichtig dabei:

re-issue erst kurz vor valid_until, damit keine unnötige Laufzeit verloren geht
wenn die Restvertragslaufzeit praktisch verbraucht ist, starte nicht noch ein Re-Issue, sondern die nächste Verlängerung als neue Bestellung
die Hauptoptimierung passiert weiterhin über den richtigen Auslösezeitpunkt; validity_days im Re-Issue nutzt du nur dann, wenn du für geeignete Multi-Year-Bestellungen bewusst eine kürzere Ersatzlaufzeit anfordern willst
nutze contract_valid_until aus dem API als Vertragsgrenze und ergänze nur dann eine eigene kaufmännische Grenze, wenn dein Geschäftsmodell das zusätzlich verlangt

Schritt 4: Re-Issue auf derselben Bestellung auslösen

Wenn das Entscheidungsmodell reissue-now liefert, löst du das Re-Issue direkt auf der vorhandenen Zertifikats-id aus. Genau hier ist der neue Endpoint deutlich passender als die frühere Modellierung über eine neue Zertifikatsbestellung.

bash

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/reissue' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "comments": "Scheduled reissue near certificate expiry",
  "validity_days": 90
}
'

Verwende für dieses Re-Issue vorzugsweise einen neuen Schlüssel und damit einen neuen CSR. validity_days sendest du nur dann mit, wenn du bewusst ein kürzeres Ersatzzertifikat anfordern willst und die zugrunde liegende Multi-Year-Bestellung das unterstützt.

Schritt 5: DCV-Token effizient aktualisieren

Verlasse dich nicht darauf, dass der alte DCV-Token weiterhin gültig ist. Lies den neuen Record aus response.reissue.validation.dns_records und aktualisiere den bestehenden _dnsauth-Record bevorzugt per PATCH /dns/rr.

bash

curl --request PATCH \
  --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": "fedcba9876543210.dcv.digicert.com.",
  "ttl": 300
}
'

Falls der Record noch nicht existiert, fällt der Workflow für diesen Schritt auf POST /dns/rr zurück.

Schritt 6: Neues Zertifikat übernehmen und Steuerzustand fortschreiben

Sobald das Re-Issue ausgestellt ist, lädst du das neue Zertifikat über dieselbe Zertifikats-id herunter und schreibst deinen internen Steuerzustand fort.

bash

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

bash

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

Danach speicherst du mindestens:

active_certificate_id = 7K9QW3M2ZT8HJ
neues valid_until
reissue.requested_at oder einen eigenen Zeitstempel der letzten Folge-Ausstellung

Bei einem normalen Re-Issue musst du das alte Zertifikat in der Regel nicht widerrufen. Es kann nach erfolgreichem Deployment regulär auslaufen.

Schritt 7: Nächste Vertragsperiode als explizite Verlängerung starten

Wenn das Entscheidungsmodell renew-next-term liefert, legst du keine weitere Folge-Ausstellung auf derselben Bestellung an. Stattdessen erzeugst du eine neue Bestellung und markierst sie explizit als Verlängerung des bisherigen Zertifikats.

bash

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",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...NEXT...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "renewal_of_certificate_id": "7K9QW3M2ZT8HJ",
  "validity_days": 199
}
'

Diese Anfrage erzeugt eine neue Bestellung mit neuer Zertifikats-id. Genau deshalb ist sie kein Re-Issue, sondern der Start des nächsten Vertrags- oder Abrechnungszyklus. Für den weiteren Ablauf behandelst du die Antwort wie jede andere neue Bestellung: neuen DCV-Record übernehmen, neuen Auftrag pollen, neues Zertifikat über die neue Zertifikats-id herunterladen und intern die Zuordnung renewed_from_certificate_id -> new_certificate_id speichern.

Wichtig bei Verlängerungen: validity_days bleibt die gekaufte Basislaufzeit. Sobald die Bestellung ausgestellt ist, sind valid_until und, falls vorhanden, renewal_bonus_days die maßgeblichen Felder für die effektiv gutgeschriebene Laufzeit.

Praxishinweise für produktive Abläufe

behandle Re-Issue-Jobs idempotent, zum Beispiel pro Vertrag und Zielgeneration
generiere den nächsten CSR vor dem Re-Issue-Fenster, damit die Folge-Ausstellung nicht auf Schlüsselerzeugung wartet
halte den DNS-TTL kurz, damit geänderte DCV-Token schnell greifen
plane einen kleinen Puffer zwischen Bestellung und erwartetem Deployment ein
verwende für den Wechsel in die nächste Vertragsperiode explizit renewal_of_certificate_id, statt blind eine komplett unverbundene Neubestellung zu erzeugen

Ergebnis

Mit dem aktuellen regfish API lässt sich dieser Lifecycle jetzt deutlich sauberer automatisieren: Die erste Ausstellung läuft über create-certificate, spätere Folge-Ausstellungen innerhalb derselben Bestellung über reissue-certificate, und die nächste Vertragsperiode wieder über create-certificate mit renewal_of_certificate_id als explizite Verlängerung. Die providerseitige Vertragsgrenze ist jetzt direkt im API sichtbar; zusätzliche kaufmännische Logik kannst du bei Bedarf weiter intern ergänzen.