Message Level Encryption

Message Level Encryption provides an enhanced end-to-end security for message payload by using asymmetric encryption technique (public-key cryptography).

Getting Started with MLE

Video Tutorial

What does this tutorial cover?

There are three different types of MLE enforcement levels: Mandatory, Optional, and Not Applicable.

This video will:

1. Guide you through how to identify these three MLE enforcement levels throughout the “client go live journey” and to which environments each level applies.
2. Teach you how to identify APIs that currently do not support MLE.
3. Show you where in the dashboard to find the information necessary to create the MLE Certificate Signing Request (CSR) file.
4. Highlight how Visa allows developers to experiment with MLE in lower environments ( Sandbox and Certification) before MLE is applied to the Production environment, at Visa’s discretion. Please note that depending on the type of data carried in an API payload, Visa may require certain enforcement levels.
5. Review enforcement levels at the individual API level since a single project can contain APIs with different MLE enforcement levels.
6. Provide a high-level overview of the two certificate pairs generated to implement MLE — Visa encryption key pair and Client encryption key.

Why use MLE?

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:

1. PII (Personal Identification Information)
2. PAN (Personal Account Number)
3. PAI (Personal Account Information)

MLE on Visa Developer Platform

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:

1. Visa (Server) Encryption key pair: The client encrypts the request (message payload) using the public key and Visa would decrypt the payload using its private key.
2. Client Encryption key pair: Visa will encrypt the response (message payload) using the public key (of client) and client would decrypt the payload using its private key.

Configuring MLE for Project

Key Management

Key-ID & Its Importance

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 the Message Level Encryption section for applicable projects. At any given time, client can have up to 3 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.

CSR Generation for each Key-ID

Once a Key-ID is generated, you can add 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.

Options for Creating a CSR

In the Sandbox environment, there are two methods for Adding a Certificate Signing Request to a project. By selecting “Generate a CSR for me (default),” Visa Developer will provide you with an automatically generated certificate based on default values. You may also choose to create and upload your own CSR by selecting “Submit my own CSR.”

In Certification and Production environments, there are two methods for Adding a Certificate Signing Request to a project. By selecting “ Create CSR with guidance (Recommended),” Visa Developer will guide you through the CSR generation process in steps. This option is recommended if it is your first time creating a CSR. You may also choose to create and upload your own CSR by selecting “Proceed to upload CSR.”

Creating a CSR with guidance (Certification and Production)

The CSR Wizard helps you create a Certificate Signing Request (CSR) by pre-filling most of the required fields with information from your project.

CSR Field Descriptions

Using Java Keytool

Step 1: Enter the required information for CSR creation.

Step 2: Click 'Generate Commands' to create scripts to create the JKS file and the CSR file.

Run the command to generate the JKS file, then run the command to create the CSR file.

Using OpenSSL

Step 1: Enter the required information for CSR creation.

Step 2: Click 'Generate Commands' to create scripts to create the key pair and the CSR file.

Run the command to generate the key pair, then run the command to create the CSR file.

For additional information on the CSR Wizard, please refer to the CSR Wizard - Frequently Asked Questions (FAQs).

Manually Create my Own CSR

Manually Generating CSR with OpenSSL

Manually Generating CSR with Keytool

1. Create JKS

2. Create CSR JKS

3. Convert JKS keystore created in step 1 to PKCS12 format

4. Extract the private key

If you are using our Message Level Encryption service for decryption, you will need the additional step below:

MLE Certificate Management

Generate MLE Certs - Project Credentials

Regeneration/Renewal of Certificates

Revocation of MLE Certificates

Here are the steps to generate MLE certificates.

1. Click on Generate Key-ID

2. Upload CSR for the generated Key-ID by clicking on Add CSR.

Here are the steps to regenerate new Key-ID and MLE certificates:

1. Click on Generate Key-ID.

2. Click on Add CSR.

3. Once valid CSR is approved, you will be able to see two sets of active MLE credentials.

Here are the steps for the business validations on revocation and impact of revocation.

1. In the Sandbox environment, you can revoke a set of MLE credentials. You should only revoke a set of MLE credentials if you have another set of active MLE credentials to use.

2. A click on Revoke will display a pop up. Once you confirm it will revoke MLE credentials for the Key-ID.

MLE Controls at API Level

Mandatory MLE

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

Optional MLE

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.

Mixed MLE

Some VDP APIs have endpoints with varying MLE controls. By clicking the down arrow to the left of the API Name, you can expand to see the state of MLE for each endpoint of that API.

Not Applicable

Some VDP APIs do not support Message Level Encryption.

MLE Options in Sandbox Tab

MLE Optional and Not Enforced This state is where MLE is not expected to be applied to the payload. The API call can be made without encrypting the payload since the MLE is not enforced. However if the payload has been encrypted, MLE is supported. If a call is received with encrypted payload when MLE Optional is OFF then VISA will decrypt the payload and process it.

MLE Optional and Enforced This state is where MLE is optional, but if toggled to ON, requires 'mandatory' encryption of the payload. The client will be provided with a key ID which will need to be used to generate the CSR and submitted for MLE certificate creation. Post this, the Key-ID will need to be included in the header at the time of making an encrypted API call. Once the toggle is ON, VISA will validate all calls coming on the API for the particular project and ensure that the payloads are encrypted. Un-encrypted payloads will be rejected.

In CERT and PROD environments, the client does not have the option to toggle the state of MLE - even for Optional MLE APIs. Mandatory MLE works the same way irrespective of the environment the client is engaged in. However in both CERT & PROD, the client will be able to view the state of MLE that has been preset by the VDP Admins so that the client is aware of the next steps. The client will also be able to view the Key-ID that they need to use to create the CSR, and be able to track the certificates and download the same from the portal once they have been provisioned for.

Implementing MLE in API Calls

1. Enable the APIs for which MLE needs to be active in VDP by toggling the API for which MLE needs to be enforced.
2. Generate MLE keys by navigating to Project dashboard > Message Level Encryption. Click on Generate Key-ID. Create and upload CSR or use autogenerated CSR and download the certificate private key. Next, download the server and client encryption certificates and also make note of the Key-ID.
3. After generating Key-ID, upload the CSR or use auto generate CSR.
4. Once upload CSR is done, you can check the MLE credentials.
5. Add the keyId as an additional HTTP header.
6. Follow the language-specific snippet guidelines for performing encryption and decryption. Some key points to check are that JWE header must contain fields kid mapped to MLE Key-ID, algorithm namely alg mapped to RSA-OAEP-256, ciphertext encryption algorithm enc equal to A128GCM or A256GCM and also iat which is issued at timestamp. The iat field will be valid for two minutes.
7. For decryption, use the certificate private key.

Downloading required certificates for MLE

Note: Please ensure to add the keyId as an additional HTTP header.

Encrypting Request Payloads

Decrypting Response Payloads

Disclaimer: MLE IS PROVIDED AS IS AND WITHOUT WARRANTY OF ANY KIND. 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.