# A rotação de certificados TLS exige duas provas

Uma autoridade certificadora pode emitir exatamente o certificado pedido por um agente de IA enquanto o serviço continua apresentando o antigo. Já vi tarefas de rotação comemorarem um PEM baixado, um segredo atualizado ou um comando de recarga verde, para depois descobrirem na pior hora que um listener nunca mudou. **Emissão bem-sucedida e implantação bem-sucedida são afirmações diferentes, por isso exigem provas diferentes.**

Uma rotação confiável registra o que a CA emitiu, implanta exatamente esse artefato e abre uma conexão TLS nova para observar o que os clientes recebem. A comparação final deve usar uma identidade estável do certificado, o hostname pretendido e o caminho de rede real. Se o agente não consegue produzir os dois lados dessa comparação, a mudança ainda está em andamento.

## A conclusão exige um contrato de prova explícito

Uma rotação só termina quando o registro do certificado emitido coincide com as observações de todos os endpoints no escopo da implantação. Escreva essa regra antes de dar credenciais ou comandos a um agente. Caso contrário, ele otimizará para aquilo que sua ferramenta chama de sucesso, mesmo que seja apenas uma gravação de arquivo, não uma mudança visível para o cliente.

O registro de emissão deve conter o identificador do pedido ou solicitação, os nomes DNS pedidos, o número de série, a impressão digital SHA-256, o período de validade, o emissor e um resumo da chave pública. Também deve indicar onde a cadeia completa e a chave privada foram armazenadas sem copiar a chave para o log. A impressão identifica todo o certificado folha; o resumo da chave pública mostra se uma reemissão manteve ou trocou a chave.

O registro de implantação responde a outras perguntas: qual destino recebeu o artefato, qual configuração o referencia, qual processo aceitou uma recarga e quando. Uma resposta bem-sucedida da API do plano de controle pertence aqui, mas não prova o serviço. Ela só prova que uma tentativa de transição chegou ao sistema de implantação.

O registro de observação vem de uma conexão nova feita depois da implantação. Precisa do hostname solicitado, do endereço resolvido ou forçado, da porta, do número de série e da impressão observados, do resultado da verificação, do horário e da localização do verificador. A localização importa porque uma sonda interna, uma externa e outra atrás de um proxy corporativo podem alcançar terminações diferentes.

Mantenha mecânica a condição de conclusão:

```text
complete = issuance.valid
        && deployment.accepted
        && every(expected_endpoint,
                 observation.chain_valid
                 && observation.name_valid
                 && observation.leaf_fingerprint == issuance.leaf_fingerprint)
```

Isso torna visível um estado incômodo: o certificado existe e a implantação foi aceita, mas a impressão servida ainda é diferente. Chame o estado de `deployed_unverified`, não de `complete`. Nomes precisos impedem que um painel ou resumo do agente misture silenciosamente duas afirmações.

## A emissão ACME não prova a implantação

ACME prova que uma CA aceitou um pedido e emitiu um certificado após a autorização exigida, mas o protocolo não prova que seu aplicativo o serve. A RFC 8555 descreve quatro etapas principais do cliente: enviar o pedido, provar controle dos identificadores, finalizá-lo com uma solicitação de assinatura e aguardar a emissão para baixar o certificado. O limite termina na obtenção.

Esse limite é fácil de esquecer porque muitos clientes ACME executam um hook de implantação após renovar. O hook fica fora da transação com a CA. Pode falhar porque um caminho mudou, um contêiner montou o segredo antigo, a recarga atingiu o processo errado, uma API remota aceitou uma atualização assíncrona ou um nó ficou inacessível. O pedido continua perfeitamente válido em todos esses casos.

Registre o objeto final do pedido ACME ou a resposta equivalente da CA. Em ACME, `status: valid` e uma URL de certificado preenchida provam a emissão. Capture os identificadores e a impressão da folha retornada após analisar o certificado baixado. Não use a simples existência de um arquivo novo como identidade do artefato; temporários, links simbólicos e nomes reutilizados são provas ruins.

Certificate Transparency também não fecha o circuito. Uma entrada pode mostrar que um certificado público foi emitido para um nome. Não diz se seu balanceador, ingress, servidor web ou CDN agora o apresenta. CT é uma prova independente de emissão, não um monitor de implantação.

