API Crypto

A API Crypto é uma API mantida pela Sensedia e que já vem cadastrada no Manager. Você pode utilizá-la para executar operações de criptografia. Essas operações podem ser utilizadas no fluxo de outros interceptors, como o Digital Signature e o Encrypt.

api crypto

No restante da página, veja exemplos de utilização para cada recurso da API.

Digest

A função deste recurso é gerar um digest a partir de um algoritmo, dados, e um salt. Atualmente, o único algoritmo disponível para a função hash é o PBKDF2-HMAC-SHA1.

Segue abaixo um exemplo de utilização do recurso apenas com o payload obrigatório, e após isso um trecho de código de um payload com todos os atributos possíveis para a função hash.

O salt é importante para evitar ataques de dicionário, pois ele é concatenado com os dados antes de ser processado pela função hash, adicionado aleatoriedade ao digest gerado.

Exemplo de como calcular/gerar o digest de um determinado dado usando uma função PBKDF2-HMAC-SHA1:

Requisição

POST http://<<seu-domínio>>/api-crypto/api/v1/digest

Headers

Nome Descrição

Content-Type

Deve ser application/json

Authorization

Basic client_id:client_secret em Base64

Todos os endpoints dessa API são protegidos com o interceptor de Client Id Secret Encoded Validation. Sendo assim, todas as requisições deverão conter o header Authorization descrito acima.

Corpo da requisição

{
	"algorithm": "PBKDF2",
	"data": "dado-desejado",
	"salt": "salt-desejado"
}

No corpo, existem atributos opcionais que, quando não informados, assumem o valor padrão de:

{
	"algorithm": "PBKDF2",
	"data": "dado-desejado",
	"salt": "salt-desejado",
	"saltType": "ASCII",
	"digestType": "BASE64",
	"length": 32,
	"iterations": 1000
}

O atributo saltType trata o tipo de salt informado e pode assumir valores HEX (Hexadecimais) ou ASCII (string).

O digestType trata o tipo de digest retornado e pode assumir valores HEX (Hexadecimais) ou Base64.

Corpo da resposta

A resposta trará seu digest com um tamanho fixo, de acordo com o algoritmo hash utilizado.

{
  "digest": "string"
}

Keys

O recurso keys é responsável por gerar pares de chave público-privada. Essas chaves são fundamentais se você estiver utilizando o interceptor Digital Signature, mas o recurso funciona independentemente de interceptors. Ou seja, você pode usá-lo para gerar chaves nos mais diversos casos de uso.

O recurso keys conta com os seguintes métodos e endpoints:

POST http://<<seu-domínio>>/api-crypto/api/v1/keys

O método acima é responsável por gerar o par de chaves. Como requisito, é necessário um payload contendo qual o tipo de algoritmo que vai ser utilizado para geração das chaves.

Exemplo gerando chaves RSA:

{
	"type": "RSA"
}

Efetuada a requisição, um par de chaves estará contido na resposta:

{
    "privateKey": "sua chave privada em base64 estará contida nessa propriedade",
    "publicKey": "sua chave pública em base64 estará contida nessa propriedade",
    "type": "RSA",
    "creationDate": 1596730568927
}
Atualmente, os tipos suportado são o RSA e o AES.

Além do endpoint descrito acima, também existe um endpoint específico para obtenção de uma chave pública:

GET http://<<seu-domínio>>/api-crypto/api/v1/keys/public

O uso desse endpoint é bem simples. Um GET retornará uma chave RSA pública, como no exemplo abaixo:

{
    "key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCIU/OVuiOQwOQDGiJ0c59dDXstBBVdmyQEjxampko+uvA6PfbHxwNKuMI1vk1qmXipWLoldYLrnFN6uF4OVYdsdfNlXTqrgMI79+fkjtNN4XhDER09vAmVFoqOb9ltgY84cQR82hhX0UtoqTVwhREIAaik+0NO+KBYrIfXdgeh2wIDAQAB"
}

Sign

Este recurso tem como objetivo assinar uma chave. Um caso de uso dentro da Plataforma está descrito no fluxo do interceptor Digital Signature.

POST http://<<seu-domínio>>/api-crypto/api/v1/sign

O backend espera um payload com as seguintes propriedades:

{
    "type": "RSA",
    "data": "data",
    "algorithm": "SHA1"
}

Após a conclusão da requisição, a assinatura estará no corpo da resposta.

{
  "signature": "k4OoVH9uiNjDpVPqTho17FBdgdROJyT2FD2ngoxSmo/vMPUye8fXZFO1fqj0iI23AXtliRnLxGgndNLAqEY0PAPMtNy0C8MGoQeSSCuRema9q36gNOgUFTtXz/2HiwGN8mbI5p8+CzyPoJvwAI9Xn3nrosSJh5+NIdHFhirQziU="
}
Como anteriormente descrito, há mais exemplos sobre o uso dos recursos sign e keys dentro da plataforma na página sobre o interceptor Digital Signature.

Verify

O recurso verify tem apenas um endpoint, que valida uma chave e assinatura.

GET http://<<seu-domínio>>/api-crypto/api/v1/verify

A chamada deverá conter um JSON com algumas propriedades obrigatórias, como a seguir:

  "signature": "assinatura",
  "data": "dados",
  "algorithm": "algoritmo utilizado na geração da assinatura",
  "type": "tipo da key"

O retorno contará apenas com uma propriedade, indicando a validade ou não.

Swagger

A API Crypto contém um arquivo Swagger próprio. Por meio dele, você pode verificar os DTOs (Data Transfer Objects) utilizados em cada endpoint para entender melhor os payloads e também o funcionamento de cada recurso. A URI de acesso à interface do Swagger é esta:

GET http://<<seu-domínio>>/api-crypto/api/v1/swagger-ui.html
gif swagger api crypto

Exemplos de uso da criptografia gerada pelo módulo API Crypto

Para mais exemplos de uso da API Crypto, cheque as página sobre os interceptors Digital Signature e Encrypt

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