Encrypt

Este interceptor tem o objetivo de criptografar e descriptografar o conteúdo de uma chamada para que a informação trafegue com maior confidencialidade e integridade — ou seja, maior segurança.

Quando dados sigilosos devem ser enviados no corpo de uma requisição, o interceptor cifra esses dados com uma chave AES a qual somente o usuário e o gateway tenham acesso.

Para que o processo funcione, é preciso cadastrar a chave AES. Quando receber uma requisição, o gateway primeiro checará se a chave cadastrada é válida e, caso seja, ele encaminhará a mensagem normalmente.

Cadastrando a chave AES no gateway

Quando você utiliza o interceptor de criptografia, é necessário que seu parceiro ajuste sua aplicação para utilizar a criptografia.

Vamos seguir um passo a passo para habilitar o uso do Encrypt.

1. Existência de chave AES
Em primeiro lugar, é necessário que o parceiro tenha em seu poder uma chave AES (128 bits, ou 16 bytes, AES/CFB/NoPadding). Ela terá que ser criptografada (o que chamamos ao longo deste documento como "geração da chave AES").

2. Obtenção da chave pública do gateway
Para que a chave AES do item 1 seja criptografada, é preciso primeiro obter a chave pública do gateway. Para isso, deve-se realizar uma operação GET para o recurso /security/keys:

 curl -X GET https://environmentURL/security/keys
Caso o seu ambiente tenha a API Crypto, utilize o endpoint a seguir ao invés do curl anterior: https://environmentURL/api-crypto/api/v1/keys/public.

3. Criptografia da chave AES
Agora, é preciso utilizar a chave pública para criptografar a chave AES. Para isso, deve-se executar o script de preferência, informando a chave pública (você pode baixar exemplos de script logo depois deste passo-a-passo). O retorno deverá ser a chave AES criptografada.

4. Envio da chave criptografada e do ID
Agora que a chave já está criptografa, é necessário enviá-la por meio de uma operação POST para o recurso /security/keys. Em conjunto com a chave, é necessário enviar um ID. Este deve ser o corpo:

{
    "id":"id_chave",
    "type":"AES",
    "key":"chave_criptografada"
}

Como no item 2, deve ser feito um curl:

curl -X POST http://envonrimentURL/security/keys -d '{ "id": "key_id", "type": "AES", key": "chave_criptografada"}'​
Se houver API Crypto no ambiente, use este endpoint: https://environmentURL/api-crypto/api/v1/keys/public.
O "id_chave" é um conteúdo que pode ser configurado conforme sua necessidade; ele pode ser um identificador do cliente (client ID), da app, etc.

A imagem a seguir representa o processo de geração da chave AES:

encrypt key pt

Com os passos seguidos, a criptografia pode funcionar. É só o parceiro criptografar o payload da requisição com essa chave AES, e só o gateway conseguirá decifrá-la. Se o usuário colocar o interceptor no fluxo da resposta, o gateway irá criptografar o payload e o parceiro deverá descriptografar posteriormente.

Exemplos de scripts

Aqui você encontra dois exemplos de script, um em Java e outro em JavaScript. Eles abarcam os passos necessários descritos acima: geração da chave AES, cadastro da chave no gateway e criptografia do payload usando a chave gerada.

Configurando o interceptor no Manager

Para configurar o Encrypt, informe um ID Header Name (nome que será adicionado no header da requisição com o ID cadastrado no POST anterior).

A opção Tokens will also be encrypted, quando selecionada, irá criptografar os headers definidos nos interceptores Access Token Metric, Client ID Metric, Access Token Validation, Client ID Validation e OAuth.

encrypt

Flow

Este interceptor pode ser inserido tanto no fluxo de requisição quanto no de resposta (veja a imagem abaixo). É aconselhável que ele fique sempre no início do fluxo, antes de qualquer outro interceptor.

encrypt fluxo
Quando inserido no fluxo de resposta, o ID Header Name deve ser o mesmo utilizado no fluxo de requisição e a opção de encriptar tokens não estará disponível.

Fazendo chamadas com criptografia

Agora, quando o seu parceiro realizar uma requisição, ela deve ser criptografada com chave AES. Nesse caso, a requisição será decifrada quando o interceptor for executado.

Caso você coloque o interceptor de criptografia no fluxo da resposta, seu parceiro precisará descriptografá-la.

A imagem abaixo ilustra o processo.

encrypt request pt

Validando access token e/ou client ID criptografados

No interceptor Client ID Secret Encoded Validation, existe a possibilidade de validar um access token e/ou client ID criptografados. Para isso, deve-se informar que eles virão criptografados e notificar os seus parceiros a enviar os valores do access token e/ou client ID criptografados.

Thanks for your feedback!
EDIT
How useful was this article to you?