A distinção muda o tratamento de erros. Uma falha de emissão significa que o agente nunca obteve a credencial pretendida. Uma falha de implantação significa que ele obteve uma credencial sensível, talvez já armazenada, mas que não está sendo servida. O segundo caso costuma exigir limpeza, repetição ou rollback e merece outro alerta.

## Valide o artefato antes do listener

Antes de implantar, confirme que o certificado folha traz os nomes solicitados, a validade e o emissor esperados, além da chave pública correspondente à privada. Essa barreira encontra bundles malformados e arquivos errados sem tocar na produção. Não substitui a sonda ativa.

A RFC 9525 deixa a regra de identidade nítida: clientes constroem identificadores de referência aceitáveis de forma independente e os comparam com os do certificado. Em serviços DNS comuns, os nomes relevantes ficam na extensão `subjectAltName`. A RFC rejeita explicitamente recorrer a um Common Name parecido com domínio. Um agente que só verifica `subject=CN=...` pode aprovar um certificado que clientes modernos devem rejeitar.

Inspecione o artefato folha com campos de saída reais:

```bash
openssl x509 -in leaf.pem -noout \
  -serial -fingerprint -sha256 -dates -issuer -subject \
  -ext subjectAltName
```

Uma saída típica tem este formato:

```text
serial=03A17C...
sha256 Fingerprint=6B:19:8A:...
notBefore=Jul 24 08:15:00 2026 GMT
notAfter=Oct 22 08:14:59 2026 GMT
issuer=C=US, O=Example CA, CN=Example Issuing CA
subject=CN=api.example.net
X509v3 Subject Alternative Name:
    DNS:api.example.net, DNS:www.example.net
```

Use `openssl x509 -checkhost api.example.net -noout` como barreira automática quando sua versão do OpenSSL suportar. A documentação do OpenSSL define `-checkhost` para conferir se um certificado corresponde a um host. Analise o código de saída, não o texto amigável que pode mudar entre versões.

Compare as chaves públicas sem expor material privado. Estes comandos calculam o hash da chave pública codificada em DER nos dois lados; linhas iguais mostram que certificado e chave privada formam um par:

```bash
openssl x509 -in leaf.pem -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256

openssl pkey -in private-key.pem -pubout -outform DER \
  | openssl dgst -sha256
```

Nunca coloque o conteúdo de `private-key.pem`, o rastreamento de comandos ou uma variável contendo a chave no contexto do agente. Deixe um executor restrito comparar e retornar o resumo e o código de saída. O agente precisa do resultado, não do segredo usado.

## Gravar o arquivo ainda exige ativação

A implantação contém duas operações: posicionar o material novo atomicamente e fazer o terminador TLS carregá-lo. Agentes costumam fazer a primeira e inferir a segunda. Servidores persistentes normalmente guardam certificados analisados na memória, então trocar um arquivo no disco não muda necessariamente os novos handshakes.

Prepare os arquivos ao lado do destino, aplique proprietário e permissões restritas, valide a configuração e então renomeie. Renomear no mesmo sistema de arquivos evita expor um PEM parcialmente escrito. Guarde os arquivos funcionais anteriores ou uma referência versionada até a verificação ativa passar; limpar imediatamente destrói o rollback mais rápido.

A ativação depende do terminador. A documentação do nginx diz que HUP faz o mestre validar a configuração, iniciar workers novos e retirar os antigos de modo gradual; se houver falha, nginx continua com a configuração antiga. Isso protege a disponibilidade, mas cria um falso positivo perfeito quando o agente só registra que enviou HUP. O reinício graceful do Apache também valida sintaxe e inicia uma nova geração enquanto conexões antigas terminam. Balanceadores e CDNs gerenciados podem aceitar uma atualização e concluí-la depois.

Capture o comando ou ID da operação, seu código de saída e a identidade do processo alvo. Em seguida, verifique o estado ou os logs específicos do serviço. Não transforme uma espera fixa em prova. Dormir 30 segundos às vezes mascara consistência eventual e às vezes desperdiça 29; consultar um estado documentado até um prazo é mais claro.

