Renew a Sophos Firewall certificate via the XML API and verify services

Shorter lifetimes for publicly trusted TLS certificates increase the effort required for manual renewals. The certificate is therefore issued on an external system, imported from a protected automation host, assigned to the intended service, and then verified on the actual listener. Successful issuance does not confirm a successful import; an existing certificate object does not confirm which certificate WebAdmin, a portal, WAF, or SMTP is presenting.

The XML fields for add and update must always come from API help for the deployed SFOS build. Determine the identifier field for an existing object, whether references are preserved, and the behavior after errors in a test run. This article therefore intentionally does not present a supposedly universal update payload.

The workflow in four phases

Prepare: Confirm CA permissions, validations, the automation host, API access, and the rollback path.
Test: Using a disposable name, turn the local add/update example into a version-specific multipart request and approve it.
Renew: Verify the certificate and key, upload them, and assign the certificate to the intended services.
Validate: Verify the object file and the actual listener, monitor operations, and remove the old certificate only later.

Why shorter lifetimes require robust automation

The maximum permitted lifetime of publicly trusted TLS certificates is being reduced in stages. According to the CA/Browser Forum Baseline Requirements, the following limits apply to newly issued certificates:

before March 15, 2026: no more than 398 days;
from March 15, 2026 through March 14, 2027: no more than 200 days;
from March 15, 2027 through March 14, 2029: no more than 100 days;
from March 15, 2029: no more than 47 days.

The permitted reuse period for completed domain or IP validations is also reduced in the same stages from 398 to 200, 100, and finally 10 days. The certificate and its underlying validation therefore have separate deadlines.

According to DigiCert’s current notice about shorter lifetimes, DigiCert has issued public TLS certificates with a maximum lifetime of 199 days since February 24, 2026. Operational limits of 99 and 46 days are not scheduled until early 2027 and early 2029 respectively; the exact transition dates may still change. The automation therefore monitors the issued certificate’s actual notAfter value instead of assuming a fixed one-year lifetime.

Separate integrated Let’s Encrypt from an external CA

The Let’s Encrypt feature integrated into SFOS is a separate workflow managed by the firewall. It is not a generic ACME client for DigiCert and cannot simply be pointed at a DigiCert ACME URL. For the built-in workflow, see Set up Let’s Encrypt certificates on Sophos Firewall.

When using an external public CA, issuance takes place on a suitable external system. Only the completed certificate is transferred to SFOS through the XML API.

Map CA-neutral prerequisites

Before setup, clarify the following points with the selected CA:

product entitlement and permitted certificate types;
order, subscription, or another payment method;
creation, validity, and rotation of ACME or API credentials;
supported DCV method for every ordered name;
required organization validation for OV/EV;
certificate, domain validation, and organization validation periods.

The terminology and approval steps differ between providers. The following account details are therefore a specific DigiCert example, not a general CA requirement.

DigiCert example: Prepare the account and ACME

In CertCentral, automation must be enabled for the relevant account. Setup and approval then differ by account model:

For Enterprise, Partner, and older non-subscription accounts, only a CertCentral administrator can create the ACME Directory URL. The administrator can then hand the generated credentials to a tightly restricted service account for ongoing operations.
For Enterprise and other non-subscription accounts, automatic approval of certificate requests must be enabled; without it, ACME requests fail by default.
Subscription accounts do not require this setting for automatic request approval. The available products and subscription status must nevertheless be appropriate.

This keeps the broad permissions required to create credentials separate from the automation account used later. Before the first order, also verify the product entitlement, payment method, and assignment of the ACME Directory URL and External Account Binding to the correct account and product. One designated owner manages credential creation, rotation, and emergency replacement.

ACME credentials belong in a protected secret store. Do not put them in a repository, shell script, ticket, wiki example, or Postman export.

DigiCert example: DCV for DV, OV, and EV

For a DV certificate, DigiCert performs Domain Control Validation again for every ACME order; a previous DCV is not prevalidated or reused. The automation host must be able to complete the selected challenge during every renewal.

For OV and EV certificates, unattended ACME issuance requires a prevalidated organization. The domain status must also be valid. DigiCert currently uses reusable OV/EV domain validation with a 199-day period; organization validation for public OV certificates can currently be reused for 397 days. Monitor both periods separately from certificate expiration.

