Hey @pravin,
Message Level Encryption
Message Level Encryption (MLE) on Visa Developer provides an enhanced security for message payload by using asymmetric encryption technique (public-key cryptography). The encryption requires separate key-pairs for Request or Response payloads of the transaction:
- Visa Encryption key pair: The client encrypts the request (message payload) using the Visa public key and Visa decrypts the payload using its private key (Server Encryption Certificate).
- Client Encryption key pair: Visa will encrypt the response (message payload) using the public key (of client, also known as, Client Encryption Certificate) and client decrypts the payload using its private key.
You can generate the encryption keys in the Sandbox, Certification, or Production environments.
The message encryption is implemented via symmetric encryption using Advanced Encryption Standard (AES), Galois Counter Mode (GCM) with 128 bit key size. The encryption of keys is supported using RSA Optimal Asymmetric Encryption Padding (OAEP) with 2048 bit key size.
The following keys are required for making a call:
- Mutual SSL
- Client Request Encryption Key Pair
- Visa Response Encryption Pair
Refer to the Sample Code section for a code snippet that shows MLE implementation for one of the APIs Visa Payments Processing.
Generating Encryption/Decryption Keys (Sandbox)
To generate the encryption/decryption key pairs in the Sandbox environment:
- Create a project using Visa Developer dashboard and select the APIs. Note: If you add Visa Payments Processing APIs in your project, you cannot add any other APIs in the project.
- Go to Credentials > Encryption/Decryption section. Note: Not all APIs in your project will require these credentials. The section will list the APIs for which you will require to use the Encryption credentials.
- Generate the key-pairs by selecting the option Generate Key-ID. This generates a Unique ID (UID), which is associated with your project and identifies the associated key-pairs. Note: This Key-ID must be included as a request header in API calls.
- Generate a CSR for provisioning the Client encryption key pair. The UID field of the CSR must be the generated Key-ID. This is required for validation purposes. The Visa encryption key pair is generated internally by Visa.
- Click on Add CSR. This provides two options to generate a CSR:
- Generate a CSR for me: Use this option if you want Visa to generate a CSR for you. The Key-ID field (UID in CSR) is auto-generated in this case. Make sure you download the certificate Private key.
- Submit my own CSR: Use this option if you have a generated CSR. Click on Browse to upload the CSR and click Confirm.
Note: The CSR file you create must include the following values:
- UID (Key-ID) provided by Visa Developer
- Country Name (2 letter code): <country name>
- State or Province Name (full name):<state name>
- Locality Name (eg, city):<city name>
- Organization Name (eg, company):<organization name>
- Organizational Unit Name (eg, section):<department/section name>
- Common Name (eg, your name or your server`s hostname, fully qualified domain name):<host name>
Note: For all fields, only the following ASCII characters are allowed:
- Space character
- Upper case, A to Z
- Lower case, a to z
- Digits, 0 to 9
- Dash (-)
Once the CSR is validated, the keys are provisioned. You can then view the public certificates under the associated Key-ID:
- Client Encryption Certificate
- Server Encryption Certificate (also known as, Visa Encryption Certificate)
The Key-ID and the associated key-pairs status are now marked as ACTIVE and ready for use.
You can also generate a second set of key-pairs, if required. This is to help you in cases where your current key-pair is compromised or certificate is about to expire. Follow the step (1-5) mentioned above to generate the second key-pair. Finally, make sure you update your project accordingly to use the right key-pair.
Note: You cannot have more than two key-pairs ACTIVE at any point of time.
If you have any issues with key-pair provisioning, contact developer@visa.com.
Generating Encryption/Decryption Keys (Certification and Production)
Once you are ready to promote your project from Sandbox to Certification or Production environment, you must submit your project to Visa for review and approval. Go to the dashboard and select Go Live, and submit all project related information. Visa will review and process your promotion request. For details, refer to Go Live section.
To generate encryption key pairs in Certification or Production environment:
- Reach out to your Visa representative at developer@visa.com for commencing the process of provisioning your project Encryption keys in Certification or Production.
- Visa representative will generate a Key-ID and provide you the same for generating your Encryption CSR. Note: The Key-ID is unique for each environment (Sandbox, Certification and Production) and will need to be included as a request header in API calls.
- Generate CSR using the steps outlined in Encryption CSR Generation section below.
- Send the generated CSR to your Visa representative. Note: Make sure you store the private key as part of CSR generation safely.
- Visa will initiate the Encryption key-pair provisioning (both client encryption and server encryption keys). Note: The key-pair provisioning in Certification and Production environment requires a lead-time of at-least 3 days. Also, until your request is approved, the key-pair (key-ID) will be in Pending state on the dashboard.
- Once the key pair is provisioned, the public certificates will be available for download from the Project dashboard (Credentials > Encryption/Decryption section) in promoted environment (Certification or Production).
Encryption CSR Generation
The CSR file you create must include the following values:
- Country Name (Two-letter International Standards Organization (ISO) 3166-1 country code. For example: US) : <country name>
- State or Province Name (full name) : <state name>
- Locality Name (e.g. city) : <city name>
- Organization Name (e.g. company) : <organization name>
- Organizational Unit Name (e.g. section) : <department/section name>
- Common Name (e.g. your name or your server`s hostname, fully qualified domain name) : <host name>
- UID (Key-ID) provided by Visa Developer
Note: For all fields, only the following ACSII characters are allowed:
- Space character
- Upper case, A to Z
- Lower case, a to z
- Digits, 0 to 9
- Dash (-)
Example commands using Java keytool (a key and certificate management utility):
keytool -genkeypair -alias client -keyalg RSA -keysize 2048 -keystore <<your-keystore-name>>.jks -storepass <your-password>> -keypass <<your-password>> -dname "CN=<<your-domain-name>>, OU=<<organization-unit>>, O=<<organization-name>>, L=<<locality>>, ST=<<state>>, C=<<country name>>, UID=<<unique-encryption-Key-ID >>"
keytool -certreq -alias client -keystore <<your-keystore-name-.jks>> -storepass <<your-password>> -keypass <<your-password>> -file <<your-csr-file-name-.csr>>
Revoking Encryption/Decryption Key-pairs
To revoke a key-pair, use the Revoke option for that Key-ID. This would invalidate the key-ID and associated certificates from any further use. You must make changes accordingly in your project as well to avoid any issues.
Note:
- Revoke is available only in Sandbox environment.
- You cannot generate a Key-ID from Visa Developer for the Certification and Production environments.
- Contact developer@visa.com, if you are unable to revoke a key-pair from Visa Developer
Sample Code (Java)
The code snippet below shows the encryption details for APIs that require Message Level Encryption.
/*© Copyright 2018 Visa. All Rights Reserved.NOTICE: The software and accompanying information and documentation (together, the “Software”) remain the property of and are proprietary to Visa and its suppliers and affiliates. The Software remains protected by intellectual property rights and may be covered by U.S. and foreign patents or patent applications. The Software is licensed and not sold.By accessing the Software you are agreeing to Visa's terms of use (developer.visa.com/terms) and privacy policy (developer.visa.com/privacy). In addition, all permissible uses of the Software must be in support of Visa products, programs and services provided through the Visa Developer Program (VDP) platform only (developer.visa.com).
THE SOFTWARE AND ANY ASSOCIATED INFORMATION OR DOCUMENTATION IS PROVIDED ON AN “AS IS,” “AS AVAILABLE,” “WITH ALL FAULTS” BASIS WITHOUT WARRANTY OR CONDITION OF ANY KIND. YOUR USE IS AT YOUR OWN RISK.*/
HTTP Request Body:
// Define the JWE spec (RSA_OAEP_256 + AES_128_GCM)
JWEHeader.Builder headerBuilder = new JWEHeader.Builder(
JWEAlgorithm.RSA_OAEP_256,
EncryptionMethod.A128GCM);
//Get the keyId from developer portal and substitute in the place holder <keyId from the developer portal> below:
headerBuilder.keyID(“<keyId from the developer portal>”);
//Add token issued at timestamp (iat)
headerBuilder.customParam("iat", System.currentTimeMillis());
//Substitute the actual payload (in clear text form) in the place holder <payload>
JWEObject jweObject = new JWEObject(headerBuilder.build(), new Payload(“<payload>”));
//Substitute the path where the server encryption certificate presents in the place holder <path where server side encryption certificate is present>
String pemEncodedPublicKey = IOUtils.readFileToString(new File("<path where server side encryption certificate is present>"), Charset.forName("UTF-8"));
Certificate cf = (X509Certificate) certFactory.generateCertificate(
new ByteArrayInputStream(pemEncodedPublicKey.getBytes()));
jweObject.encrypt(new RSAEncrypter((RSAPublicKey) cf.getPublicKey()));
String encryptedPayload = "{\"encData\":\""+jweObject.serialize()+"\"}";
Sample Body:
{
"encData" : "<compact serialized JWE string>";
//encData is the field which should carry the encrypted payload (applies to both request and response)
}
where,
compact serialized JWE string = JWE string obtained by applying the encryption algorithm (
RSA_OAEP_256 and AES_128_GCM) + iat header (in Java, it is A128GCM) using the public key from the certificate
Headers:
//Get the keyId from developer portal and substitute in the place holder <keyId from the developer portal> below:
headers.put("keyId", “<keyId from the developer portal>”);
Disclaimer
MLE IS PROVIDED AS IS AND WITHOUT WARRANTY OF ANY KIND. YOUR USE OF MLE IS AT YOUR OWN RISK. VISA ESPECIALLY DOES NOT REPRESENT OR WARRANT THAT MLE OR ITS COMPONENTS WILL BE SECURE, ERROR-FREE OR SUFFICIENT TO SAFEGUARD THE CONFIDENTIALITY OF YOUR DATA.
Here's the direct link to the MLE information above - https://developer.visa.com/pages/encryption_guide#generating_encryptiondecryption_keys_certification...
Thanks,
Diana
Was your question answered? Don't forget to click on "Accept as Solution" to help other devs find the answer to the same question.