Uma falha de ativação deve parar o fluxo antes que sondas públicas repetidas sobrecarreguem o serviço. Se a sintaxe falhar, a identidade do processo mudar inesperadamente ou o plano de controle relatar erro terminal, preserve o certificado antigo e marque a implantação como falha. Se a ativação disser sucesso mas o endpoint continuar antigo, siga sondando em uma janela limitada porque troca gradual e propagação levam tempo.

## Verifique o que o cliente recebe e o nome

A verificação decisiva abre uma conexão TLS nova, envia o Server Name Indication pretendido, valida a cadeia e o hostname e registra a folha. Examinar um arquivo local não responde o que o cliente recebe. Reutilizar uma conexão keep-alive também não, pois o handshake já escolheu o certificado.

Use OpenSSL com SNI e validação de hostname:

```bash
openssl s_client \
  -connect api.example.net:443 \
  -servername api.example.net \
  -verify_hostname api.example.net \
  -verify_return_error \
  </dev/null 2>/dev/null \
| openssl x509 -noout -serial -fingerprint -sha256 -dates -issuer
```

`-servername` controla SNI, que seleciona o host virtual em muitos listeners compartilhados. `-verify_hostname` verifica a identidade e `-verify_return_error` encerra o comando quando há erro em vez de apenas imprimir o diagnóstico. `-showcerts` exibe a cadeia enviada pelo servidor, mas a documentação alerta que essa lista não é, por si só, uma cadeia validada.

Não adicione `-k`, `--insecure` ou equivalente para fazer a automação passar. O manual do curl diz que uma requisição TLS normal verifica a confiança na CA e a correspondência do hostname. Uma sonda insegura pode confirmar a impressão e ignorar a cadeia quebrada ou o nome errado que afetará usuários.

A impressão sozinha também é insuficiente. Um servidor pode apresentar a folha pretendida com uma cadeia intermediária incompleta e falhar para alguns clientes. A barreira deve exigir caminho de confiança e nome válidos, além da identidade esperada. Se revogação ou política CT fizer parte do perfil real, execute esse perfil; a sonda OpenSSL básica não cobre tudo.

Execute cada observação em processo novo ou desative explicitamente o reuso. Registre stderr na falha, mas o higienize antes de colocá-lo no contexto do agente. Preserve a categoria: conexão, handshake, confiança, identidade ou impressão divergente.

## Cada terminação TLS é um alvo separado

Um hostname não é um escopo de implantação. O escopo é o conjunto de lugares que podem terminar TLS para ele: endereços de balanceadores, pontos CDN, réplicas ingress, portas regionais, caminhos IPv4 e IPv6 e listeners de origem acessíveis. Uma conexão aprovada prova uma rota em um instante.

Monte o inventário esperado a partir do estado da infraestrutura, não da resposta DNS casual da sonda. DNS dinâmico e anycast dificultam amostragem pública exaustiva, então defina um conjunto defensável: cada listener ou associação de certificado configurados, além de sondas nas regiões importantes. Se um fornecedor administra o edge, valide seu estado de implantação e faça amostras externas em mais de um local.

Para testar um endereço específico, `--resolve` do curl é mais seguro que trocar a URL por um IP, pois mantém o hostname original para SNI e validação:

```bash
curl --fail --silent --show-error \
  --resolve api.example.net:443:192.0.2.18 \
  --output /dev/null \
  https://api.example.net/health
```

Repita para cada endereço conhecido, incluindo IPv6 entre colchetes quando suportado. Depois faça a sonda OpenSSL contra o mesmo endereço mantendo `-servername api.example.net`. Um status HTTP correto verifica mais do que TLS, então escolha um endpoint barato e sem mutações; a observação do certificado continua sendo a prova da rotação.

Seja preciso com proxies. Uma sonda de um notebook pode ver o certificado de inspeção corporativa. Uma sonda interna pode contornar o CDN público. Registre localização e caminho de rede, e rejeite a observação quando emissor ou impressão mostrarem que ela não chegou ao terminador pretendido.

Durante uma mudança gradual, espere uma mistura de impressões antigas e novas. É um estado transitório válido, não licença para concluir por maioria. Todos os endpoints devem convergir ou o endpoint com falha precisa ser retirado explicitamente.

