Overview of Security

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

What is two-way TLS/SSL

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.

Onboarding Process

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.

Data captured in the above mentioned table

1. 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
   http://bank.com/credit
2. Lender SSL Certificate
3. 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.
4. The document should also have the email address and contact details of the SPOC.
5. Both parties will share IP addresses to the whitelist. Make sure you provide multiple addresses (max
   3. so that datacenter flips can be handled smoothly.

Request Response Signing - Digital Signature

How to generate a public key:

Sample 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:

eyJtZXRhZGF0YSI6eyJ2ZXJzaW9uIjoiMS4wIiwidGltZXN0YW1wIjoiMjAxOC0xMi0wNlQxMTozOTo1Ny4xNTNaIiwidHJhY2VJZCI6ImU4Y2M2ODIyYmQ0YmJiNGViMWI5ZTFiNDk5NmZiZmY4YWNiIiwib3JnSWQiOiJMU1AxMjMifSwicmVxdWVzdElkIjoiZThjYzY4MjJiZDRiYmI0ZWIxYjllMWI0OTk2ZmJmZjhhY2IiLCJsb2FuQXBwbGljYXRpb25JZHMiOlsiZThjYzY4MjJiZDRiYmI0ZWIxYjllMWI0OTk2ZmJmZjhhY2IiXSwiY3JlZEJsb2NrIjp7InR5cGUiOiJPVFAiLCJkYXRhIjp7ImFwcFRva2VuIjoiMGFCQ0Q3RE1yN3MifX19

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:

eyJraWQiOiJjYjU5Y2NlMi03NTgxLTQxNGQtYmZmNy02ZWNmMTMyZGJlZjEiLCJhbGciOiJSUzUxMiJ9

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?

Sample Implementation

Python :: https://github.com/google/jws
Java :: https://github.com/auth0/java-jwt

More Details

1. 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.

2. Encryption specification
   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.

3. 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
   replay attacks.

4. 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
   (https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/)

Reference

1. Algorithms for digital Signatures - https://tools.ietf.org/html/rfc7518#section-3.1
2. JWS RFC - https://tools.ietf.org/html/rfc7515
3. RSA RFC - https://tools.ietf.org/html/rfc3447