Skip to main content

Troca de chaves

Requisição assinada​

Toda a troca de informações entre APIs deverá utilizar o protocolo HTTPS e uma assinatura assimétrica. Nosso modelo de implementação da assinatura é baseado no utilizado pela Amazon, sendo a principal diferença o uso de chaves assimétricas que adicionam uma camada de não-repúdio na comunicação.

Atenção

Todas as nossas API's só aceitam requests HTTPS utilizando TLS 2.0

Toda a comunicação com a QI é assinada, tanto as requisições quanto as respostas, isso significa que existe um parâmetro nas mensagens que garante sua autenticidade. Para realizar tal assinatura, a QI usa um padrão com chaves assimétricas, portanto existem duas chaves diferentes, uma para assinatura (chave privada) e uma para leitura (chave pública). As assinaturas seguem o padrão JWT e o algoritmo de criptografia ECDSASHA512 (Recomendamos FORTEMENTE a exploração do site https://jwt.io/, nele você conseguirá validar JWTs e descobrir bibliotecas para lidar com esses tokens em basicamente qualquer linguagem moderna de programação).

O uso dessa combinação de tecnologias visa criar um canal de comunicação seguro e que garanta que as mensagens enviadas só poderiam vir de uma fonte que possui a chave privada para assiná-la. Por esse motivo o par de chaves pública-privada precisa ser criado de maneira independente por cada uma das partes e a chave privada deve ser guardada em segredo, não sendo divulgada para nenhum terceiro ou parte interessada, nem mesmo a QI.

Geração do par de chaves (pública e privada)​

Para gerar sua chave privada em um computador Unix faça em seu terminal ou linha de comando:

$ ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key

E a partir desta chave privada gere sua chave pública.

$ openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub

Conferindo o formato da chave pública​

A chave pública que esperamos receber é o arquivo gerado pelo segundo comando da seção anterior (openssl ec ... -pubout) — jwtECDSASHA512.key.pub no Unix e no Windows, ec512-public.pem no Mac OS. Ele está no formato PEM, em várias linhas, delimitado por -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY-----, como no exemplo abaixo — que serve apenas para conferir o formato e nunca deve ser cadastrado como a sua chave:

-----BEGIN PUBLIC KEY-----
MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAD8a66B1olkMDoeQM9imiOOCuq1Hq
LOq0bu6ry2GJJzDtjGws5u52SQikFFv0YSRSGpgAJN7cZiuXQkGooDxDvXsAev+2
iQn7HImrLN8YaNPqGMU28UFiuc2SSPf5QdHozEf6LRqq1bhg2oJirpLJAgKlse9M
hhsYr9sznWJDoLOJgjM=
-----END PUBLIC KEY-----

Confira o arquivo antes de nos enviar:

openssl ec -pubin -in jwtECDSASHA512.key.pub -text -noout

A resposta esperada termina em ASN1 OID: secp521r1 e NIST CURVE: P-521. Se o comando responder um erro de leitura, o arquivo não é uma chave pública em PEM.

Se a sua chave está no formato OpenSSH​

O ssh-keygen do primeiro comando também grava um arquivo .pub ao lado da chave privada, mas ele está no formato OpenSSH: uma única linha começando pelo tipo da chave e terminando no comentário.

ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAI... usuario@maquina

Esse arquivo corresponde ao mesmo par de chaves, mas não é o formato aceito no cadastro da sua integração. Você não precisa gerar um novo par: basta executar o comando openssl ec ... -pubout sobre a sua chave privada para obter a mesma chave pública em PEM.

Envio da chave pública​

As suas requisições à API são assinadas com a sua chave privada, e por isso você nos fornece a sua chave pública. Em retorno, fornecemos uma chave única do tipo UUID (API-CLIENT-KEY) que representa a sua integração via API dentro do nosso sistema.

No sentido inverso, os webhooks que a QI Tech envia são assinados por nós. A chave pública da QI Tech, usada para validá-los, é entregue na configuração dos webhooks.

No Insurance-as-a-Service o cadastro da chave pública ainda não está disponível pelo portal QI Tech. Envie a sua chave pública em PEM — o arquivo conferido na seção anterior — ao time de Integração da QI Tech por um meio seguro — entre em contato com api@qitech.com.br para alinhar o canal de envio. Em retorno, você receberá a sua chave de integração (API-CLIENT-KEY).

Atenção!

Nunca compartilhe sua chave privada, ela é de uso exclusivo seu e o compartilhamento da mesma no lugar da chave pública compromete a segurança de suas requests. Além disso, não compartilhe sua chave pública QI Tech e chave de integração pois eles são seu meio de comunicação com nossas APIs.