Förnya ett Sophos Firewall-certifikat via XML API och kontrollera tjänster

Kortare livslängder för offentligt betrodda TLS-certifikat ökar arbetsinsatsen vid manuell förnyelse. Certifikatet utfärdas därför på ett externt system, importeras från en skyddad automationsvärd, tilldelas den avsedda tjänsten och kontrolleras därefter på den verkliga lyssnaren. Ett lyckat utfärdande bekräftar ännu inte att importen lyckades. Ett befintligt certifikatobjekt bekräftar inte heller vilket certifikat som levereras av WebAdmin, Portal, WAF eller SMTP.

XML-fälten för add och update hämtas alltid från API help för den SFOS-build som används. Identifieringsfältet för ett befintligt objekt, hur referenser bevaras och beteendet efter fel fastställs i en testkörning. Artikeln visar därför medvetet ingen påstått universell uppdateringspayload.

Arbetsflödet i fyra faser

Förbered: Klargör CA-behörigheter, valideringar, automationsvärd, API-åtkomst och återställningsväg.
Testa: Använd ett umbärligt namn för att omvandla det lokala add-/update-exemplet till en versionsbunden multipart-begäran och godkänn den.
Förnya: Kontrollera certifikat och nyckel, ladda upp dem och tilldela certifikatet till de avsedda tjänsterna.
Godkänn: Kontrollera objektfilen och den verkliga lyssnaren, övervaka driften och ta bort det gamla certifikatet först senare.

Varför livslängderna kräver robust automation

Den högsta tillåtna livslängden för offentligt betrodda TLS-certifikat förkortas stegvis. Enligt Baseline Requirements från CA/Browser Forum gäller följande övre gränser för nyutfärdade certifikat:

före den 15 mars 2026: högst 398 dagar;
från den 15 mars 2026 till den 14 mars 2027: högst 200 dagar;
från den 15 mars 2027 till den 14 mars 2029: högst 100 dagar;
från och med den 15 mars 2029: högst 47 dagar.

Även den tillåtna återanvändningsperioden för slutförda domän- eller IP-valideringar förkortas i samma steg, från 398 till 200, 100 och slutligen 10 dagar. Certifikatet och den underliggande valideringen har alltså separata tidsfrister.

Enligt DigiCerts aktuella information om kortare livslängder utfärdar företaget sedan den 24 februari 2026 offentliga TLS-certifikat med en livslängd på högst 199 dagar. Driftsgränser på 99 respektive 46 dagar har endast aviserats till början av 2027 respektive början av 2029. De exakta övergångsdatumen kan fortfarande ändras. Automationen övervakar därför det faktiskt utfärdade notAfter i stället för att utgå från en fast livslängd på ett år.

Håll inbyggt Let’s Encrypt och extern CA åtskilda

Let’s Encrypt-funktionen som är inbyggd i SFOS är ett separat arbetsflöde som hanteras av brandväggen. Den är inte en generell ACME-klient för DigiCert och kan inte enkelt ställas om till en DigiCert ACME-URL. För det inbyggda arbetsflödet är Konfigurera Let’s Encrypt-certifikat på Sophos Firewall rätt väg.

Med en extern offentlig CA sker utfärdandet på ett system som är lämpat för ändamålet. Först därefter överförs det färdiga certifikatet till SFOS via XML API.

Kartlägg CA-neutrala förutsättningar

Innan konfigurationen påbörjas måste följande punkter klargöras hos den valda CA:n:

produktbehörighet och tillåtna certifikattyper;
beställning, prenumeration eller annan betalningsmetod;
skapande, giltighet och rotation av ACME- eller API-inloggningsuppgifter;
DCV-metod som stöds för varje beställt namn;
nödvändig organisationsvalidering för OV/EV;
tidsfrister för certifikat-, domän- och organisationsvalidering.

Benämningar och godkännandesteg skiljer sig mellan olika leverantörer. Följande kontouppgifter är därför ett konkret DigiCert-exempel, inte ett generellt CA-krav.

DigiCert-exempel: Förbered konto och ACME

I CertCentral måste automationsfunktionen vara aktiverad för det aktuella kontot. Därefter skiljer sig konfiguration och godkännande åt beroende på kontomodell:

