Renovar um certificado Sophos Firewall através da API XML e verificar os serviços

Os períodos de validade mais curtos dos certificados TLS de confiança pública aumentam o esforço necessário para as renovações manuais. Por isso, o certificado é emitido num sistema externo, importado a partir de um host de automação protegido, atribuído ao serviço previsto e, depois, verificado no listener real. Uma emissão bem-sucedida ainda não confirma a importação; a existência de um objeto de certificado também não confirma qual certificado é apresentado pelo WebAdmin, portal, WAF ou SMTP.

Os campos XML para add e update são sempre obtidos na API help do build do SFOS utilizado. O campo de identificação de um objeto existente, a preservação das referências e o comportamento após erros são determinados numa execução de teste. Por esse motivo, este artigo não apresenta deliberadamente uma carga útil de atualização supostamente universal.

O procedimento em quatro fases

Preparar: esclarecer as autorizações da CA, validações, host de automação, acesso à API e procedimento de recuperação.
Testar: com um nome dispensável, converter o exemplo local de adição/atualização num pedido multipart específico da versão e aprová-lo.
Renovar: verificar o certificado e a chave, carregá-los e atribuí-los aos serviços previstos.
Validar: verificar o ficheiro do objeto e o listener real, monitorizar a operação e só remover o certificado antigo mais tarde.

Porque é que os períodos de validade exigem uma automação robusta

O período de validade máximo permitido para certificados TLS de confiança pública está a ser reduzido por etapas. De acordo com os Baseline Requirements do CA/Browser Forum, aplicam-se os seguintes limites máximos aos certificados recém-emitidos:

antes de 15 de março de 2026: no máximo 398 dias;
de 15 de março de 2026 a 14 de março de 2027: no máximo 200 dias;
de 15 de março de 2027 a 14 de março de 2029: no máximo 100 dias;
a partir de 15 de março de 2029: no máximo 47 dias.

O período permitido para reutilizar validações de domínio ou IP concluídas também diminui nas mesmas etapas, de 398 para 200, 100 e, por fim, 10 dias. Assim, o certificado e a validação subjacente têm prazos distintos.

Segundo o seu aviso atual sobre períodos de validade mais curtos, desde 24 de fevereiro de 2026, a DigiCert emite certificados TLS públicos com uma validade máxima de 199 dias. Os limites operacionais de 99 e 46 dias só estão anunciados para o início de 2027 e o início de 2029, respetivamente; as datas exatas da transição ainda podem mudar. Por isso, a automação monitoriza o notAfter efetivamente emitido, em vez de assumir uma validade anual fixa.

Distinguir o Let’s Encrypt integrado de uma CA externa

A funcionalidade Let’s Encrypt integrada no SFOS é um processo próprio, gerido pela firewall. Não é um cliente ACME genérico para a DigiCert e não pode ser simplesmente alterado para utilizar um URL ACME da DigiCert. Para o processo integrado, consulte Configurar certificados Let’s Encrypt na Sophos Firewall.

Com uma CA pública externa, a emissão é efetuada num sistema adequado para esse fim. Só o certificado concluído é transferido para o SFOS através da API XML.

Identificar os requisitos independentes da CA

Antes da configuração, é necessário esclarecer os seguintes pontos junto da CA escolhida:

autorização do produto e tipos de certificado permitidos;
encomenda, subscrição ou outra forma de pagamento;
criação, validade e rotação das credenciais ACME ou API;
método DCV suportado para cada nome solicitado;
no caso de OV/EV, a validação da organização necessária;
prazos de validade do certificado, da validação de domínio e da validação da organização.

As designações e os passos de aprovação variam consoante o fornecedor. Por isso, os detalhes de conta seguintes constituem um exemplo concreto da DigiCert, e não um requisito geral de uma CA.

Exemplo da DigiCert: preparar a conta e o ACME

No CertCentral, a funcionalidade de automação tem de estar ativada para a conta em questão. Depois, a configuração e a aprovação variam consoante o modelo de conta:

Nas contas Enterprise, Partner e contas mais antigas sem subscrição, apenas um administrador do CertCentral pode criar o ACME Directory URL. Em seguida, pode entregar as credenciais geradas a uma conta de serviço com permissões estritamente limitadas para a operação contínua.
Nas contas Enterprise e noutras contas sem subscrição, a aprovação automática dos pedidos de certificado tem de estar ativada; sem ela, os pedidos ACME falham por predefinição.
As Subscription Accounts não necessitam desta definição para a aprovação automática de pedidos. No entanto, os produtos disponíveis e o estado da subscrição têm de ser adequados.

Desta forma, as permissões abrangentes necessárias para criar as credenciais permanecem separadas da conta de automação utilizada posteriormente. Antes da primeira encomenda, verifique também a autorização do produto, a forma de pagamento e a atribuição do ACME Directory URL e do External Account Binding à conta e ao produto corretos. Uma pessoa claramente responsável gere a criação, a rotação e a substituição de emergência das credenciais.

As credenciais ACME devem ser guardadas num cofre de segredos protegido. Não devem ser incluídas num repositório, script shell, ticket, exemplo de wiki ou exportação do Postman.

Exemplo da DigiCert: DCV para DV, OV e EV

Num certificado DV, a DigiCert efetua a Domain Control Validation novamente para cada encomenda ACME; uma DCV anterior não é pré-validada nem reutilizada. O host de automação tem de conseguir responder ao desafio escolhido em cada renovação.

Nos certificados OV e EV, uma emissão ACME sem supervisão exige uma organização previamente validada. Além disso, o estado do domínio tem de ser válido. Atualmente, a DigiCert utiliza uma validação de domínio OV/EV reutilizável durante 199 dias; a validação da organização para certificados OV públicos pode atualmente ser reutilizada durante 397 dias. Ambos os prazos são monitorizados separadamente da expiração do certificado.

Para um certificado wildcard como *.example.com, o DNS-01 é o método de validação típico. O acesso à API DNS só deve poder editar a zona ou o registo necessário.

Configurar um host de automação seguro

O host de automação processa temporariamente a chave privada, as credenciais da CA e uma palavra-passe do SFOS com permissão de escrita. Deve estar numa infraestrutura de gestão protegida, e não num computador portátil de administração genérico nem num ambiente de execução de CI arbitrário.

Os requisitos mínimos são:

sistema operativo reforçado e atualizado, com uma pessoa claramente responsável;
IP de origem fixo ou rede de gestão estritamente limitada;
acesso de saída apenas à CA, à API DNS e às firewalls previstas;
credenciais separadas para a CA, o DNS e cada firewall, ou para um grupo de firewalls claramente delimitado;
cofre de segredos em vez de variáveis de ambiente, resultados de diagnóstico, parâmetros da linha de comandos ou ficheiros de texto simples;
permissões de ficheiro restritivas e diretório de trabalho temporário em armazenamento encriptado;
ausência de chaves privadas, palavras-passe ou pedidos XML completos nos registos;
ID de tarefa, firewall de destino, nome do certificado e resultado rastreáveis, sem conteúdos secretos;
sincronização horária e alertas em caso de erros repetidos ou de um período de validade restante demasiado curto.

Se a chave privada for transferida de forma encriptada para o SFOS, a palavra-passe de importação não deve exceder 30 carateres, por motivos de compatibilidade. A ajuda da GUI do SFOS indica este limite máximo, enquanto a ajuda da API descreve, consoante o build, entre 4 e 128 carateres. O limite de 30 carateres destina-se exclusivamente à compatibilidade e não constitui uma recomendação geral para o comprimento de palavras-passe. A palavra-passe aleatória aplica-se apenas a esta chave e é transportada de forma protegida.

