Thanks for your feedback!
EDIT
Encrypt
This interceptor is used to encrypt and decrypt the contents of a call so that the information is transferred more safely (ensuring confidentiality and integrity).
When confidential data need to be transferred in the body of a request, the Encrypt interceptor encrypts the data with an AES key which is known by the user and the Gateway alone.
For the process to work, an AES key needs to be registered. Then, when a request is received, the Gateway will check whether the key registered is valid, and, if it is, it will relay the message as usual.
Registering the AES key in the gateway
When you use the Encrypt interceptor, your partner needs to adjust their application in order for it to work with encryption.
Let’s follow the steps needed one by one.
1. Possession of an AES key
First of all, your partner must be in possession of an AES key (128 bits, or 16 bytes, AES/CFB/NoPadding).
It must be encrypted following the next steps (altogether, we call this "generating an AES key").
2. Obtention of the public key of the Gateway
For the AES key on item 1 to be encrypted, the public key of the Gateway must be obtained.
The partner must request the public key to generate their encrypted AES key.
To do so, a GET operation to /security/keys must be performed:
curl -X GET https://environmentURL/security/keys
If your environment has API Crypto, use this endpoint instead of the curl above: https://environmentURL/api-crypto/api/v1/keys/public.
|
3. Encryption of the AES key
Now, the public key must be used to encrypt the AES key.
To do so, the preferred script should be run (you can download example scripts below, after this step-by-step explanation).
The return must be the encrypted AES key.
4. Sending the encrypted key and the ID
Now that the key is encrypted, it is necessary to send it via a POST operation to the resource /security/keys.
Along with the key, an ID must be sent.
This is the body expected:
{
"id":"key_id",
"type":"AES",
"key":"encrypted_key"
}As in the previous item, a curl must be used:
curl -X POST http://envonrimentURL/security/keys -d '{ "id": "key_id", "type": "AES", "key": "encrypted_key"}'
If there is API Crypto in the environment, use this endpoint: https://environmentURL/api-crypto/api/v1/keys/public.
|
| "key_id" is a content which can be configured according to your needs; e.g: it can be a client identifier (client ID), app identifier, etc. |
The image below represents the process to generate the AES key.
After these steps are followed through, encryption will work. Now your partner must encrypt the request payload with the AES key and only the Gateway will be able to decode it. If the user sets the interceptor in the response flow, the Gateway will encrypt the payload and the partner must decode it afterwards. All you need for this to happen is to set the interceptor up on the Manager.
Configuring the interceptor on the Manager
When adding this interceptor, users must inform an ID Header Name (a name that will be added to the request header with the ID informed in the previous POST).
The Tokens will also be encrypted option, when marked, will encrypt the headers defined in the Access Token Metric, Client ID Metric, Access Token Validation, Client ID Validation, and OAuth interceptors.
Flow
The interceptor can be inserted in both the request and the response flows (see the image below). It is advisable to always place it in the beginning of the flow, before any other interceptor.
| When inserted in the response, the ID Header Name must match the one informed in the request, and the option to encrypt tokens will not be available. |
Making encrypted calls
Now, when your partner sends a request, it must be encrypted with the AES key, as we have mentioned above. In this case, the request will be decoded when the interceptor runs.
If you place the interceptor in the response flow, your partner will need to decode the payload after receiving it.
The image below illustrates the process.
Validating encrypted access tokens and/or client IDs
Using the Client ID Secret Encoded Validation interceptor, it’s possible to validate an encrypted access token and/or client ID. To do this, you must inform that they will be encrypted and notify your partners to send the values of the access token and/or client ID with encryption.