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.
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)
- Unix
- Mac OS
- Windows
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
Para gerar sua chave privada em um computador Mac OS rode em seu terminal:
openssl ecparam -name secp521r1 -genkey -noout -out ec512-private.pem
E a partir desta chave privada gere sua chave pública.
openssl ec -in ec512-private.pem -pubout -out ec512-public.pem
Para gerar seu par de chaves (privada e pública) em um computador Windows, você precisará das ferramentas ssh-keygen e openssl no PowerShell ou GitBash.
Execute o comando abaixo para criar o arquivo da sua chave privada (jwtECDSASHA512.key).
ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key
E a partir desta chave privada gere sua chave pública (jwtECDSASHA512.key.pub).
openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub
Para visualizar a chave em um bloco de notas:
notepad jwtECDSASHA512.key.pub
Para visualizar a chave no terminal:
cat jwtECDSASHA512.key.pub
Caso você adicione uma senha de criptografia em sua chave privada e deseje visualizá-la, será necessário descriptografar com o comando abaixo e sua senha:
openssl ec -in jwtECDSASHA512.key -out chave_descriptografada.pem
Envio da chave pública
Como parte da assinatura das requisições e das respostas, é necessário que você forneça a sua chave pública a nós e que retornemos uma chave pública para você — assim a leitura das mensagens pode ser feita nas duas pontas da comunicação. Além disso, fornecemos uma chave única do tipo UUID (API-CLIENT-KEY) que representa a sua integração via API dentro do nosso sistema.
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 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) e a chave pública da QI Tech.
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.