Security Specifications
All API’s are secured using the below standards:
Three headers values we are using - x-provider-id , x-provider-kid , x-juspay-kid for authorization and key rotation
JOSE standard for signature (JWS) and encryption (JWE) of the payload.
It is recommended to use well known and existing libraries available in the language of your choice to create JWS and JWE.
JWS + JWE payload creation :
Construct the JSON payload to be sent
Use your private key to create a JWS (Signature step) of the payload using RS256 as the algorithm (Usually this is just a call to a crypto library)
Serialize the JWS to below format:
Note// Sample JWS
{
"header": "eyJhbGciOiJIUzI1NiIsI....",
"payload": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI....",
"signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6...."e
}
Stringify the above JSON to form an intermediate payload
Use Juspay’s public key to create a JWE (Encryption step) of the intermediate payload using RSA_OAEP + AES GCM 256 algorithms (Usually this is just a call to a crypto library)
Serialize the JWE to below format:
Note// Sample JWE:
{
"header" : "hbGciOiJIUzI1NiIsInR5cCI6Ikp....",
"encryptedKey" : "NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9....",
"iv" : "iIsInR5c....",
"encryptedPayload" : "DkwIiwibmFtZSI6IkpvaG4gRG9lI....",
"tag" : "2QT4fwpMeJf36POk6y...."
}
Call the push provisioning APIs with the above JSON
Field level Encryption (JWE Direct Encryption) :
The receiver service of the payload might not be the one that consumes the sensitive fields. Thus, we have one more level of encryption (at field level) that ensures only the right service has access to all the PIIs and sensitive information like card/payment instruments details.
We will be using the JWE Direct Encryption with AES256-GCM as an encryption algorithm with a shared key (SKey) between Juspay and the Issuer. This will be provided by Juspay at the time of onboarding. All the fields that start with “enc” are the ones that have field level encryption.
Construct a JSON as shown below to be used as header
Note{
"alg": "dir",
"enc": "AES256"
}
Compute the Base64 encoded value against the UTF8 encoded value of the above JSON, to generate the header element of the JWE
Generate a random 12 byte vector, let’s call it IV (Initialization Vector)
Use Skey + IV to encrypt the field value using AES 256 - GCM algorithm (Use a crypto library)
This would output a cipherText and a tag
Compute the Base64 encoded value of the cipherText to generate the encryptedPayload element of the JWE
Computer the Base64 encoded value of the IV from step 3 to generate the IV element of the JWE
Computer the Base64 encoded value of the tag from step 5 to generate the tag element of the JWE
Using encoded headers from step 1, encoded cipherText from Step 6, encoded IV from step 7 and encoded Tag from step 8, construct following JSON
AAD is additional authentication data , if you are using AAD while doing encryption , base64 encode the aad value and use that in JSON below , else pass an empty string as the AAD value
Note{
"header" : "hbGciOiJIUzI1NiIsInR5cCI6Ikp....",
"iv" : "iIsInR5c....",
"encryptedPayload" : "DkwIiwibmFtZSI6IkpvaG4gRG9lI....",
"tag" : "2QT4fwpMeJf36POk6y....",
"aad" : "2wpMeJf36POk6y....",
}
Stringify the above payload and base64 encode this string
Use the output from step 11 as the value of the “enc*” field
- Have questions?
- Need help? Contact support
- LLM? Read llms.txt