## Faça o agente emitir registros comparáveis

Um agente de IA deve produzir provas estruturadas que outro programa compare sem interpretar prosa. Resumos como "a renovação funcionou e o site parece bom" apagam alvo, horário e divergências. Mantenha a explicação humana, mas faça as transições dependerem de campos tipados.

Um par compacto de eventos pode ser:

```json
{"type":"certificate.issued","rotation_id":"rot_7f2","order_id":"ord_91c","dns_names":["api.example.net"],"serial_hex":"03A17C","leaf_sha256":"6B:19:8A:...","spki_sha256":"9f4c...","not_before":"2026-07-24T08:15:00Z","not_after":"2026-10-22T08:14:59Z"}
{"type":"certificate.observed","rotation_id":"rot_7f2","host":"api.example.net","address":"192.0.2.18","port":443,"leaf_sha256":"6B:19:8A:...","chain_valid":true,"name_valid":true,"observed_at":"2026-07-24T08:19:22Z","vantage":"external-us-east"}
```

Use o mesmo `rotation_id` na emissão, tentativas, observações, repetições, rollback e conclusão. Guarde o ID do pedido da CA e o da operação de infraestrutura em campos separados. Misturá-los num ID genérico dificulta reconstruir incidentes.

Repetições precisam de semântica. O agente pode perder a resposta depois que a CA aceita um pedido ou o plano aceita uma associação. Repetir às cegas cria certificados extras, limites ou implantações concorrentes. Dê a cada mutação um token de idempotência derivado da rotação e fase, e consulte a operação remota antes de substituí-la. Registre se a resposta é nova ou repetida.

O frescor também exige regra. Uma sonda aprovada uma hora antes não prova a implantação, mesmo que tenha visto a mesma impressão em outra tentativa. Exija que `observed_at` venha depois da ativação aceita e limite a idade na conclusão. Use o relógio confiável do fluxo ou verificador, não um horário escrito pelo modelo.

Separe a identidade do certificado da identidade do serviço. A impressão responde se é a folha emitida, o hostname se ela vale para o serviço pedido e a cadeia se há confiança aceitável. Juntar tudo em `tls_ok` obriga a repetir testes depois que a prova sumiu.

O inventário também deve ter revisão. Se a infraestrutura adicionar um listener durante a rotação, a conclusão precisa adotar a nova revisão e observá-lo, ou ficar ligada à revisão aprovada e abrir acompanhamento. Ler uma lista móvel cria uma corrida. Guarde a revisão para reconstruir o sentido de "todos".

A coleta deve ser segura para repetir. Use rotas somente leitura, timeouts curtos e concorrência limitada. Um health que aquece cache ou muda sessão é ruim; TLS ocorre antes do HTTP, então uma requisição mínima ou handshake basta. Com milhares de alvos, agende por destino e repita só falhas.

Por fim, separe observação de interpretação. A sonda relata bytes e validação; o comparador decide se satisfazem a rotação. Assim você pode corrigir o comparador e reprocessar provas sem tocar na produção, e o agente não consegue reescrever uma divergência como resumo tranquilizador.

O comparador deve rejeitar observações anteriores à implantação, de hostname ou endereço inesperado ou de outra rotação. Deve comparar impressões binárias normalizadas, não a exibição, pois dois-pontos e maiúsculas variam. Preserve o valor original para operadores.

Não deixe o agente omitir campos. Defina o esquema no fluxo e falhe fechado quando faltar prova. Assinaturas reforçam procedência, mas não consertam uma afirmação fraca. Mesmo assinado, "o comando saiu com zero" não diz qual certificado o cliente recebeu.

Guarde também observações falhas. Impressão divergente, certificado vencido ou nome incorreto explicam por que a tarefa ficou aberta e distinguem propagação lenta de associação errada. Sobrescrever falha com sucesso deixa o log incapaz de explicar a janela do incidente.

## A falha conhecida é uma implantação dividida

Ela começa quieta. O agente obtém um certificado para `api.example.net`, registra o pedido ACME válido, atualiza `api-tls` e recebe sucesso da API. Vê uma nova versão do segredo e fecha o ticket.

