TLS-Zertifikat explizit verlängern

Dieses Rezept beschreibt den Fall, in dem ein Zertifikat nicht einfach auf derselben Bestellung neu ausgestellt werden soll, sondern als neue Bestellung in die nächste Vertrags- oder Abrechnungsperiode übergeht. Genau dafür dient renewal_of_certificate_id auf POST /tls/certificate.

Der Unterschied zum Re-Issue ist wesentlich: Re-Issue behält dieselbe Zertifikats-id und dieselbe Bestellung. Eine explizite Verlängerung erzeugt dagegen eine neue Bestellung mit neuer Zertifikats-id, verweist aber auf das bisherige Zertifikat, damit der Provider die Restlaufzeit anrechnen kann.

Voraussetzungen

ein API-Key mit Zugriff auf TLS- und DNS-Endpunkte
die Zertifikats-id des aktuell aktiven Zertifikats
ein neuer CSR für die Verlängerung
DNS-Zugriff für die Domain Control Validation
ein Deployment-Schritt, der auf das neu ausgestellte Zertifikat umschalten und seine neue Zertifikats-id nachhalten kann

Schritt 1: Bestehendes Zertifikat lesen und Verlängerungsquelle festhalten

Lies das aktuell aktive Zertifikat, damit du den Ausgangszustand dokumentierst und die richtige renewal_of_certificate_id verwendest.

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

Speichere daraus mindestens:

id
common_name
dns_names
contract_valid_until
valid_until
status

Schritt 2: Neue Bestellung mit expliziter Verlängerung anlegen

Lege die neue Bestellung über denselben Endpunkt wie eine Erstbestellung an, aber setze zusätzlich renewal_of_certificate_id.

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

Die Antwort enthält eine neue id. Diese neue Zertifikats-id ist der zentrale Steuerwert für alle weiteren Schritte der Verlängerung.

Wichtig dabei: validity_days bleibt die gekaufte Basislaufzeit. Nach der Ausstellung ist valid_until für die effektive Laufzeit maßgeblich, und renewal_bonus_days kann erscheinen, sobald der Provider eine gutgeschriebene Restlaufzeit bestätigt hat.

Schritt 3: DCV für die neue Bestellung umsetzen

Übernimm die in validation.dns_records gelieferte Validierung für die neue Bestellung. Auch bei einer Verlängerung solltest du nicht annehmen, dass alte DCV-Daten automatisch weiterverwendet werden.

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 4: Neue Bestellung bis zur Ausstellung pollen

Ab jetzt überwachst du nicht mehr das alte Zertifikat, sondern die neue Zertifikats-id.

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

Achte dabei vor allem auf:

status
order_state
contract_valid_until
valid_until
renewal_bonus_days
certificate_pem_available

Schritt 5: Neues Zertifikat über die neue Zertifikats-`id` herunterladen

Sobald die Verlängerung ausgestellt ist, lädst du das Zertifikat über die neue Bestellung herunter und rollst es aus.

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

Danach aktualisierst du intern mindestens:

previous_certificate_id = 7K9QW3M2ZT8HJ
active_certificate_id = 9M4TR8C6X2HP7
renewed_from_certificate_id = 7K9QW3M2ZT8HJ
contract_valid_until
renewal_bonus_days, falls vorhanden
neues valid_until

Praxishinweise für produktive Abläufe

nutze die explizite Verlängerung für den nächsten Vertrags- oder Abrechnungszyklus, nicht für einen Sicherheitsersatz auf derselben Bestellung
nutze Re-Issue, wenn dieselbe Bestellung und dieselbe Zertifikats-id bestehen bleiben sollen
speichere die Beziehung zwischen alter und neuer Zertifikats-id, damit Reporting und Deployment sauber bleiben
plane genug Vorlauf vor dem Ablaufdatum ein, statt die Verlängerung erst im letzten Moment zu starten
übernimm die von der Verlängerung gelieferten DCV-Daten explizit und verlasse dich nicht auf alte Tokens

Ergebnis

Mit diesem Ablauf erzeugst du eine neue Zertifikatsbestellung, die vom Provider explizit als Verlängerung unter Anrechnung der Restlaufzeit des bisherigen Zertifikats verstanden wird. Damit ist der nächste Vertragszyklus sauber dokumentiert und klar vom Re-Issue-Fall auf derselben Bestellung getrennt.