JavaScript is disabled. Some features may not work. You can also read the static version: View text version

JWT (Encryption & Signing) Guide

To ensure secure API communication, Juspay uses the JOSE framework, primarily through JWS (JSON Web Signature) for digitally signing/verifying messages and JWE (JSON Web Encryption) for encrypting/decrypting them. This dual-layer security helps prevent fraud, protect sensitive transaction data, and verify the sender’s identity.

In Depth

Analogical Understanding of the crypto setup

Analogical Understanding of crypto Setup

Let’s say we want to have a two way secure messaging system that ensures integrity (no tempering) and confidentiality (no visibility). To facilitate this we use a briefcase with two locks with two keys individually. The two keys are public and private keys (yes the same RSA keys). Public keys can be shared and private keys have to be kept private. The properties of two lock:

Integrity Lock (JWS):
- Ensures the contents haven’t been tampered with. But you can see the contents of the briefcase. Think of it as seal on a document, if malformed the document is tampered with and must not be used.
- You can lock (sign) this by private key and unlock (verify) this by public key. They key usage is intuitive as you don’t want anyone to replace your signature
Confidentiality Lock (JWE):
- Ensures only the recipient of the briefcase can see the contents. You cannot even see the contents of the briefcase.
- You can lock (encrypt) this by public key and unlock (decrypt) this by private key. The key usage intuitive as you want only a trusted person to read the contents.

Using the combination of both the locks we have ensured integrity and confidentiality of the secret. Now let’s see how we send (http request) and receive (http response) the message securely by taking the example of Merchant and Juspay.

Setup:

For this to work both parties will generate the keys and mutually share the public keys with each other (This happens in Juspay via dashboard check the respective section). Now both parties will use their private key and others public key for the secure process.

Send the secret message:

Merchant Sends:- The merchant sends the request by first applying the integrity lock (JWS Sign) using their own private key. Once signed, the payload is then secured with the confidentiality lock (JWE Encrypt) using Juspay’s public key.
Juspay Reads:- Juspay receives the message, then decrypts the JWE (confidentiality layer) using its private key and verifies the JWS (integrity layer) using the merchant’s public key.

Receive the secret message:

Juspay Sends:- Juspay sends the request by first acquiring integrity lock (JWS Sign) by Juspay’s own private key. Once it's done, the secret is then locked by Confidentiality lock (JWE Encrypt) by Merchant’s public key.
Merchant Reads:- Merchant receives the above message then unlock (JWE Decrypt) the Confidentiality lock by Merchant’s private key and unlock (JWS Verify) the Integrity lock by Juspay’s public key.

Special Mention: Key UUID:

Key UUID is used to ask Juspay to use a particular set of keys as merchants can general any number of keys.

JWT Setup

JWTs use 2048-bit asymmetric key pairs—one public and one private key. Since JWT involves both signing and encryption, two separate key pairs are used:

Merchant’s Key Pair: Generated by the merchant. The public key is shared with Juspay. Juspay uses merchant’s public key to verify signed requests and to encrypt responses sent back to the merchant.
Juspay’s Key Pair: Generated by Juspay and the public key shared. Merchant should use Juspay’s public key to encrypt the requests and to verify the responses send back to the merchant.

Keys Generation

How to Generate 2 sets of Public Private Key required for JWT Authentication:

Login to Juspay Portal (Sandbox: https://sandbox.portal.juspay.in; Production: https://portal.juspay.in )
Navigate to Payments -> Settings -> Security module
Scroll Down to JWT Keys section
Click on Upload New JWT
If merchants do not have a public-private key pair generated,
click on option 1 - I don’t have the JWT Keys, I want to auto generate the keys.
1. Juspay public key and merchant’s private key will be auto downloaded as a zip file in the merchant's default browser download folder.
2. Juspay will never store a merchant's private key even though the keys are auto generated.
I don’t have the JWT Keys, I want to auto generate the keys.
If a merchant has already generated or wants to generate a new set of public-private keys, they can click on option 2 - I have the JWT Keys already, I want to manually upload the Public Key.
1. Generate a new pair of RSA 2048 bit keys, using commands below (Skip this step if you already have keys):
2. Merchants will have to upload their public key in the upload file section.
3. Post upload, Juspay’s public Key will be auto downloaded in the merchant's default browser download folder.
I have the JWT Keys already, I want to manually upload the Public Key.
At the end of this step, merchants will have 2 keys - Merchant’s private key and Juspay’s public key which will be used for signing and encryption.
Kindly keep a note of Key Uuid for the JWT keys to be used for encryption and signing. This will be displayed on dashboard post generation.

Sample Codes

To run the sample codes please ensure dependencies and files are properly setup. Encryption and Decryption codes make use of KeyProvider class or File to read keys.

Only for demo purposes the keys have been hardcoded inside the code, it’s unsafe and unsecured. Please keep the keys safe either in file system, env variables or some HSM.

Dependencies

Some of the programming languages use external dependencies. Please inject these dependencies in your code accordingly:

These libraries do not belong to Juspay, hence merchants discretion is required.

Java: nimbus-jose-jwt, bouncy-castle
PHP: web-token/jwt-framework. Please note that some additional dependencies may be required to build this if you are using version 4 or upwards of this dependency, which are listed below:
C#: jose-jwt
Python: pycryptodome

Key Provider

JWT Encryption

Pseudo Code

Demo Encryption Code

JWT Decryption

Pseudo Code

Demo Decryption Code

Download

You can download the above codes using the following link.

Key Rotations

Key rotations for JWT Encryption (Both API Request and Webhooks) are typically straightforward, thanks to the JOSE™ framework that contains protected kid information inside JWE™ and JWS™ headers. Merchants and Juspay can now mutually agree on key pairs using kid, enabling seamless key rotations with minimal changes at Merchant’s end (and possibly without any downtime).

Summary

Have questions?
Need help? Contact support
LLM? Read llms.txt