For a wildcard certificate such as *.example.com, DNS-01 is the typical validation method. DNS API access should be permitted to modify only the required zone or record.

Build a secure automation host

The automation host temporarily handles the private key, CA credentials, and an SFOS password with write access. It belongs in a protected management environment, not on a general-purpose administrator notebook or an arbitrary CI runner.

Minimum requirements include:

a hardened and up-to-date operating system with a designated owner;
a fixed source IP address or tightly restricted management network;
outbound access only to the CA, DNS API, and intended firewalls;
separate credentials for the CA, DNS, and each firewall, or for a clearly defined firewall group;
a secret store instead of environment variables, diagnostic output, command-line arguments, or plaintext files;
restrictive file permissions and a temporary working directory on encrypted storage;
no private keys, passwords, or complete XML requests in logs;
a traceable job ID, target firewall, certificate name, and result without secret content;
clock synchronization and alerting for repeated failures or insufficient remaining lifetime.

If the private key is transferred to SFOS in encrypted form, the import password should be no more than 30 characters long for compatibility. The SFOS GUI help specifies this upper limit, while the API help describes 4 to 128 characters depending on the build. Limiting the password to 30 characters is solely a compatibility measure and not a general password-length recommendation. The random password applies only to this key and is transported securely.

Secure Sophos Firewall XML API access describes how to harden the source, service account, Device Access, and API permissions. In SFOS 22, allow only the automation system’s IP Host under Allowed IP hosts in Administration > API access. On older versions, the API configuration is located under a different menu path.

Test run before production renewal

The test run uses a disposable name such as test-fw.example.com, a separate certificate object, and a listener for which an interruption is acceptable. Repeat it after relevant SFOS or automation updates.

Determine the behavior of the deployed build

The tests determine the behavior of the specific build; they do not replace a vendor commitment. Verify and record:

the exact SFOS build and the local API help used;
the exact add and update fields and the identifier field for the existing object;
the result of sending the same request again and after an interrupted upload;
how a certificate file containing the leaf and intermediate certificates is processed, and the resulting CA objects;
the chain actually presented;
whether WebAdmin, portal, WAF, and SMTP references are preserved or lost;
any required listener activation or service restart;
for HA, propagation of the certificate, private key, and assignment, as well as presentation after failover.

Do not assume that a full-chain file is supported without testing. Likewise, the automation must not assume idempotency, preservation of references, or that an automatic retry after an error is safe.

Turn the local add/update example into a request

Use the following process to create a concrete request for the installed build without falsely treating it as universal:

In the target firewall’s local API help, go to System > Certificates > Certificate > Add Certificate / Update Certificate. Save the example configuration and parameter description for this exact build.
For the first case, use the documented add wrapper. For the second case, use the update operation and identifier field shown there. Do not copy either the operation attribute or object identifier from another build.
Replace only the environment-specific values in the example: API credentials from the secret store, object name test-public-cert, the certificate upload action, certificate format, certificate filename, private key filename, and the import password if applicable. Remove unused example branches, but leave element names and nesting unchanged.
Generate the resulting XML request locally as ephemeral reqxml. The two filenames in the XML must exactly match the uploaded files.
In Postman or the HTTP library in use, send a POST request to the following endpoint and select multipart/form-data:
```
https://<Firewall-FQDN>:<Admin-Port>/webconsole/APIController
```
Create exactly three multipart parts: the file part named for the certificate in the local help, the file part named there for the private key, and the reqxml text field. Do not guess the first two part names; take their current names and the filenames from the target build’s example.
Run add first, then run update with a newly issued test certificate. Also send an invalid request in the test environment and read back the state before attempting a retry.
Approve the request only when <Response> and <Status> report the expected success, exactly the intended object was changed, no unexpected CA objects were created, the service reference behaves as recorded, and the external listener presents the new certificate with a valid chain after assignment. For HA, include a controlled failover.

Based on these results, create, test, and internally approve the request for this exact build. Version the three part names, XML template, expected status values, and abort conditions together, without storing credentials or keys.

Verify the certificate before upload