O reforço da origem, da conta de serviço, do Device Access e das permissões da API é descrito em Proteger o acesso à API XML do Sophos Firewall. No SFOS 22, em Administration > API access, apenas o IP Host do sistema de automação é permitido em Allowed IP hosts. Nas versões anteriores, a configuração da API encontra-se noutro caminho de menu.

Execução de teste antes da renovação em produção

A execução de teste utiliza um nome dispensável, como test-fw.example.com, um objeto de certificado separado e um listener cuja interrupção seja aceitável. É repetida após atualizações relevantes do SFOS ou da automação.

Determinar o comportamento do build utilizado

Os testes determinam o comportamento do build específico; não substituem uma garantia do fabricante. É necessário verificar e registar:

o build exato do SFOS e a API help local utilizada;
os campos add e update exatos, bem como o campo de identificação do objeto existente;
o resultado do reenvio do mesmo pedido e o resultado após um carregamento interrompido;
o processamento de um ficheiro de certificado com certificados leaf e intermédios, bem como os objetos de CA resultantes;
a cadeia efetivamente apresentada;
a preservação ou perda das referências do WebAdmin, portal, WAF e SMTP;
a ativação do listener ou o eventual reinício do serviço necessário;
em HA, a replicação do certificado, da chave privada e da atribuição, bem como a apresentação após o failover.

Um ficheiro fullchain não é considerado compatível sem verificação. Do mesmo modo, a automação não pode pressupor idempotência, preservação de referências ou uma repetição automática segura após erros.

Do exemplo local de adição/atualização ao pedido

É assim que se cria um pedido concreto para o build instalado, sem o apresentar erradamente como universal:

Na API help local da firewall de destino, aceda a System > Certificates > Certificate > Add Certificate / Update Certificate. Guarde a configuração de exemplo e a descrição dos parâmetros para esse build específico.
No primeiro caso, utilize o wrapper add documentado. No segundo caso, utilize o update aí apresentado e o respetivo campo de identificação. Não copie o atributo de operação nem o identificador do objeto a partir de outro build.
No exemplo, substitua apenas os valores do ambiente: credenciais da API obtidas no cofre de segredos, nome do objeto test-public-cert, ação para o carregamento do certificado, formato do certificado, nome do ficheiro de certificado, nome do ficheiro da chave privada e, se necessário, a palavra-passe de importação. Remova os ramos do exemplo que não sejam necessários, mas mantenha os nomes dos elementos e o aninhamento inalterados.
Crie localmente o pedido XML resultante como um reqxml temporário. Os dois nomes de ficheiro no XML têm de corresponder exatamente aos ficheiros carregados.
No Postman ou na biblioteca HTTP utilizada, selecione POST para o seguinte endpoint e escolha multipart/form-data:
```
https://<Firewall-FQDN>:<Admin-Port>/webconsole/APIController
```
Crie exatamente três partes multipart: a parte de ficheiro indicada na ajuda local para o certificado, a parte de ficheiro aí indicada para a chave privada e o campo de texto reqxml. Os nomes das duas primeiras partes não são presumidos; o respetivo nome atual e os nomes dos ficheiros são obtidos no exemplo do build de destino.
Execute primeiro add e, depois, update com um certificado de teste recém-emitido. Envie também um pedido inválido no ambiente de teste e volte a consultar o estado antes de repetir qualquer operação.
O pedido só é aprovado quando <Response> e <Status> comunicarem o sucesso esperado, tiver sido alterado exatamente o objeto previsto, não tiverem sido criados objetos de CA inesperados, a referência do serviço se comportar conforme registado e, após a atribuição, o listener externo apresentar o novo certificado com uma cadeia válida. Em HA, isto inclui um failover controlado.

Com base nos resultados, o pedido é criado, testado e aprovado internamente para esse build específico. Os três nomes das partes, o modelo XML, os valores de estado esperados e as condições de interrupção são versionados em conjunto, sem guardar credenciais nem chaves.

Verificar o certificado antes do carregamento

Os exemplos seguintes utilizam estes valores substituíveis:

FQDN do serviço: vpn.example.com
nome do objeto SFOS: public-vpn-example-com
certificado leaf: vpn.example.com.pem
chave privada: vpn.example.com.key
bundle intermédio: intermediates.pem
bundle de raízes fidedignas: trust-roots.pem
porta HTTPS externa: 443

Primeiro, consulte os dados do certificado:

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

O emissor, o período de validade, os SAN e a impressão digital SHA-256 têm de corresponder à encomenda. Em seguida, verifique se o certificado e a chave privada formam o mesmo par de chaves, sem apresentar a chave:

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

Se as chaves públicas forem idênticas, o cmp não apresenta qualquer resultado. Em caso de divergência, o processo é interrompido. Uma chave privada encriptada solicita a palavra-passe de forma interativa; na automação, esta é obtida no cofre de segredos e não aparece na chamada do processo nem no registo.

A cadeia prevista é verificada no próprio repositório de confiança:

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

O trust-roots.pem contém as CA raiz consideradas fidedignas no ambiente e o intermediates.pem contém as CA intermédias associadas à emissão. A verificação só é bem-sucedida com o resultado vpn.example.com.pem: OK; qualquer outro resultado interrompe o carregamento.

Transferir o certificado através da API XML

Verificações antes do carregamento

Antes da escrita, compare a firewall de destino, o build do SFOS, o nome do objeto e os serviços com a alteração aprovada. Têm de estar disponíveis uma cópia de segurança do Sophos Firewall atual, o acesso de gestão alternativo e o objeto de certificado anterior. Com o mesmo host e a mesma conta de serviço, execute primeiro uma consulta de leitura sem riscos. As permissões dos ficheiros e as verificações locais do certificado não podem apresentar erros.

Enviar o pedido e avaliar a resposta

A automação envia o pedido multipart aprovado durante a execução de teste. O certificado e a chave privada são transferidos como ficheiros; o reqxml é criado em tempo de execução e, depois, eliminado. O cliente utiliza o FQDN correspondente ao certificado da firewall, valida a respetiva CA e interrompe o processo em caso de erros de hostname ou certificado. A utilização de curl -k ou de uma desativação equivalente da verificação TLS não é permitida.

Um estado HTTP 200 ou Send successful confirma apenas o transporte. No XML, a automação avalia, no mínimo, o elemento <Response> associado à operação e o respetivo <Status> com base nos valores aprovados durante a execução de teste. Em caso de timeout, resposta incompleta ou estado negativo, consulta primeiro o estado do objeto ou interrompe o processo para esclarecimento manual; não repete o pedido de escrita sem verificação.

Verificar o objeto e o ficheiro descarregado

Em Certificates > Certificates, procure o objeto de destino. Na GUI, verifique as informações efetivamente disponibilizadas, em particular o nome do objeto, o estado da chave privada, Trusted, os valores Subject, Issuer e Purpose apresentados ao passar o cursor, bem como objetos adicionais de certificado ou CA inesperados.

Não se pressupõe que o número de série, os SAN, a data de expiração e a impressão digital SHA-256 sejam campos garantidos da GUI. Exporte o certificado de destino através da ação de download do SFOS e verifique o ficheiro descarregado:

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

Estes valores têm de corresponder ao ficheiro verificado antes do carregamento. O estado verde Trusted, por si só, não comprova a atribuição ao serviço correto nem uma cadeia completa no listener. Os formatos, a cadeia e a importação através da GUI são explicados em Importar e atribuir certificados na Sophos Firewall.

Atribuir o certificado ao serviço

A importação e a atribuição são alterações distintas. Um objeto novo é explicitamente atribuído ao serviço pretendido. Numa atualização, é utilizado o método confirmado durante a execução de teste e, após a execução, verifica-se se as referências foram efetivamente preservadas.

WebAdmin e portais