O hostname resolve para dois balanceadores. Um controlador observa `api-tls` no namespace de produção e carrega o novo certificado. O outro listener referencia o mesmo nome num namespace antigo. Nenhuma API falhou: o agente atualizou um objeto real, mas não todos os que controlam o hostname.

A maioria chega ao primeiro endereço e vê o novo certificado. Outro caminho serve a folha antiga. Perto do vencimento, falhas parecem intermitentes e repetir parece curar, porque DNS ou balanceamento escolhe outro destino. Operadores culpam caches embora TLS escolha o certificado em cada novo handshake.

A dupla prova expõe a divisão. Emissão diz `6B:19:8A:...`; os endereços retornam esse valor e `41:D0:72:...`. A rotação fica `deployed_unverified`, e a observação divergente nomeia o endereço a corrigir.

A recomendação popular "veja no navegador" é fraca para automação. O navegador pode reutilizar conexão, esconder endereço, usar outra confiança ou passar por inspeção. Serve como checagem independente em incidente, não para concluir. Sondas fixadas no endereço e com hostname validado dão prova repetível.

Depois de corrigir a associação antiga, sonde ambos com conexões novas. Guarde a primeira divergência, a correção e as observações aprovadas. Esse histórico prova o que mudou e por que o fluxo fechou.

## Ações privilegiadas precisam de autoridade estreita

A rotação acessa APIs de CA, segredos e recargas de produção, então o executor deve expor ações estreitas, não credenciais. "Enviar este CSR", "associar artefato X ao listener Y" ou "sondar H por A" são limites úteis. Dar um token reutilizável ao modelo acrescenta risco sem melhorar o raciocínio.

Cada resultado deve incluir ID remoto e campos de prova, sem credenciais nem bytes da chave privada. Separe poderes de emissão, implantação, verificação e rollback. Poder pedir um certificado não deve dar permissão automática para instalá-lo em toda parte.

Sallyport guarda credenciais de API e SSH no cofre criptografado enquanto o agente executa ações HTTP e SSH pelo app, sem recebê-las. Seus diários Activity e Sessions derivam de um log criptografado, encadeado por hash e cego para escrita, adequado para atribuir chamadas sem fingir que substituem observações do certificado.

Coloque aprovação humana onde o impacto aumenta. Renovação rotineira para nome e listener declarados pode usar autorização de sessão; adicionar nome, trocar chave, tocar wildcard ou reverter pede aprovação por chamada. A aprovação deve vincular alvo e impressão exibidos. "Permitir atualização" é vago demais para detectar o listener errado.

Audite o verificador como o implantador. Se o mesmo agente irrestrito pode mudar inventário, implantar e declarar suficiente sua amostra incompleta, o contrato é decorativo. Calcule alvos de fonte controlada e rejeite ausências.

## Conclua só após convergência e mantenha o rollback

A conclusão deve comparar deterministicamente eventos imutáveis. Não deve perguntar se a rotação "parece pronta". Quando todos os endpoints apresentarem a folha emitida com cadeia válida e nome correspondente, registre o resultado exato e conclua.

Defina prazos de propagação. Na janela, repita apenas alvos pendentes com recuo limitado. No prazo, falhe anexando divergências. Reverter depende da validade e saúde: um certificado anterior ainda válido pode ser mais seguro, enquanto um vencido ou revogado exige reparo adiante.

Rollback tem a mesma obrigação de prova. Reassociar o artefato anterior é uma tentativa, e o fluxo deve observar sua impressão antes de declarar recuperação. Se a chave foi comprometida, voltar a ela não recupera nada: emita com chave nova e revogue conforme o plano.

Guarde ambos os certificados até que drenagem e política permitam limpeza. Uma recarga gradual pode deixar workers antigos em conexões existentes, mas sondas novas devem atingir a geração nova. Apague material anterior pela rota controlada e registre a limpeza após a conclusão, não como requisito para servir o novo.

A primeira mudança é pequena e rígida: retire "certificado baixado" e "segredo atualizado" dos estados finais. Exija uma impressão emitida de um lado e impressões novas, com hostname validado, de todo o inventário do outro. O agente pode executar cada etapa, mas só provas coincidentes podem declarar o fim.