The following examples use these placeholder values:

Service FQDN: vpn.example.com
SFOS object name: public-vpn-example-com
Leaf certificate: vpn.example.com.pem
Private key: vpn.example.com.key
Intermediate bundle: intermediates.pem
Trusted root bundle: trust-roots.pem
External HTTPS port: 443

First, read the certificate data:

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

The issuer, validity period, SANs, and SHA-256 fingerprint must match the order. Then verify that the certificate and private key form the same key pair without displaying the key:

(
  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 produces no output when the public keys are identical. Abort if they differ. An encrypted private key prompts for the password interactively; in automation, retrieve it from the secret store and ensure it appears neither in the process invocation nor in the log.

Verify the intended chain against your own trust store:

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

trust-roots.pem contains the root CAs trusted in your environment, and intermediates.pem contains the intermediate CAs used for issuance. The verification succeeds only with the output vpn.example.com.pem: OK; any other output stops the upload.

Transfer the certificate via the XML API

Checks before upload

Before writing, compare the target firewall, SFOS build, object name, and services with the approved change. A current Sophos Firewall backup, alternative management access, and the previous certificate object must be available. First run a harmless read request using the same host and service account. File permissions and local certificate checks must show no errors.

Send the request and evaluate the response

The automation sends the multipart request approved during the test run. The certificate and private key are transferred as files; reqxml is generated at runtime and then discarded. The client uses the FQDN matching the firewall certificate, validates its CA, and aborts on hostname or certificate errors. curl -k or any comparable disabling of TLS verification is not permitted.

An HTTP status of 200 or Send successful confirms only the transport. At a minimum, the automation evaluates the <Response> element belonging to the operation and its <Status> against the values approved during the test run. After a timeout, incomplete response, or negative status, it first reads back the object state or stops for manual investigation; it does not retry the write request without verification.

Check the object and downloaded file

Find the target object under Certificates > Certificates. Check the information actually available in the GUI, particularly the object name, private key status, Trusted, the Subject, Issuer, and Purpose values shown on hover, and any unexpected additional certificate or CA objects.

Do not assume that the serial number, SANs, expiration date, and SHA-256 fingerprint are guaranteed GUI fields. Export the target certificate using the SFOS download action and inspect the downloaded file:

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

These values must match the file verified before the upload. The green Trusted status alone proves neither correct service assignment nor a complete listener chain. Import and assign certificates on Sophos Firewall explains formats, chains, and GUI import.

Assign the certificate to the service

Import and assignment are separate changes. Explicitly assign a new object to the intended service. For an update, use the method confirmed in the test run and verify that references were actually preserved after the run.

WebAdmin and portals

Under Administration > Admin and user settings > Admin console and end-user interaction, the Certificate field applies jointly to WebAdmin Console, User Portal, VPN Portal, Captive Portal, and the SPX Registration and Reply Portal. The certificate must contain every name actually used as a SAN. After selecting Apply, test every FQDN and port separately; keep an existing administrator session and an alternative local management path open.

WAF

For a WAF publication, select the certificate in the relevant rule under Rules and policies > Firewall in the HTTPS certificate field. The domain, SNI, listen port, and SAN must match. Saving restarts the Web Server Protection rules; existing connections may be interrupted. Whether replacing an already referenced certificate also triggers a reload must be verified for the deployed build during the test run.

SMTP TLS

In MTA mode, the selection is under Email > General settings > SMTP TLS configuration in the TLS certificate field. After selecting Apply, test STARTTLS and, if applicable, implicit TLS separately. VPN and other certificate uses may have their own assignments; an identical name does not mean they switch automatically.

Validate externally with SNI and the correct port

First, check the chain and hostname from a realistic external test host:

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

Expect the required intermediate certificates and Verification: OK. -servername sends SNI; replace the FQDN and port with those of the actual service.

Read the fingerprint, serial number, and other leaf certificate data in a second executable step using the same listener configuration:

(
  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
)

The serial number, SHA-256 fingerprint, validity period, issuer, and SANs must match the approved certificate. Then test the application itself, such as a portal login, WAF health check, or another harmless end-to-end function. An upstream load balancer, CDN, or reverse proxy may terminate TLS with a different certificate, so the test point must correspond to the intended SFOS function.

SMTP with STARTTLS requires a separate command:

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

For implicit TLS on port 465, omit -starttls smtp. Here too, confirm the chain and hostname with Verification: OK; you can read the leaf data with the preceding extraction pattern and adjusted connection options. Then test actual mail flow.

Maintenance window, rollback, and HA

Prepare the maintenance window

Perform the first production run, as well as changes to the request, SFOS build, CA product, or chain composition, during a maintenance window. Keep the previous object available; know the affected assignments, alternative management access, and the people responsible for rollback and external verification.

Choose a rollback strategy

For a new object, the clearest rollback is to select the old certificate again in the affected service and retest the listener externally. Therefore, do not delete the old object in the same run.

When updating an existing object, use only the rollback method confirmed in the test run. If safe restoration of the previous content has not been demonstrated, take the conservative approach of creating a separate new object and then explicitly assigning it.

Test HA separately

In an HA cluster, SFOS generally synchronizes configuration from the Primary to the Auxiliary. Nevertheless, verify the certificate, private key, and service assignment on both nodes or on the shared service. Then perform a controlled failover and test the listener externally. Only a successful test approves the workflow for HA.

Monitoring and recurring operations

The automation must report errors and missed renewals in time. Continuously monitor:

the certificate’s remaining days on the external listener and the next CA renewal window;
DCV status and, for OV/EV, organization validation as well;
the last successful CA order and SFOS upload;
the expected and actually presented fingerprint;
API errors, ambiguous responses, and aborted runs;
unplanned new certificate or CA objects;
credential expiration and rotation;
for HA, the last successful failover test.

The alert must leave enough time for CA/DCV processing, internal response, the maintenance window, and rollback. After a successful change, keep the old certificate for the defined observation period. Delete temporary certificate, key, and XML files in a controlled manner; permanently stored evidence contains only non-secret metadata.

Troubleshooting by symptom

The CA does not issue a new certificate

Check product entitlement, account status, payment method, and DCV with the respective provider. For the DigiCert example, also check automation and the account-model-specific automatic request approval. For OV/EV, the organization and domain must be valid. Investigate DNS-01 errors against the authoritative public DNS, not only the local resolver.

The XML API is unreachable

Check the source IP as seen by the firewall, Allowed IP hosts, Device Access, routing, administrator port, and firewall certificate. The test must be performed from the actual automation host.

The HTTP request succeeds, but the certificate is not updated

Check <Response> and <Status>, not just the HTTP code. Then compare the object name, file format, permitted password length, and build-specific fields with the local API help. Under Diagnostics > Troubleshooting logs, apiparser.log, validation.log, and validationError.log can help; remove all credentials before sharing them. If the state is unclear, download and inspect the certificate object first instead of retrying the write request without verification.

The object is new, but the service presents the old certificate

Check the service assignment, WAF rule, shared certificate selection for WebAdmin and portals, or SMTP configuration. Then test with SNI on the correct port and rule out an upstream TLS endpoint.

The certificate is not `Trusted` or the chain is incomplete

Compare the leaf certificate’s issuer with the installed intermediate CAs. Use the import method confirmed during the test run and inspect the chain sent by the listener with -showcerts.

The old certificate reappears after an update or failover

Determine which node and listener is responding. Then compare the downloaded object’s fingerprint, the service reference, and the HA state. If they differ, perform the confirmed rollback and stop the automation.

Acceptance checklist

Approve the production renewal only when all of the following conditions are met:

CA entitlement, payment, DCV, and organization validation, if applicable, are valid.
The build, local API help, and multipart request match the successful test run.
The local certificate, key, and chain verification succeeded.
<Response> and <Status> report the expected success; exactly the target object was changed.
The downloaded object file has the expected serial number, SANs, validity period, and SHA-256 fingerprint; the private key and Trusted status are correct, and no unexpected objects were created.
Every actual FQDN and port presents the new certificate, expected chain, and Verification: OK with SNI; the associated service works.
For HA, the controlled failover and external verification succeeded.
Monitoring detects the new expiration date and successful result; the old certificate remains available as a rollback path until the end of the observation period.