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

Nome	Descrição
Content-Type	Deve ser `application/json`
Authorization	Basic client_id:client_secret em Base64

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

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

Share your suggestions with us!
Click here and then [+ Submit idea]