Aparência
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 doctoravisa a partir de 60 dias do vencimento, e o aviso fica crítico com 7 dias ou menos.finnest opin directory certsmarca 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
| Material | Itens |
|---|---|
| Certificado de servidor ICP-Brasil do gateway mTLS (BRCAC do listener) | brcac-tls-cert-pem, brcac-tls-key-pem |
| Certificado de assinatura BRSEAL | keycloak-brseal-certificate-pem, keycloak-brseal-private-key-pem |
| Cadeias de confiança ICP-Brasil | icp-brasil-ca-crt, icp-brasil-roots-pem, icp-brasil-intermediates-pem |
| Criptografia do request object | keycloak-opin-request-object-enc-private-key-pem, keycloak-opin-request-object-enc-certificate-pem |
| Receptora | opin-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 OFB | ofb-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
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:bashENVIRONMENT=sandbox # ou: prod finnest secrets write brcac-tls-cert-pem --file ./brcac.crt --pair-file ./brcac.key --environment="$ENVIRONMENT" --yesPara os outros itens, use
--file, ou--stdinpara valores lidos da entrada padrão. Também é possível fazer tudo pelo Configuration Workspace:bashfinnest config workspace open --goal=applyConfira:
bashCLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod finnest secrets list --scope regulatory --cloud="$CLOUD" --environment="$ENVIRONMENT" finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"O
doctorvalida a cadeia, o par certificado/chave, os nomes do certificado e o vencimento. Veja Material regulado.Publique com um deploy:
bashCLOUD=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.
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 diffefinnest opin directory certs, informando as credenciais do Diretório (veja a referência definnest opin).Verifique com
finnest smokee, 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) eofb-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 formatov<N>:<32 bytes em base64>) é estável durante o ano-base. Troque-o só em incidente de segurança, comfinnest 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. SeFINNEST_OPIN_RECEIVER_HOLDER_KEY_SECRETestiver 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 mesmax-idempotency-keyde umPOST /connectionsenviado antes dela recebeERRO_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.