Two-Way SSL

As one of the security protocols, Visa Developer sandbox secures its connections with clients by means of Two-Way SSL (Mutual Authentication) method.

Tutorial Video

Refer to the video below to quickly learn about how to get credentials to start building with Two-Way SSL.

SSL Handshake

In Two-Way SSL authentication, the client and server need to authenticate and validate each other's identities. The authentication message exchange between client and server is called an SSL handshake, and it includes the following steps:

1. A client requests access to a protected resource.
2. The server presents its certificate to the client.
3. The client verifies the server's certificate.
4. If successful, the client sends its certificate to the server.
5. The server verifies the client’s credentials.
6. If successful, the server grants access to the protected resource requested by the client.

In step 5, the server validates the client, which is the second part of the Two-Way SSL (Mutual Authentication) process. This is typically done by making sure that the client certificate is valid (non-expired and issued by a trusted Certificate Authority), as well as the client’s digital signature is valid. The digital signature is produced using the private key from the client. Anyone that has the public key can validate the digital signature.

Establishing SSL Connection

To establish a Two-Way SSL (Mutual Authentication) connection, you must have the following:

Client Side

• private key
• client certificate
• Visa Developer Platform Root Certificate
• Visa Developer Platform Intermediate Certificate

Server Side

• DigiCert Root Certificate
• DigiCert Intermediate Certificate (optional)

DigiCert Root/Intermediate Certificates

The DigiCert Global Root certificate is available for download at DigiCertGlobalRootG2.crt.pem (PEM) and DigiCertGlobalRootG2.crt (binary).

The Intermediate certificate is available for download at DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt.pem and DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt (binary).

Windows Certificate Management Users: Download the binary (.crt) version of the certificate and open it or right-click and select Install Certificate and follow the instructions in the Certificate Wizard to save the file to your trust store.

Obtaining a Two-Way SSL Certificate

The following sections explain how to obtain a private key, client certificate, and certificate authority root certificate. You will also learn about how to bundle the certificates into keystores, using Java keytool or OpenSSL.

In order to obtain a valid client certificate from Visa Developer, you must submit a Certificate Signing Request (CSR). The CSR file contains client registration details (such as Organization Name and Locality), as well as the public key from the client. The process of creating the CSR yields the CSR file itself and also a private key (which corresponds to a public key, which is encoded into the CSR file). There are multiple tools that you can use to create a CSR, such as Java keytool or OpenSSL.

Refer to one of the following sections on how to obtain a Two-Way SSL certificate.

• Configuring a Two-Way SSL Keystore Using an Auto-generated CSR
• Configuring Two-Way SSL Keystore Using Your Own CSR

Configuring a Two-Way SSL Keystore Using an Auto-generated CSR (Sandbox)

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 can also choose to create and upload your own CSR by selecting “Submit my own CSR.”

Download the private key to your local machine. Once you have made sure it is saved to your computer, please confirm and click done.

Now you should be able to see the active certificate under the "Two-Way SSL" tab. Click the "download" button to download the certificate file.

Configuring a Two-Way SSL Keystore Using Your Own CSR - OpenSSL

OpenSSL is an open source software library that implements Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols, as well as provides basic cryptographic functions and various utilities.

To generate a CSR and private key, run the command shown below from the command line. The command will prompt you for Country Name, State Name, Locality Name, Organization Name, Organization Unit Name, Common Name, and Email Address. For example, notice the output from the resulting files--one is the private key ( privateKey.pem) and the other is the CSR ( certreq.csr).

# Command to generate a CSR and private key
openssl req -nodes -newkey rsa:2048 -keyout privateKey.pem -out certreq.csr

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

CSR Field Descriptions

2. Upload your CSR file to Visa Developer.

In response, Visa Developer will create your client certificate and the Visa Developer CA Root Certificate. Download both the Visa Developer Certificate (Root CA) and certificate (client cert) to a local folder.

Note: You should see both VDPCA-SBX.pem and cert.pem in your local folder.

3. Create the PKCS12 (P12) Certificate Store Using OpenSSL.

In order to invoke Two-Way SSL with a majority of the non-java platforms, you will need the PKCS12 keystore, which is described below. Check your SSL library documentation, as some platforms accept the key and the certificate directly. If this is the case, you can skip this step.

Note: The PKCS12 (P12) files can be imported into the Windows keystore using the Windows certificate import utility. This action will be invoked automatically when you double-click a P12 file.

Place your private key file (for example: privateKey.pem) and your certificate file from VDP (for example: cert.pem) in the same directory.

Run the following OpenSSL command to create the P12 certificate store containing your private key and your client certificate.

1. Generate a keystore (for example: myProject_keyAndCertBundle.p12) file.

# Command to create the P12 store
openssl pkcs12 -export -in cert.pem -inkey privateKey.pem -out myProject_keyAndCertBundle.p12

The resulting file, called myProject_keyAndCertBundle.p12 will contain both your private key and your client certificate.

Note: The Visa Developer sandbox does not validate the VDP root CA, so you do not have to include it in your P12 keystore. However, the root certificate is required when you create your Java Key Store, because you cannot add the client certificate to the JKS file without the root certificate.

Configuring Two-Way SSL Keystore Using Your Own CSR - Java Keytool

Keytool is a certificate management utility that is part of the standard Java distribution.

1. Download the DigiCert Global Root CA certificate from https://dl.cacerts.digicert.com/DigiCertGlobalRootCA.crt to your local folder.

2. Backup your truststore JKS file as a safeguard.

3. Run the following keytool command to add it your truststore

# Command to add DigiCert to truststore
keytool -importcert -alias digicert -file DigiCertGlobalRootCA.crt -keystore mytruststore.jks

Testing Two-Way SSL Connectivity Using SOAPUI

SOAPUI is a free and open-source Web Service Functional Testing solution. With an easy-to-use graphical user interface, SOAPUI allows client developers the ability to rapidly create and execute web service API functional tests. Visa recommends that client developers use SOAPUI or a similar connectivity tool to establish initial connection to the VDP sandbox.

Configuring SOAP UI Two-Way SSL Preferences

To configure Two-Way SSL, you must create the Certificate Signing Request (CSR) and use Visa Developer to obtain the VDP root CA and project-specific certificate. The certificates and the private key need to be bundled together into a keystore (either Java Key store or PKCS12 keystore).

Once the keystore file is available, follow these steps to configure SOAPUI Two-Way SSL preferences.

1. Download SoapUI 5.4 from http://www.soapui.org

2. Once installed, open SOAPUI and go to File > Preferences.

3. Select the SSL Preferences tab, browse to your keystore file (either JKS or P12 file), and provide the keystore password. Make sure to check the requires client authentication checkbox below.

Testing Two-Way SSL Connectivity Using Postman

Postman is a free and open-source API development and testing solution. With an easy-to-use graphical user interface, Postman allows client developers the ability to rapidly create and execute RESTful API functional tests.

Configuring Postman Two-Way SSL Preferences

1. Download Postman from https://www.getpostman.com/ .

2. Once installed, open Postman and go to File > Settings.

3. Select the Certificates tab, click the Add Certificate link, add the Project certificate and private key as shown below and click Add. No Passphrase required.

Sample Code for Two-Way SSL

Java
Python
Node.Js
Ruby
C#
PHP

// Sample Java Code  

# Sample Python Code    

// Sample Node.js Code  

# Sample Ruby Code  

// Sample C# Code  

// Sample PHP Code