För Enterprise-, Partner- och äldre Non-Subscription-konton kan endast en CertCentral-administratör skapa en ACME Directory URL. Administratören kan därefter överlämna de färdiga inloggningsuppgifterna till ett tjänstekonto med snäva behörigheter för den löpande driften.
För Enterprise- och andra Non-Subscription-konton måste automatiskt godkännande av certifikatbegäranden vara aktiverat. Utan det misslyckas ACME-begäranden som standard.
Subscription Accounts behöver inte denna inställning för automatiskt godkännande av begäranden. Tillgängliga produkter och prenumerationsstatus måste ändå stämma.

Därmed hålls de omfattande rättigheterna för att skapa inloggningsuppgifterna åtskilda från det senare automationskontot. Kontrollera före den första beställningen även produktbehörighet, betalningsmetod samt att ACME Directory URL och External Account Binding är kopplade till rätt konto och produkt. En tydligt utsedd ansvarig hanterar skapande, rotation och akut ersättning av inloggningsuppgifterna.

ACME-inloggningsuppgifter ska lagras i ett skyddat hemlighetsvalv. De får inte skrivas till ett repository, skalskript, ärende, wiki-exempel eller en Postman-export.

DigiCert-exempel: DCV för DV, OV och EV

För ett DV-certifikat utför DigiCert Domain Control Validation på nytt för varje ACME-beställning. En tidigare DCV förvalideras eller återanvänds inte. Automationsvärden måste kunna utföra den valda challenge-metoden vid varje förnyelse.

För OV- och EV-certifikat kräver obevakat ACME-utfärdande att organisationen har validerats i förväg. Dessutom måste domänstatusen vara giltig. DigiCert använder för närvarande en återanvändbar OV-/EV-domänvalidering på 199 dagar. Organisationsvalideringen för offentliga OV-certifikat kan för närvarande återanvändas i 397 dagar. Båda tidsfristerna övervakas separat från certifikatets utgångsdatum.

För ett wildcard-certifikat som *.example.com är DNS-01 den typiska valideringsmetoden. DNS API-åtkomsten bör endast få ändra den zon eller DNS-post som behövs.

Bygg en säker automationsvärd

Automationsvärden hanterar tillfälligt den privata nyckeln, CA-inloggningsuppgifter och ett SFOS-lösenord med skrivbehörighet. Den hör hemma i en skyddad hanteringsmiljö, inte på en vanlig administratörsdator eller i en godtycklig CI-körningsmiljö.

Minimikraven är:

härdat och uppdaterat operativsystem med en tydligt utsedd ansvarig;
fast käll-IP eller snävt avgränsat hanteringsnätverk;
utgående åtkomst endast till CA, DNS API och avsedda brandväggar;
separata inloggningsuppgifter för CA, DNS och varje brandvägg, eller för en tydligt avgränsad brandväggsgrupp;
hemlighetsvalv i stället för miljövariabler, diagnostikutdata, kommandoradsparametrar eller klartextfiler;
restriktiva filbehörigheter och en tillfällig arbetskatalog på krypterad lagring;
inga privata nycklar, lösenord eller fullständiga XML-begäranden i loggar;
spårbart beställnings-ID, målbrandvägg, certifikatnamn och resultat utan hemligt innehåll;
tidssynkronisering och larm vid upprepade fel eller för kort återstående giltighetstid.

Om den privata nyckeln överförs krypterad till SFOS bör importlösenordet av kompatibilitetsskäl vara högst 30 tecken långt. SFOS GUI-hjälpen anger denna övre gräns, medan API-hjälpen, beroende på build, beskriver 4 till 128 tecken. Begränsningen till 30 tecken är endast avsedd för kompatibilitet och är ingen allmän rekommendation om lösenordslängd. Det slumpmässiga lösenordet gäller endast för denna nyckel och överförs skyddat.

Härdning av källa, tjänstekonto, Device Access och API-behörigheter beskrivs i Säkra åtkomst till Sophos Firewall XML API. I SFOS 22 tillåts endast automationssystemets IP Host under Allowed IP hosts i Administration > API access. I äldre versioner finns API-konfigurationen på en annan menysökväg.

Testkörning före produktionsförnyelsen

Testkörningen använder ett umbärligt namn som test-fw.example.com, ett separat certifikatobjekt och en lyssnare där ett avbrott är acceptabelt. Den upprepas efter relevanta uppdateringar av SFOS eller automationen.

