Message Level Encryption (MLE) allows you to store information or to communicate with other parties while helping to prevent uninvolved parties from understanding the stored information or understanding the communication. MLE can help address the threat of relying on TLS for message security. SSL is designed to provide point-to-point security, which falls short for web/restful services because of a need for end-to-end security. Where multiple intermediary nodes could exist between the two endpoints, MLE would provide that the message remains encrypted, even during these intermediate "hops" where the traffic itself is decrypted before it arrives at Visa servers. Both processes involve a mathematical formula (algorithm) and secret data (key).
MLE is required for APIs that primarily deal with sensitive transaction data (financial/non-financial) which could fall into one or several of the following categories:
MLE on the Visa Developer Platform provides enhanced security for message payload by using an asymmetric encryption technique (public-key cryptography). The message encryption is implemented via symmetric encryption using Advanced Encryption Standard (AES), Galois Counter Mode (GCM) with 128-bit or 256-bit key size. The encryption of keys is supported using RSA Optimal Asymmetric Encryption Padding (OAEP) with 2048-bit key size.The encryption service is based on JWE and works on top of SSL and requires separate key-pairs for Request and Response legs of the transaction:
There are two certificate pairs required for MLE:
Visa (Server) Encryption Key Pair
Visa generates the Server Encryption certificate based on the provided information for a particular Key-ID. Public key for this certificate is available for download via Visa Developer portal under the Encryption/Decryption section of the Credentials page for applicable projects. The client will use this public key to encrypt the request (message payload) and invoke the API call with relevant Key-ID as header attribute. Visa uses the private key associated with the Key-ID to decrypt this payload and process the API request.
Client Encryption Key
Client generates the Client Encryption certificate and uploads the CSR for the relevant Key-ID. Public key for this certificate is stored on Visa servers; public key is available for verification under the Encryption/Decryption section of the Credentials page for applicable projects. Visa will encrypt the response (message payload) using the public key (of client); client will use the applicable private key stored on their environment to decrypt the payload and process the API response.
Key-ID is a system generated unique identifier (UID), which is associated with your project and identifies the associated key-pairs. This Key-ID must be included as a request header in API calls. Key-ID can be generated and is accessible under Encryption/Decryption section of Credentials page for applicable projects. At any given time, client can have upto 2 pairs of Key-IDs active per project. This helps allow for more seamless migration to new MLE certificates.
Your KeyID is distinct to the certificates generated. When you renew these certificates, their KeyID will change and need to be updated in your API calls.
Once a Key-ID is generated, you can upload a CSR (Certificate Signing Request) for each Key-ID. In Sandbox, there are 2 options - ask VDP to generate a CSR for you OR submit your own CSR. If you are submitting your own CSR, the UID value should be the Key-ID. In either case make sure to securely save your private key file as you will need it to decrypt the response.
keytool -genkeypair -alias client -keyalg RSA -keysize 2048 -keystore clientkeystore.jks -storepass <password> -keypass <password> -dname "CN=<common name>, OU=<organizational unit>, O=<organization name>, L=<city/locality name>, ST=<state name>, C=<country name>, UID=<MLE KeyId value>"
Create CSR JKS
keytool -certreq -alias client -keystore clientkeystore.jks -storepass <password> -keypass <password> -file certreq1.csr
Convert JKS keystore created in step 1 to PKCS12 format
keytool -importkeystore -srckeystore clientkeystore.jks -srcstorepass <password> -srckeypass <password> -srcalias client -destalias client -destkeystore clientkeystore.p12 -deststoretype PKCS12 -deststorepass <password> -destkeypass <password>
Extract the private key
openssl pkcs12 -in clientkeystore.p12 -nodes -nocerts -out private-key.pem
If you are using our Message Level Encryption service for decryption, you will need the additional step below:
openssl rsa -in private-key.pem -out private-key_rsa.key
Some VDP APIs show up as Mandatory MLE. This means there is no choice given to the end user, on whether to opt to use MLE when sending payloads across to these API end points. These APIs have been identified as dealing with information falling into a sensitive category and VISA mandates that such API calls are by default encrypted using the MLE framework that is exposed. This works across all the environments (SBX, CERT & PROD).
Some VDP APIs allow the clients to be able to toggle the choice of whether MLE needs to be applied to the API or not - however, this is available only in SBX. The option to go with or without MLE at the time of project promotion to CERT and/or PROD lies with the VDP Admin's discretion. The client is able to view the selection on the project dashboard for CERT & PROD environments. In SBX, depending on whether the client has chosen to opt in to MLE or not, the validations applied at the time of processing the APIs calls will be modified accordingly. This ability gives the clients a migration path to consider for existing projects which would be moving from non-MLE to MLE scenarios, and also provide an option to experiment in a lower environment the checks and balances needed to make an encrypted call vs. a non-encrypted call.