Skip to navigation

Gerar o par de chaves

Gere a chave privada no seu servidor e cadastre só a pública no internet banking.

A credencial da sua conta assina toda requisição com um par de chaves que você gera. A chave privada fica no servidor que chama a API; a pública vai para a tela de credenciais do internet banking. O banco e a CorpX nunca veem a privada — e nunca vão pedir por ela.

Você vai precisar de um terminal com openssl (OpenSSL 1.1.1+, OpenSSL 3 ou o LibreSSL que vem no macOS).

O que é aceito

AlgoritmoChavealg na assinaturaQuando usar
ECDSA P-256EC prime256v1 (P-256)ES256Recomendado. Chave e assinatura curtas, suportado em qualquer linguagem
RSA-PSSRSA de 2048 bits ou maisPS256Quando a chave já vive num HSM/KMS que só faz RSA

A pública é enviada como PEM SPKI: um bloco que começa com -----BEGIN PUBLIC KEY-----. O algoritmo é deduzido do tipo da chave; você não escolhe nada na tela.

São recusados: outras curvas (P-384, secp256k1, Ed25519), RSA abaixo de 2048 bits, -----BEGIN RSA PUBLIC KEY----- (PKCS#1), certificado (BEGIN CERTIFICATE), JWK, chave OpenSSH (ssh-rsa …) e — o erro mais caro — qualquer PEM de chave privada.

1

Gere a chave privada

No servidor que vai chamar a API (não no seu notebook, se puder evitar):

umask 077
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out corpx-signing.key

umask 077 faz o arquivo nascer legível só pelo seu usuário. Se o seu openssl não tiver genpkey, este comando gera uma chave equivalente:

openssl ecparam -genkey -name prime256v1 -noout -out corpx-signing.key

Para RSA (PS256):

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out corpx-signing.key
2

Extraia a chave pública

openssl pkey -in corpx-signing.key -pubout -out corpx-signing.pub
cat corpx-signing.pub
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE6VuQL7n18jc/8dHENPXeHZrdCVPu
q2j496awbvsDhxWTVj3hBScPI9MioPmlfS9nNUo9MJhTDNMfVRUALXXrfg==
-----END PUBLIC KEY-----

Uma chave EC tem essas 4 linhas; uma RSA de 3072 bits, cerca de 11. Para conferir o tipo:

openssl pkey -pubin -in corpx-signing.pub -noout -text | grep -E 'Public-Key|ASN1 OID'
# EC: Public-Key: (256 bit) / ASN1 OID: prime256v1
# RSA: Public-Key: (3072 bit)

Se a sua chave está em HSM/KMS, exporte a pública em PEM (SPKI). Se ela saiu como BEGIN RSA PUBLIC KEY, converta:

openssl rsa -RSAPublicKey_in -in chave-pkcs1.pub -pubout -out corpx-signing.pub
3

Anote a impressão digital e o kid

A impressão digital é o SHA-256 do DER da chave pública. É ela que a tela do internet banking mostra quando você cola a chave:

openssl pkey -pubin -in corpx-signing.pub -outform DER | openssl dgst -sha256 -c
# SHA2-256(stdin)= cf:e8:29:14:43:21:51:53:e1:1b:76:a7:a5:33:dd:3c:3d:fc:d3:ab:23:b9:d2:96:f3:5e:44:b9:6c:bc:63:7c

(As saídas de exemplo nesta página são da chave pública do vetor de teste.)

O kid — o identificador que vai em toda assinatura — são os primeiros 16 bytes desse mesmo hash, em hex, sem os ::

openssl pkey -pubin -in corpx-signing.pub -outform DER | openssl dgst -sha256 -r | cut -c1-32
# cfe8291443215153e11b76a7a533dd3c

O kid é derivado, não sorteado: você recalcula offline e confere que cadastrou a chave certa. Os exemplos de código calculam o kid a partir da chave privada, então não há o que configurar.

4

Cadastre a pública no internet banking

Quem emite a credencial é o titular da conta (ou um operador com permissão para isso), na tela Credenciais de API do internet banking:

  1. Cadastre antes o IP de saída do servidor em IPs permitidos. Sem pelo menos um IP a credencial não é emitida.
  2. Clique em Emitir credencial de API, dê um nome (ex.: ERP produção) e marque os escopos.
  3. Em Chave pública (PEM), cole o conteúdo inteiro de corpx-signing.pub, com as linhas BEGIN e END.
  4. Confira se a impressão digital que aparece abaixo do campo é a mesma do passo 3.
  5. Emita. A tela mostra client_id, client_secret e token_url uma única vez: guarde o client_secret no seu cofre de segredos antes de fechar.

A credencial nasce em carência: ela passa a valer 18 horas depois da emissão. Até lá as chamadas respondem 403. Veja Autenticação.

Colou a chave privada?

A tela recusa um PEM de chave privada, mas trate a chave como comprometida mesmo assim: ela passou por clipboard, navegador e talvez por um chat. Gere outro par e cadastre a nova pública.

Confira que a privada e a pública são o mesmo par

Antes de cadastrar, e sempre que trocar de servidor:

diff <(openssl pkey -in corpx-signing.key -pubout) corpx-signing.pub && echo "mesmo par"

Guardar a chave privada

  • Nunca envie a privada a ninguém — nem ao banco, nem ao suporte da CorpX. Ninguém do nosso lado precisa dela.
  • Não a coloque em repositório, imagem de container, variável de CI exposta em log ou ticket. Prefira um cofre (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) ou, melhor, um KMS/HSM que assina sem exportar a chave.
  • No disco, permissão 600 e dono igual ao usuário do serviço: chmod 600 corpx-signing.key.
  • Um par por ambiente. Homologação e produção com a mesma chave fazem um vazamento em homologação valer em produção.

Rotacionar

A credencial aceita mais de uma chave pública ao mesmo tempo, então a troca não derruba nenhuma chamada:

  1. Gere o par novo (passos 1 a 3).
  2. Cadastre a pública nova pela API — POST .../public-keys, descrito em Chaves e IPs. Ela entra em carência de 18 horas.
  3. Passada a carência, troque a privada no servidor. O kid muda junto.
  4. Aposente a chave antiga (DELETE .../public-keys/{kid}). Remover vale na hora.

Se a privada vazou, não espere a rotação: aposente a chave ou peça ao titular para revogar a credencial no internet banking. As duas coisas valem imediatamente.

Próximo passo

Com a credencial ativa, assine as requisições — ou vá direto aos exemplos de código.