Fastställ beteendet för den build som används

Testerna fastställer beteendet för den konkreta builden. De ersätter inget tillverkarbesked. Följande ska kontrolleras och protokollföras:

exakt SFOS-build och den lokala API help som används;
exakta add- och update-fält samt identifieringsfältet för det befintliga objektet;
resultatet när samma begäran skickas igen och efter en avbruten uppladdning;
hantering av en certifikatfil med Leaf- och Intermediate-certifikat samt de CA-objekt som skapas;
den kedja som faktiskt levereras;
om WebAdmin-, Portal-, WAF- och SMTP-referenser bevaras eller går förlorade;
nödvändig aktivering av lyssnaren eller eventuell omstart av tjänsten;
i HA, överföring av certifikat, privat nyckel och tilldelning samt leverans efter failover.

En Fullchain-fil betraktas inte som stödd utan kontroll. Automationen får inte heller förutsätta idempotens, att referenser bevaras eller att en automatisk upprepning efter fel är säker.

Från lokalt add-/update-exempel till begäran

Så skapas en konkret, men inte felaktigt universaliserad, begäran för den installerade builden:

Gå i målbrandväggens lokala API help till System > Certificates > Certificate > Add Certificate / Update Certificate. Spara exempelkonfigurationen och parameterbeskrivningen för just denna build.
Använd den dokumenterade add-wrappern för det första fallet. För det andra fallet används det update och identifieringsfält som visas där. Kopiera varken operationsattribut eller objektidentifierare från en annan build.
Ersätt endast miljövärdena i exemplet: API-inloggning från hemlighetsvalvet, objektnamnet test-public-cert, åtgärden för certifikatuppladdning, certifikatformat, certifikatfilnamn, filnamn för privat nyckel och vid behov importlösenordet. Ta bort exempelgrenar som inte behövs, men lämna elementnamn och nästling oförändrade.
Skapa den resulterande XML-begäran lokalt som ett tillfälligt reqxml. De båda filnamnen i XML måste exakt motsvara de uppladdade filerna.
Välj POST till följande endpoint och multipart/form-data i Postman eller HTTP-biblioteket som används:
```
https://<Firewall-FQDN>:<Admin-Port>/webconsole/APIController
```
Skapa exakt tre multipart-delar: den fildel för certifikatet som anges i den lokala hjälpen, den fildel för den privata nyckeln som anges där och textfältet reqxml. Namnen på de två första delarna ska inte gissas. Deras aktuella namn och filnamnen hämtas från exemplet för målbuilden.
Kör först add och därefter update med ett nyutfärdat testcertifikat. Skicka dessutom en ogiltig begäran i testmiljön och läs tillbaka tillståndet innan ett nytt försök görs.
Begäran godkänns först när <Response> och <Status> rapporterar förväntat lyckat resultat, exakt det avsedda objektet har ändrats, inga oväntade CA-objekt har skapats, tjänstreferensen beter sig som protokollfört och den externa lyssnaren efter tilldelningen levererar det nya certifikatet med en giltig kedja. För HA ingår en kontrollerad failover.

Utifrån resultaten skapas, testas och godkänns begäran internt för just denna build. De tre delnamnen, XML-mallen, förväntade statusvärden och avbrottsvillkor versionshanteras tillsammans, utan att inloggningsuppgifter eller nycklar lagras.

Kontrollera certifikatet före uppladdningen

Följande exempel använder dessa ersättningsvärden:

tjänstens FQDN: vpn.example.com
SFOS-objektnamn: public-vpn-example-com
Leaf-certifikat: vpn.example.com.pem
privat nyckel: vpn.example.com.key
Intermediate-bundle: intermediates.pem
betrott Root-bundle: trust-roots.pem
extern HTTPS-port: 443

Läs först certifikatuppgifterna:

openssl x509 -in vpn.example.com.pem -noout -subject -issuer -serial -dates -ext subjectAltName -fingerprint -sha256

Utfärdare, giltighetstid, SAN och SHA-256-fingerprint måste stämma med beställningen. Kontrollera därefter att certifikatet och den privata nyckeln hör till samma nyckelpar utan att skriva ut nyckeln:

