Skip to content

Rotação de certificados ​

Os certificados ICP-Brasil, as chaves e os segredos da plataforma ficam no cofre de segredos da nuvem da instituição (AWS Secrets Manager ou Azure Key Vault). O cluster os recebe pelo External Secrets Operator. Por isso, a troca é feita pela CLI e publicada por um deploy, e não direto no Kubernetes: uma alteração manual no cluster seria desfeita na próxima sincronização.

Quando trocar ​

  • Antes do vencimento. O finnest doctor avisa a partir de 60 dias do vencimento, e o aviso fica crítico com 7 dias ou menos. finnest opin directory certs marca os certificados do Diretório que vencem em 30 dias ou menos.
  • Imediatamente, se houver suspeita de comprometimento de uma chave.
  • Quando o cadastro no Diretório de Participantes mudar.

Itens de material regulado ​

MaterialItens
Certificado de servidor ICP-Brasil do gateway mTLS (BRCAC do listener)brcac-tls-cert-pem, brcac-tls-key-pem
Certificado de assinatura BRSEALkeycloak-brseal-certificate-pem, keycloak-brseal-private-key-pem
Cadeias de confiança ICP-Brasilicp-brasil-ca-crt, icp-brasil-roots-pem, icp-brasil-intermediates-pem
Criptografia do request objectkeycloak-opin-request-object-enc-private-key-pem, keycloak-opin-request-object-enc-certificate-pem
Receptoraopin-receiver-jwks-json, opin-receiver-jws-private-jwk-json, opin-receiver-jwe-private-jwk-json, opin-receiver-client-cert-pem, opin-receiver-client-key-pem
Receptora OFBofb-receiver-jwks-json, ofb-receiver-jws-private-jwk-json, ofb-receiver-jwe-private-jwk-json, ofb-receiver-client-cert-pem, ofb-receiver-client-key-pem
Receptora OFB durante a troca (opcional)ofb-receiver-jwe-retired-jwks-json, ofb-receiver-client-retired-cert-pem, ofb-receiver-client-retired-key-pem
Certificado TLS próprio do host api. (opcional)api-edge-tls-cert-pem, api-edge-tls-key-pem, exigidos com api_certificate_source = "operator"
Cliente de sonda OPIN do smoke (opcional)opin-probe-client-cert-pem, opin-probe-client-key-pem

Os itens exigidos dependem do papel da instituição. O Configuration Workspace mostra os que faltam para o seu papel.

Na troca da receptora OFB, guarde as chaves de criptografia antigas em ofb-receiver-jwe-retired-jwks-json, cada uma com o seu kid, enquanto as transmissoras ainda podem usá-las. A chave antiga sai do ofb-receiver-jwks-json publicado, não pode ser a chave de assinatura e não pode usar o kid da nova chave de criptografia. Se algum desses casos ocorrer, o finnest doctor aponta o erro e o deploy é bloqueado, porque o banking não iniciaria. O finnest secrets write confere só cada valor isolado. Ao renovar o certificado de transporte, guarde o certificado e a chave antigos no par ofb-receiver-client-retired-cert-pem / ofb-receiver-client-retired-key-pem. Grave o par de uma vez, com --pair-file. Quando a troca terminar, remova os itens antigos com finnest secrets remove <item> --yes (os dois itens do par) e rode um deploy. Um certificado antigo vencido bloqueia o deploy como qualquer outro.

Passo a passo ​

  1. Grave o material novo. Os arquivos precisam pertencer ao operador e ter permissão 0600. Para um certificado e sua chave, grave o par de uma vez:

    bash
    ENVIRONMENT=sandbox  # ou: prod
    finnest secrets write brcac-tls-cert-pem --file ./brcac.crt --pair-file ./brcac.key --environment="$ENVIRONMENT" --yes

    Para os outros itens, use --file, ou --stdin para valores lidos da entrada padrão. Também é possível fazer tudo pelo Configuration Workspace:

    bash
    finnest config workspace open --goal=apply
  2. Confira:

    bash
    CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
    finnest secrets list --scope regulatory --cloud="$CLOUD" --environment="$ENVIRONMENT"
    finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"

    O doctor valida a cadeia, o par certificado/chave, os nomes do certificado e o vencimento. Veja Material regulado.

  3. Publique com um deploy:

    bash
    CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
    finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --preview
    # <confirmação>: aws:<conta>:<ambiente> ou azure:<tenant>:<assinatura>:<ambiente>
    finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes --confirm=<confirmação>

    O deploy grava o material no cofre de segredos da nuvem, e o External Secrets Operator o leva ao cluster.

  4. Atualize o Diretório de Participantes quando a troca envolver um certificado ou chave pública cadastrada lá, seguindo o processo do Diretório. Depois confira o cadastro com finnest opin directory diff e finnest opin directory certs, informando as credenciais do Diretório (veja a referência de finnest opin).

  5. Verifique com finnest smoke e, no Open Insurance, finnest opin verify.

Cuidados ​

  • As chaves que cifram dados guardados pela receptora não têm troca: opin-receiver-data-encryption-key-base64 (credenciais de gestão de DCR da receptora OPIN) e ofb-receiver-secret-key-base64 (tokens de conexão da receptora OFB). Não há como cifrar de novo os dados com uma chave nova. Por isso, a CLI recusa gravar um valor diferente do que já está em uso. Gravar a chave pela primeira vez, ou de novo com o mesmo valor, é permitido.
  • O segredo da chave de titular da receptora (opin-receiver-holder-key-secret, no formato v<N>:<32 bytes em base64>) é estável durante o ano-base. Troque-o só em incidente de segurança, com finnest secrets write opin-receiver-holder-key-secret --incident-rotation --yes: a CLI gera a versão seguinte (v<N+1>) e recusa qualquer outra versão. Valores derivados das versões anteriores não são recalculados. Se FINNEST_OPIN_RECEIVER_HOLDER_KEY_SECRET estiver definida no ambiente com um valor diferente do armazenado, a CLI recusa a troca até que a variável seja removida ou passe a coincidir com o valor armazenado. Depois da rotação, uma retentativa com a mesma x-idempotency-key de um POST /connections enviado antes dela recebe ERRO_IDEMPOTENCIA, mesmo com corpo idêntico, porque o serviço não guarda mais a versão aposentada para recalcular o fingerprint. Oriente os clientes a reenviar esses pedidos com uma key nova.
  • Nunca grave chaves privadas em repositórios, tickets ou logs. A CLI não aceita valores secretos na linha de comando (--value), só por arquivo ou pela entrada padrão.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br