Pular para o conteúdo principal

mTLS e certificados da API Pix

Resposta rápida: Além do Bearer token, a API Pix do PSP recebedor exige mTLS: o cliente apresenta o certificado emitido no Internet Banking e precisa confiar na CA privada do banco, que costuma vir dentro do próprio .pfx.

O que é​

Mutual TLS: servidor e cliente autenticam com certificados. São três arquivos em jogo, não dois:

ArquivoPapelPlaceholder
Certificado de clienteprova quem você é{{PATH_TO_CERT}}
Chave privadapar do certificado{{PATH_TO_KEY}}
CA do bancoprova quem o servidor é{{PATH_TO_CA}}

Esquecer o terceiro é o erro mais comum. A cadeia do servidor não é pública, então o cliente HTTP falha no handshake com unable to get local issuer certificate — antes de qualquer HTTP, o que faz o erro parecer problema de credencial.

Quando usar​

Em todas as chamadas HTTPS à API, inclusive na emissão do token.

Extrair os três do .pfx​

O banco entrega um PKCS#12 protegido por senha. A CA está dentro dele:

openssl pkcs12 -in banco.pfx -clcerts -nokeys  -out client.crt
openssl pkcs12 -in banco.pfx -nocerts  -nodes  -out client.key
openssl pkcs12 -in banco.pfx -cacerts  -nokeys -out ca.crt

Homologação e produção são .pfx diferentes, com senhas diferentes e autoridades diferentes — mesmo quando o CN da CA é idêntico nos dois. Comparar o fingerprint evita usar a CA errada:

openssl x509 -in ca.crt -noout -fingerprint -sha256

Provar a cadeia antes de culpar o código​

openssl s_client -connect <host-da-api>:443 -CAfile ca.crt </dev/null 2>&1 | grep 'Verify return'

Verify return code: 0 é o único resultado aceitável. Qualquer outro valor significa CA errada ou incompleta.

Regras e limites​

  • Não commitar chave privada nem .pfx.
  • Em ambiente sem arquivo em disco (containers, PaaS), carregue os PEM por variável de ambiente e materialize em diretório temporário com permissão restrita no boot.
  • Desligar a verificação TLS "pra funcionar" abre janela de MITM. Se precisar em HML por falta de CA, que seja atrás de flag explícita e nunca em produção.
  • Regenerar credenciais pode exigir novo certificado — avise o time.

Usado em​