(
  tmpdir=$(mktemp -d)
  trap 'rm -rf -- "$tmpdir"' EXIT
  openssl x509 -in vpn.example.com.pem -pubkey -noout > "$tmpdir/cert-public-key.pem" &&
    openssl pkey -in vpn.example.com.key -pubout > "$tmpdir/key-public-key.pem" &&
    cmp "$tmpdir/cert-public-key.pem" "$tmpdir/key-public-key.pem"
)

cmp ger ingen utdata när de offentliga nycklarna är identiska. Vid en avvikelse avbryts processen. En krypterad privat nyckel frågar interaktivt efter lösenordet. I automationen hämtas det från hemlighetsvalvet och visas varken i processanropet eller i loggen.

Den avsedda kedjan kontrolleras mot det egna lagret med betrodda certifikat:

openssl verify -CAfile trust-roots.pem -untrusted intermediates.pem vpn.example.com.pem

trust-roots.pem innehåller de Root-CA:er som är betrodda i den egna miljön, medan intermediates.pem innehåller de Intermediate-CA:er som hör till utfärdandet. Kontrollen lyckas endast med utdata vpn.example.com.pem: OK. All annan utdata stoppar uppladdningen.

Överför certifikatet via XML API

Kontroller före uppladdningen

Jämför målbrandvägg, SFOS-build, objektnamn och tjänster med den godkända ändringen innan något skrivs. En aktuell Sophos Firewall-säkerhetskopia, den alternativa hanteringsåtkomsten och det tidigare certifikatobjektet måste vara tillgängliga. Kör först en ofarlig läsbegäran med samma värd och tjänstekonto. Filbehörigheter och lokala certifikatkontroller får inte visa några fel.

Skicka begäran och utvärdera svaret

Automationen skickar den multipart-begäran som godkändes under testkörningen. Certifikatet och den privata nyckeln överförs som filer. reqxml skapas vid körning och kasseras därefter. Klienten använder det FQDN som matchar brandväggscertifikatet, validerar dess CA och avbryter vid värdnamns- eller certifikatfel. curl -k eller en jämförbar avstängning av TLS-kontrollen är inte tillåten.

HTTP-status 200 eller Send successful bekräftar endast transporten. Automationen utvärderar i XML åtminstone det <Response>-element som hör till operationen och dess <Status> utifrån de värden som godkändes under testkörningen. Vid timeout, ofullständigt svar eller negativ status läser den först tillbaka objektets tillstånd eller stoppar för manuell utredning. Den upprepar inte skrivbegäran utan kontroll.

Kontrollera objektet och den nedladdade filen

Sök efter målobjektet under Certificates > Certificates. Kontrollera den information som faktiskt visas där i GUI:t, särskilt objektnamn, status för privat nyckel, Trusted, värdena Subject, Issuer och Purpose som visas när muspekaren hålls över objektet samt oväntade ytterligare certifikat- eller CA-objekt.

Serienummer, SAN, utgångsdatum och SHA-256-fingerprint förutsätts inte vara garanterade GUI-fält. Exportera målcertifikatet med nedladdningsåtgärden i SFOS och kontrollera den nedladdade filen:

openssl x509 -in downloaded-vpn.example.com.pem -noout -serial -dates -issuer -subject -ext subjectAltName -fingerprint -sha256

Dessa värden måste överensstämma med filen som kontrollerades före uppladdningen. Enbart grön Trusted-status bevisar varken korrekt tjänstetilldelning eller en fullständig kedja på lyssnaren. Format, kedja och GUI-import förklaras i Importera och tilldela certifikat på Sophos Firewall.

Tilldela certifikatet till tjänsten

Import och tilldelning är separata ändringar. Ett nytt objekt tilldelas uttryckligen till önskad tjänst. Vid en uppdatering används den metod som bekräftades under testkörningen, och efter körningen kontrolleras att referenserna faktiskt har bevarats.

WebAdmin och portaler

Under Administration > Admin and user settings > Admin console and end-user interaction gäller fältet Certificate gemensamt för WebAdmin Console, User Portal, VPN Portal, Captive Portal samt SPX Registration och Reply Portal. Certifikatet måste innehålla alla namn som faktiskt används som SAN. Kontrollera varje FQDN och port separat efter Apply. En befintlig administratörssession och en alternativ lokal hanteringsväg hålls öppna.