Em Administration > Admin and user settings > Admin console and end-user interaction, o campo Certificate aplica-se conjuntamente à WebAdmin Console, ao User Portal, VPN Portal, Captive Portal, bem como ao SPX Registration e Reply Portal. O certificado tem de conter como SAN todos os nomes efetivamente utilizados. Depois de selecionar Apply, verifique cada FQDN e porta individualmente; mantenha aberta uma sessão de administrador existente e uma via alternativa de gestão local.

WAF

Numa publicação WAF, o certificado é selecionado na regra correspondente, em Rules and policies > Firewall, no campo HTTPS certificate. O domínio, SNI, Listen Port e SAN têm de corresponder. Ao guardar, as regras de Web Server Protection são reiniciadas; as ligações existentes podem ser interrompidas. É necessário verificar durante a execução de teste, com o build utilizado, se a substituição de um certificado já referenciado também provoca um reload.

SMTP TLS

No modo MTA, a seleção encontra-se em Email > General settings > SMTP TLS configuration, no campo TLS certificate. Depois de selecionar Apply, teste separadamente STARTTLS e, se aplicável, TLS implícito. A VPN e outras utilizações de certificados podem ter atribuições próprias; um nome idêntico não significa que mudem automaticamente.

Validar externamente com SNI e a porta correta

Primeiro, verifique a cadeia e o hostname a partir de um host de teste externo realista:

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

Devem ser apresentados os certificados intermédios necessários e Verification: OK. A opção -servername envia o SNI; substitua o FQDN e a porta pelos do serviço real.

A impressão digital, o número de série e outros dados do certificado leaf podem ser consultados num segundo passo executável, a partir da mesma configuração do listener:

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

O número de série, a impressão digital SHA-256, a validade, o Issuer e os SAN têm de corresponder ao certificado aprovado. Em seguida, verifique a própria aplicação, por exemplo, iniciando sessão no portal, efetuando um health check da WAF ou utilizando outra função end-to-end sem riscos. Um load balancer, CDN ou reverse proxy a montante pode terminar o TLS com outro certificado; por isso, o ponto de teste tem de corresponder à função do SFOS pretendida.

O SMTP com STARTTLS requer um comando próprio:

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

Para TLS implícito na porta 465, omita -starttls smtp. Também neste caso, a cadeia e o hostname são confirmados com Verification: OK; os dados do certificado leaf podem ser consultados através do padrão de extração anterior, com as opções de ligação ajustadas. Depois, verifique o fluxo de correio real.

Janela de manutenção, rollback e HA

Preparar a janela de manutenção

A primeira execução em produção, bem como alterações ao pedido, ao build do SFOS, ao produto da CA ou à composição da cadeia, são efetuadas numa janela de manutenção. O objeto anterior permanece disponível; são conhecidas as atribuições afetadas, o acesso de gestão alternativo e as pessoas responsáveis pelo procedimento de recuperação e pela verificação externa.

Escolher a estratégia de rollback

No caso de um objeto novo, o procedimento de recuperação mais claro consiste em voltar a selecionar o certificado antigo no serviço afetado e testar novamente o listener a partir do exterior. Por isso, o objeto antigo não é eliminado na mesma execução.

Ao atualizar o objeto existente, aplica-se exclusivamente o procedimento de recuperação confirmado durante a execução de teste. Se não tiver sido demonstrado que o conteúdo anterior pode ser reposto em segurança, é criado, de forma conservadora, um novo objeto separado e, em seguida, este é explicitamente atribuído.

Testar o HA separadamente

Num cluster HA, o SFOS sincroniza, em princípio, a configuração do Primary para o Auxiliary. Ainda assim, o certificado, a chave privada e a atribuição ao serviço têm de ser verificados em ambos os nós ou no serviço partilhado. Depois, é efetuado um failover controlado com verificação externa do listener. Só um teste bem-sucedido aprova o procedimento para HA.

Monitorização e operação recorrente

A automação tem de comunicar atempadamente os erros e a ausência de renovações. São monitorizados continuamente:

os dias restantes do certificado no listener externo e a próxima janela de renovação da CA;
o estado da DCV e, no caso de OV/EV, também a validação da organização;
a última encomenda bem-sucedida à CA e o último carregamento no SFOS;
a impressão digital esperada e a efetivamente apresentada;
erros da API, respostas ambíguas e execuções interrompidas;
novos objetos de certificado ou CA não planeados;
a expiração e a rotação das credenciais;
em HA, o último teste de failover bem-sucedido.

O alerta tem de deixar tempo suficiente para o processamento pela CA e a DCV, a reação interna, a janela de manutenção e o procedimento de recuperação. Após uma alteração bem-sucedida, o certificado antigo permanece durante o período de observação definido. Os ficheiros temporários de certificado, chave e XML são eliminados de forma controlada; os dados de auditoria guardados permanentemente contêm apenas metadados não secretos.

Resolução de problemas por sintoma

A CA não emite um novo certificado

Verifique junto do respetivo fornecedor a autorização do produto, o estado da conta, a forma de pagamento e a DCV. No exemplo da DigiCert, verifique também a automação e a aprovação automática de pedidos específica do modelo de conta. No caso de OV/EV, a organização e o domínio têm de ser válidos. Verifique os erros de DNS-01 no DNS público autoritativo, e não apenas no resolver local.

A API XML não está acessível

Verifique o IP de origem do ponto de vista da firewall, Allowed IP hosts, Device Access, encaminhamento, porta de administração e certificado da firewall. O teste tem de ser efetuado a partir do host de automação real.

O pedido HTTP é bem-sucedido, mas o certificado não é atualizado

Verifique <Response> e <Status>, e não apenas o código HTTP. Em seguida, compare o nome do objeto, o formato do ficheiro, o comprimento permitido da palavra-passe e os campos específicos do build com a ajuda local da API. Em Diagnostics > Troubleshooting logs, os ficheiros apiparser.log, validation.log e validationError.log podem ajudar; remova todas as credenciais antes de os partilhar. Se o estado não for claro, descarregue e verifique primeiro o objeto de certificado, em vez de repetir o pedido de escrita sem confirmação.

O objeto é novo, mas o serviço apresenta o certificado antigo

Verifique a atribuição ao serviço, a regra WAF, a seleção de certificado partilhada para o WebAdmin e os portais ou a configuração SMTP. Depois, teste com SNI na porta correta e exclua a existência de um endpoint TLS a montante.

O certificado não está `Trusted` ou a cadeia está incompleta

Compare o Issuer do certificado leaf com as CA intermédias instaladas. Utilize o processo de importação confirmado durante a execução de teste e verifique com -showcerts a cadeia enviada pelo listener.

Após uma atualização ou failover, o certificado antigo volta a aparecer

Determine qual o nó e o listener que estão a responder. Depois, compare a impressão digital do objeto descarregado, a referência do serviço e o estado de HA. Em caso de divergência, execute o procedimento de recuperação confirmado e interrompa a automação.

Lista de verificação para aprovação

A renovação em produção só é aprovada quando todos os pontos estiverem cumpridos:

A autorização da CA, o pagamento, a DCV e, se aplicável, a validação da organização estão válidos.
O build, a ajuda local da API e o pedido multipart correspondem à execução de teste bem-sucedida.
A verificação local do certificado, da chave e da cadeia foi bem-sucedida.
<Response> e <Status> comunicam o sucesso esperado; foi alterado exatamente o objeto de destino.
O ficheiro do objeto descarregado tem o número de série, os SAN, a validade e a impressão digital SHA-256 esperados; a chave privada e o estado Trusted estão corretos e não foram criados objetos inesperados.
Cada FQDN e porta reais apresentam, com SNI, o novo certificado, a cadeia esperada e Verification: OK; o serviço correspondente funciona.
Em HA, o failover controlado, incluindo a verificação externa, foi concluído com êxito.
A monitorização deteta a nova data de expiração e o resultado bem-sucedido; o certificado antigo permanece disponível como procedimento de recuperação até ao fim do período de observação.