API Crypto

API Crypto is an API maintained by Sensedia and which is pre-registered on the API Manager. You can use it to perform encryption operations. These operations can be used on other interceptors' flow, such as Digital Signature and Encrypt.

api crypto

This page shows examples on how to use each API resource.

Digest

This resource generates a digest from an algorithm, data, and a salt. As of now, the algorithm available for the hash function is PBKDF2-HMAC-SHA1.

This is an example of using this resource with required payload, and after that a code block of a payload with all possible attributes for the hash function.

Salts are important to avoid dictionary attacks, since they are concatenated with the data before being processed by the hash function, adding randomness to the digest generated.

Example of digest generated from a given piece of data using a PBKDF2-HMAC-SHA1 function:

Request

POST http://<<your-domain>>/api-crypto/api/v1/digest

Headers

Name Description

Content-Type

Should be application/json

Authorization

Basic client_id:client_secret (Base64)
All endpoints of this API are protected with the Client Id Secret Encoded Validation interceptor. Thus, all requests must contain the Authorization header described above.

Request body

{
	"algorithm": "PBKDF2",
	"data": "desired-data",
	"salt": "desired-salt"
}

There are optional attributes in the body that, when not informed, assume the default value of:

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

The attribute saltType treats the reported salt type and can assume HEX (Hexadecimal) or ASCII (String) values.

DigestType treats the returned digest type and can assume HEX (Hexadecimal) or Base64 values.

Response Body

The response will bring its digest with fixed size, according to the hash algorithm used.

{
  "digest": "string"
}

Keys

The resource keys is generates pairs of public-private keys. These keys are essential if your are using the Digital Signature interceptor, but the resource works regardless of interceptors. That is, you can use it to generate keys for the most diverse contexts.

The resource has the following methods and endpoints:

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

The method above generates a pair of keys. As a requirement, it needs a payload containing what type of algorithm will be used to generate the keys.

Example generating RSA keys:

{
	"type": "RSA"
}

Once the request is done, a pair of keys will be contained in the response:

{
    "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
}
As of now, the types supported are RSA and AES.

In addition to the endpoint described above, there is also an endpoint exclusively for the obtention of a public key:

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

It’s easy to use this endpoint. A GET request will return an RSA public key, as in the example below:

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

Sign

This resource signs a key. A use case for the Platform is described on the Digital Signature interceptor’s flow.

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

The backend expects a payload with the following properties:

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

Once the request is done, the signature will be in the request body.

{
  "signature": "k4OoVH9uiNjDpVPqTho17FBdgdROJyT2FD2ngoxSmo/vMPUye8fXZFO1fqj0iI23AXtliRnLxGgndNLAqEY0PAPMtNy0C8MGoQeSSCuRema9q36gNOgUFTtXz/2HiwGN8mbI5p8+CzyPoJvwAI9Xn3nrosSJh5+NIdHFhirQziU="
}
As described above, more example on how to use the resources sign`and `keys on the Platform can be found on the page regarding the Digital Signature interceptor.

Verify

The resource verify has only one endpoint, which validates key and signature.

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

The request must contain a JSON with some required properties:

  "signature": "signature",
  "data": "data",
  "algorithm": "algorithm used to generate the signature",
  "type": "key type"

The response will contain one only property, indicating whether key and signature are valid.

Swagger

There is a Swagger file for API Crypto. You can see it to check the DTOs (Data Transfer Objects) used for each endpoint, which helps to understand the payloads and the way each resource works. This is the URI to access the Swagger interface:

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

Examples on using the encryption generated by the API Crypto module

For more examples regarding using API Crypto, check the pages on the interceptors Digital Signature and Encrypt.

Thanks for your feedback!
EDIT

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