WAF

För en WAF-publicering väljs certifikatet i respektive regel under Rules and policies > Firewall i fältet HTTPS certificate. Domain, SNI, Listen Port och SAN måste stämma överens. När inställningen sparas startas Web Server Protection-reglerna om. Befintliga anslutningar kan brytas. Huruvida även byte av ett redan refererat certifikat utlöser en reload måste kontrolleras med den build som används under testkörningen.

SMTP TLS

I MTA-läge finns valet under Email > General settings > SMTP TLS configuration i fältet TLS certificate. Efter Apply kontrolleras STARTTLS och i förekommande fall implicit TLS separat. VPN och andra certifikatanvändningar kan ha egna tilldelningar. Ett identiskt namn innebär inte att de byts automatiskt.

Validera externt med SNI och rätt port

Kontrollera först kedja och värdnamn från en realistisk extern testvärd:

openssl s_client -connect vpn.example.com:443 -servername vpn.example.com -showcerts -verify_hostname vpn.example.com -verify_return_error </dev/null

De Intermediate-certifikat som behövs och Verification: OK förväntas. -servername skickar SNI. Ersätt värdnamn och port med den verkliga tjänstens värden.

Fingerprint, serienummer och andra Leaf-uppgifter kan läsas i ett andra körbart steg från samma lyssnarkonfiguration:

(
  set -o pipefail
  tmpdir=$(mktemp -d)
  trap 'rm -rf -- "$tmpdir"' EXIT
  openssl s_client -connect vpn.example.com:443 -servername vpn.example.com -showcerts \
    -verify_hostname vpn.example.com -verify_return_error </dev/null 2>"$tmpdir/s_client.log" |
    openssl x509 -out "$tmpdir/leaf.pem" &&
  openssl x509 -in "$tmpdir/leaf.pem" -noout -serial -fingerprint -sha256 -dates -issuer -subject -ext subjectAltName
)

Serienummer, SHA-256-fingerprint, giltighetstid, Issuer och SAN måste stämma överens med det godkända certifikatet. Kontrollera därefter själva applikationen, till exempel inloggning i portalen, WAF-healthcheck eller någon annan ofarlig End-to-End-funktion. En Load Balancer, CDN eller Reverse Proxy framför brandväggen kan terminera ett annat certifikat. Testpunkten måste därför motsvara den avsedda SFOS-funktionen.

SMTP med STARTTLS kräver ett separat anrop:

openssl s_client -starttls smtp -connect mail.example.com:25 -servername mail.example.com -verify_hostname mail.example.com -verify_return_error </dev/null

För implicit TLS på port 465 utelämnas -starttls smtp. Även här bekräftas kedja och värdnamn med Verification: OK. Leaf-uppgifterna kan läsas med det föregående extraktionsmönstret och anpassade anslutningsalternativ. Kontrollera därefter det faktiska e-postflödet.

Underhållsfönster, rollback och HA

Förbered underhållsfönstret

Den första produktionskörningen samt ändringar av begäran, SFOS-build, CA-produkt eller kedjans sammansättning utförs i ett underhållsfönster. Det tidigare objektet förblir tillgängligt. Berörda tilldelningar, alternativ hanteringsåtkomst samt ansvariga för återställningsväg och extern kontroll är kända.

Välj rollback-strategi

För ett nytt objekt är den tydligaste återställningsvägen att åter välja det gamla certifikatet i den berörda tjänsten och testa lyssnaren externt igen. Det gamla objektet tas därför inte bort under samma körning.

Vid en uppdatering av det befintliga objektet gäller endast den återställningsväg som bekräftades under testkörningen. Om en säker återinläsning av det tidigare innehållet inte har verifierats skapas i stället konservativt ett separat nytt objekt som därefter tilldelas uttryckligen.

Testa HA separat

I ett HA-kluster synkroniserar SFOS i grunden konfigurationen från Primary till Auxiliary. Certifikat, privat nyckel och tjänstetilldelning måste ändå kontrolleras på båda noderna eller via den gemensamma tjänsten. Därefter genomförs en kontrollerad failover med extern kontroll av lyssnaren. Först när testet har godkänts kan arbetsflödet tas i bruk för HA.

