Security
Leegality APIs follow industry-best practices on security. All API communication is secured by default using HTTPS, TLS and SSL protocols.
However, for customers interested in an additional level of security, there are more features in place.
Payload encryption
Pre-requisites
1.
The license plan purchased by your organization should support Payload Encryption.
2.
There needs to be a key-pair exchange between you and Leegality. The Leegality team will share our public key with you (in .cer.txt format) and you need to share your organisation's public key (in .cer.txt format) with us. This key-pair exchange will happen over secure email channels.
3.
Specify the user IDs through which you will make API calls to Leegality.
4.
The Leegality team will map & configure the public certificate shared by you in step 2 above against these specified user IDs.
Steps to use encrypted payloads
1.
Before starting, please ensure you are calling the latest version of the APIs which support payload encryption.
2.
When using payload encryption, pass the request header ‘content-encoding’ with value ‘encrypted’. The other headers should be passed as usual as per the API documentation.
3.
Prepares the standard request payload as per API documentation.
4.
Generate a 256-bit AES key and IV (Initialisation Vector). Use the AES key to encrypt the API payload (prepared in step 3). The encrypted payload has to be sent as the 'payload' key in the API call in the form of a base64 encoded string.
5.
Combine the AES key & IV generated in step 4, and then encrypt the combined string with Leegality’s public key using the RSA algorithm.
6.
This encrypted AES key & IV are to be passed in the API call as the 'salt' key in the form of a base64 encoded string. The ‘salt’ key must be 48 bit long and must contain both the AES key and IV (Initialization vector):
A.
0-32 bits shall contain the Actual AES key; and
B.
32-48 bits shall contain IV.
7.
See a sample of the final request payload below:
API response when using encrypted payloads
1.
On receiving the API call, Leegality will decrypt the ‘salt’ using its private key, and then decrypt the ‘payload’ using the decrypted AES key. After performing business logic, Leegality will prepare the response payload as per API documentation.
2.
Leegality will generate a 256-bit AES key and IV (Initialisation Vector). The AES key will be used to encrypt the response payload which is sent as the 'payload' key in the API response in the form of a base64 encoded string.
3.
The AES key & IV (generated in step 2 above) will be further encrypted with the public key (shared by the customer) using RSA algorithm. The encrypted AES key & IV will be passed in the API response as the 'salt' key in the form of a base64 encoded string. The ‘salt’ key will be 48 bit long and will contain both the AES key and IV:
A.
0-32 bits shall contain the Actual AES key; and
B.
32-48 bits shall contain IV.
4.
See a sample of the final response payload that you will receive from Leegality below:
Note: HTTPS-level success & error codes & messages will not be part of the encrypted payload.
5.
On receiving the response, you will have to first decrypt the ‘salt’ using your organisation's private key to obtain the AES key, and then decrypt the payload using the AES key.
Encryption-related resources
1.
You can access a sample Java application/source code for encryption, decryption and other related steps here:
https://gitlab.leegality.com/leegality-public/encryption-decryption-util.
2.
Encryption in Leegality webhooks works in a similar way, but there are certain additional pre-requisities. For using encryption in Webhooks, refer to our Webhook documentation here:
https://docs.leegality.com/webhooks_resources#section/Payload-Encryption.
Webhook authentication
Webhooks enable the communication of invitation status and signed documents to your application. You may add additional header parameters to the webhook calls for authentication purposes for enhanced security.
You can add the following to the Webhook headers:
1.
Basic authentication parameters (like username and password)
2.
Bearer/Token authentication parameters (fetching token or code from an API request and adding it to the webhook headers)
Steps to configure authentication parameters to webhooks headers
1.
Share your authentication requirements with the Leegality Support Team from your registered admin email ID at support@leegality.com over a secure email including
A.
For static parameters, provide request header parameter names and their ‘values’. For example
B.
For dynamic parameters, provide request header parameter names and their ‘values’. For example
I.
The API documentation for the APIs that need to be called to fetch dynamic values (such as bearer or auth tokens). This should include
1.
API Endpoint/URL
2.
Method type
3.
Request structure and values
4.
Response structure
II.
A final list of key-value pairs that need to be passed in the webhook headers. In the case of static values insert the value to be passed. In the case of dynamic values, specify the parameter to be passed from the API documentation shared above (i.e., the JSON path).
C.
Sample of requested additional parameters
Webhook private salt
Private salt can be used to verify the webhook calls made by Leegality.
To verify the webhook calls made by Leegality using Private Salt, refer to the ‘mac’ parameter in our webhook documentation. Private Salt can only be regenerated by disabling and enabling the API.
IP whitelisting
Whitelisting *.leegality.com ensures that all the subdomains and microservices are whitelisted as well. If this is not done, then you will need to individually whitelist any existing subdomain and any subdomain that will be created in the future. You can access the list of IP and URLs to be whitelisted here.