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
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.
Gere a chave privada
No servidor que vai chamar a API (não no seu notebook, se puder evitar):
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:
Para RSA (PS256):
Extraia a chave pública
Uma chave EC tem essas 4 linhas; uma RSA de 3072 bits, cerca de 11. Para conferir o tipo:
Se a sua chave está em HSM/KMS, exporte a pública em PEM (SPKI). Se ela
saiu como BEGIN RSA PUBLIC KEY, converta:
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:
(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 ::
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.
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:
- Cadastre antes o IP de saída do servidor em IPs permitidos. Sem pelo menos um IP a credencial não é emitida.
- Clique em Emitir credencial de API, dê um nome (ex.:
ERP produção) e marque os escopos. - Em Chave pública (PEM), cole o conteúdo inteiro de
corpx-signing.pub, com as linhasBEGINeEND. - Confira se a impressão digital que aparece abaixo do campo é a mesma do passo 3.
- Emita. A tela mostra
client_id,client_secretetoken_urluma única vez: guarde oclient_secretno 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.
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:
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
600e 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:
- Gere o par novo (passos 1 a 3).
- Cadastre a pública nova pela API —
POST .../public-keys, descrito em Chaves e IPs. Ela entra em carência de 18 horas. - Passada a carência, troque a privada no servidor. O
kidmuda junto. - 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.