This document describes the security aspects of BHIM for lending and the security processes to be followed between the Lender and the LSP while transmitting data over API calls. On a high level, these are the security aspects that need to be ensured.
1. HTTPS - All API calls must be done securely over HTTPS 2. Two-way TLS - The system should use Two-way TLS to ensure that both parties can send the information securely 3. Digital Signature - All communication between the LSP and Lender should be digitally signed as per the JSON Web Signature Specification 4. Onboarding Process - One Time Onboarding process to be done between LSP and Lenders to configure the security parameters. More details on this in the relevant sections below
The credit system that we are building is an asynchronous system and we need to ensure that both systems follow Transport Layer Security (TLS) Protocol to communicate with each other. In Normal TLS, the client first checks the authenticity of the server. However, the server does not try to identify the client. Since, in our case, we need to verify the identities of both the systems involved, “Two Way SSL” needs to be used. "Two-Way SSL" is usually called TLS/SSL with client certificate authentication because both parties authenticate each other.
To get the Lender onboarded with respect to security, few details need to be collected and shared. This is a one-time process and can be captured using the below form. Once the Lender completes the onboarding form and sends the data, the LSP will share the Public Key that should be used for communication with the Lender and also the key to verify the requests originating from LSP.
Same as what is configured in API
Lender SSL Certificate
Lender Public Key
Also share the kId along with this to identify the key
Back-up Public Key (Optional)
Also share the kId. This key is used for rotation.
This has to be organisation email ID
SPOC contact number
Data captured in the above mentioned table
- Lender URL - The Lender’s endpoint where the LSP APIs are hosted. This should be the base URL.
For example, if the Lender has hosted APIs at the URL -
http://bank.com/credit/v3/loanApplication/createLoanApplicationRequest, then the base URL will be
- Lender SSL Certificate
- Lender Signature verification Key (Public Key)
a. You can configure upto 2 keys (minimum 1 key). You can dynamically switch between these
keys (if two configured) with the kid in the payload. If you want to block use of one of them
then you have to explicitly inform.
- The document should also have the email address and contact details of the SPOC.
- Both parties will share IP addresses to the whitelist. Make sure you provide multiple addresses (max
- so that datacenter flips can be handled smoothly.
How to generate a public key:
openssl genrsa -out privatekey.txt 2048
Sample Public Key
-----BEGIN PUBLIC KEY-----
The JSON Web Signature (RFC7515) standard describes the process of creation and validation of a data structure representing a signed payload. Let’s take an example for the TriggerLoanAcceptanceRequest API. The JSON request object will look like the following:
Before we can sign this, we need to stringify the payload, utf8 encode and then base64 encode this object to obtain the payload. The result of the base64url encoding of the above transaction is:
Additional parameters are associated with each payload. One of those is the required “alg” parameter, which indicates what algorithm needs to be used to generate a signature. This is a mandatory field. Another parameter we will be using is “kid”. “Kid” is a hint indicating which key was used to sign the JWS.
All the above-mentioned parameters are included in the final JWS. These have to be sent as protected headers. Assume we want to sign our payload using a key as we generated in the previous section. Our header JSON would look like this:
and base64url encoded this would be:
We will be using the RS512 algorithm for our use case. RS512 is an abbreviation for RSASSA-PKCS1-v1_5 using SHA-512.
The base64url encoded payload and protected header are concatenated with a ‘.’ to form raw data, which is fed to the signature algorithm to produce the final signature. Finally, all of this output will be structured using the Flattened JWS JSON Serialization Syntax.
What will a Lender and LSP get in every request/response/ack?
curl -X POST -H 'Content-Type: application/json' -d
How are the keys managed?
a. Every lender and LSP will share multiple keys with the counterparty to ensure that the keys
are rotated without any downtime.
b. In case of key compromise counterparty has to be informed explicitly and just changing the
keys in the payload won’t be enough.
a. We will be using the RS512 algorithm for signing (Link). The key size will be 2048 bits. Exact
specification:: We will be using the RS512 algorithm for our use case. RS512 is an
abbreviation for RSASSA-PKCS1-v1_5 using SHA-512.
What are the security issues we have taken care of?
a. Two-way TLS/SSL will help to establish a bi-directional secure transport channel between
the LSP and the Lender. JWS ensures that the message was not tampered with during
transit. 2048 bit RSA for encryption along with SHA512 for hashing ensures the integrity of
the message against attackers.
b. “timeStamp” and “traceId” fields in metaData will together act as a nonce value to avoid
Things you should be careful about
a. Take into account the Security consideration section of the RFC.
b. Be careful about the libraries as some of them are vulnerable as mentioned in this doc
Updated almost 2 years ago