Övervakning och återkommande drift

Automationen måste rapportera fel och uteblivna förnyelser i tid. Följande övervakas kontinuerligt:

certifikatets återstående dagar på den externa lyssnaren och nästa CA-förnyelsefönster;
DCV-status och, för OV/EV, även organisationsvalidering;
senaste lyckade CA-beställning och SFOS-uppladdning;
förväntat och faktiskt levererat fingerprint;
API-fel, tvetydiga svar och avbrutna körningar;
oplanerade nya certifikat- eller CA-objekt;
inloggningsuppgifters utgång och rotation;
för HA, senaste godkända failover-test.

Larmet måste lämna tillräckligt med tid för CA-/DCV-processen, intern reaktion, underhållsfönster och återställningsväg. Efter ett lyckat byte behålls det gamla certifikatet under den definierade observationsperioden. Tillfälliga certifikat-, nyckel- och XML-filer raderas kontrollerat. Bevisdata som lagras permanent innehåller endast icke-hemliga metadata.

Felsökning efter symptom

CA:n utfärdar inget nytt certifikat

Kontrollera produktbehörighet, kontostatus, betalningsmetod och DCV hos respektive leverantör. I DigiCert-exemplet kontrolleras dessutom automationen och det kontomodellspecifika automatiska godkännandet av begäranden. För OV/EV måste organisation och domän vara giltiga. Kontrollera DNS-01-fel mot den auktoritativa offentliga DNS-tjänsten, inte bara mot den lokala resolvern.

XML API kan inte nås

Kontrollera käll-IP ur brandväggens perspektiv, Allowed IP hosts, Device Access, routing, Admin-Port och brandväggscertifikat. Testet måste utföras från den verkliga automationsvärden.

HTTP-begäran lyckas, men certifikatet uppdateras inte

Kontrollera <Response> och <Status>, inte bara HTTP-koden. Jämför därefter objektnamn, filformat, tillåten lösenordslängd och de buildspecifika fälten med den lokala API-hjälpen. Under Diagnostics > Troubleshooting logs kan apiparser.log, validation.log och validationError.log vara till hjälp. Ta bort alla inloggningsuppgifter innan loggarna delas. Vid oklart tillstånd ska certifikatobjektet först laddas ned och kontrolleras i stället för att skrivbegäran upprepas utan kontroll.

Objektet är nytt, men tjänsten visar det gamla certifikatet

Kontrollera tjänstetilldelning, WAF-regel, gemensamt certifikatval för WebAdmin och portaler eller SMTP-konfiguration. Testa därefter med SNI på rätt port och uteslut en TLS-endpoint framför brandväggen.

Certifikatet är inte `Trusted` eller kedjan är ofullständig

Jämför Leaf-certifikatets Issuer med installerade Intermediate-CA:er. Använd det importförfarande som bekräftades under testkörningen och kontrollera kedjan som lyssnaren skickar med -showcerts.

Efter uppdatering eller failover visas det gamla certifikatet igen

Fastställ vilken nod och lyssnare som svarar. Jämför sedan det nedladdade objektets fingerprint, tjänstreferens och HA-tillstånd. Vid en avvikelse genomförs den bekräftade återställningsvägen och automationen stoppas.

Checklista för godkännande

Produktionsförnyelsen godkänns endast när samtliga punkter är uppfyllda:

CA-behörighet, betalning, DCV och i förekommande fall organisationsvalidering är giltiga.
Build, lokal API-hjälp och multipart-begäran motsvarar den godkända testkörningen.
Den lokala kontrollen av certifikat, nyckel och kedja lyckades.
<Response> och <Status> rapporterar förväntat lyckat resultat. Exakt målobjektet ändrades.
Den nedladdade objektfilen har förväntat serienummer, SAN, giltighetstid och SHA-256-fingerprint. Privat nyckel och Trusted-status är korrekta, och inga oväntade objekt skapades.
Varje verkligt FQDN och port levererar det nya certifikatet, den förväntade kedjan och Verification: OK med SNI. Den tillhörande tjänsten fungerar.
För HA godkändes kontrollerad failover med extern kontroll.
Övervakningen registrerar det nya utgångsdatumet och ett lyckat resultat. Det gamla certifikatet behålls som återställningsväg till observationsperiodens slut.