Docs play_arrow Two-Way SSL

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. 

Two-Way SSL 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 others 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 (above), 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. (However, only the client that has the private key can create a valid signature.)

Establishing SSL Connection

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

  • private key
  • client certificate
  • certificate authority root certificate, and 
  • certificate authority intermediate certificates (Note: These certificates are optional for the Visa Developer sandbox)

DigiCert CA Certificate

The DigiCert Global Root CA certificate is available for download at https://dl.cacerts.digicert.com/DigiCertGlobalRootCA.crt.

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 Client Server 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. Both tools are available for free to download from the Internet for all major operating systems.

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

Visa Developer creates the CSR file and submits the CSR to itself. The output of this process is the private key and the certificate of the client. 

Note: The auto generated CSR file is only available as an option in the Visa Developer sandbox when a project is created.

To auto-generate the CSR:

  1. On the dashboard, click on Create a New Project.
  2. Specify your Project Name and Project Description, then specify the APIs you are interested in using.
  3. Depending on the APIs you select, click on either Submit a Certificate Signing Request or Generate a CSR for Me.
    Visa Developer self-submits a certificate request and produces a .pem file with the private key of your certificate in it. This uses default values for Organization Name and Locality.
  4. Download the private key and store it in a secure location.
  5. In addition, you must download the ProjectCertificate and the Visa Developer Root Certificate (available in dashboard under Keys/APIs -> Certificates section).

Note: Once you complete the project creation process, Visa Developer Platform (VDP) will provide you with the links of the certificates to download. In this case, Visa Developer provides a VDP CSR. Once you obtain the private key and the certificates, you can begin to create the key stores and start testing mutual SSL connectivity.

The following steps include examples for context.

  1. Place your private key file (for example: privateKey.pem and your certificate file from VDP (for example: cert.pem in the same directory. Generate a keystore (for example: myProject_keyAndCertBundle.p12) file as shown below.

    > openssl pkcs12 -export -in cert.pem -inkey "privateKey.pem" -certfile cert.pem -out myProject_keyAndCertBundle.p12

    Note: The myProject_keyAndCertBundle.p12 is only a placeholder file name. You may choose to name it anything else.

  2. If you need a Java Key Store, run the following Java keytool command to convert your P12 file into a JKS file.

    > keytool -importkeystore -srckeystore myProject_keyAndCertBundle.p12 -srcstoretype PKCS12 -destkeystore myProject_keyAndCertBundle.jks

  3. Run the following Java keytool command to validate the contents of your new JKS file.

    > keytool -list -v -keystore myProject_keyAndCertBundle.jks

  4. Run the following command to add the root certificate to your JKS file.

    > keytool -import -alias ejbca -keystore myProject_keyAndCertBundle.jks -file VDPCA-SBX.pem -storepass <password>

Configuring Two-Way SSL Keystore Using Your Own CSR

Configuring Two-Way SSL Keystore with 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.

See below for a command-line utility, which is freely available for download from the Internet for all major operating systems.

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

    > openssl req -new -keyout privateKey.pem -out certreq.csr
    Generating a 2048 bit RSA private key

    Writing a new private key to ‘privatekey.pem’
    Enter PEM pass phrase: <your_password>
    Verifying – Enter PEM pass phrase: <re-enter your password>
    You are about to be asked to enter information that will be incorporated into your certificate request.
    What you are about to enter is what is called Distinguished Name or DN.
    For some fields there will be a default value.
    If you enter ‘.’, the field will be left blank
    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):<host name>
    Email Address []:<email address>
    Please enter the following 'extra' attributes to be sent with your certificate request A challenge password:.
    An optional company name:

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

    Country Name

    Two-digit International Standards Organization (ISO) 3166-1 country code. For example: US

    State Name

    Name of the state or province where the server is located. For example: California

    Locality Name

    A valid city name. For example: San Francisco

    Organization Name

    Name of your organization. For example: Bank of USA

    Organization Unit Name

    Name of the division within your organization. For example: Debit Card Processing Unit

    Common Name

    This field must contain a fully qualified domain name. Format should be alias/hostname.domainname.com. This must not contain any wildcard characters for the hostname. For example: services.visa.com

    CSR Unique Id (UID)

    Note: This is required for Certification or Production environment only

    The UID should be appended with one of the following values:

    • Certification environment: <UID>-CERT
    • Production environment: <UID>-PROD

    To get the CSR Unique Id, go to dashboard, select the Project Name for which you need to generate the CSR, and click on Settings.

  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.pemin 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 as shown below.

    > openssl pkcs12 -export -in cert.pem -inkey "privateKey.pem" -certfile cert.pem -out myProject_keyAndCertBundle.p12

    Note: The myProject_keyAndCertBundle.p12  file is only a placeholder file name. You may choose to name it anything you choose.
  2. View and validate the contents of your P12 certificate store by executing the following OpenSSL command.

    > openssl pkcs12 -info -in myProject_keyAndCertChainBundle.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. During the actual SSL handshake, the VDP sandbox does not validate the root certificate, so both JKS with the root cert and P12 without the root certificate will work equally well.

Configuring Two-Way SSL Keystore with Java Keytool

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

If you use a JKS file as your truststore, follow the instructions below to add the DigiCert Global Root CA certificate to your truststore.

  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. Then, run the following keytool command to add it your truststore

keytool -import -alias DigiCertGlobalCA -keystore <Path to JKS (TrustStore) file> -file DigiCertGlobalRootCA.crt

import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.ssl.SSLContexts;


import javax.net.ssl.SSLContext;
import java.io.File;
import java.io.IOException;
import java.security.KeyManagementException;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.UnrecoverableKeyException;

import java.security.cert.CertificateException;

….
private CloseableHttpClient createHttpClient() throws KeyManagementException, UnrecoverableKeyException, NoSuchAlgorithmException, KeyStoreException, CertificateException, IOException {


    return HttpClients.custom().setSSLSocketFactory(getSSLSocketFactory()).build();

}

private SSLConnectionSocketFactory getSSLSocketFactory() throws KeyManagementException, UnrecoverableKeyException, NoSuchAlgorithmException, KeyStoreException, CertificateException, IOException {

    SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(loadSSLContext(),

            new String[]{"TLSv1.2"}, null, SSLConnectionSocketFactory.getDefaultHostnameVerifier());

    return sslSocketFactory;
}

private SSLContext loadSSLContext() throws KeyManagementException, UnrecoverableKeyException,

        NoSuchAlgorithmException, KeyStoreException, CertificateException, IOException {

    SSLContext sslcontext = SSLContexts.custom()

            .loadKeyMaterial(new File(VisaProperties.getProperty(Property.KEYSTORE_PATH)),

                    VisaProperties.getProperty(Property.KEYSTORE_PASSWORD).toCharArray(),

                    VisaProperties.getProperty(Property.PRIVATE_KEY_PASSWORD).toCharArray())

            .loadTrustMaterial(new File(VisaProperties.getProperty(Property.TRUSTSTORE_PATH)),

                    VisaProperties.getProperty(Property.TRUSTSTORE_PASSWORD).toCharArray())

            .build();

    return sslcontext;
}

To generate a CSR using keytool:

  1. Generate a keystore file that contains public/private key pair (for example: 'clientkeystore.jks'), as shown below, using RSA, a keysize of 2048, and a password. Keytool manages everything through the Java Key Store (JKS).

    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>"

    Note: For all fields, only following ACSII characters are allowed.

    • Space Character
    • Upper case A to Z
    • Lower case a to z
    • Digits 0 to 9
    • Dash (-)

    Country Name

    Two-digit International Standards Organization (ISO) 3166-1 country code. For example: US

    State Name

    Name of the state or province where the server is located. For example: California

    Locality Name

    A valid city name. For example: San Francisco

    Organization Name

    Name of your organization. For example: Bank of USA

    Organization Unit Name

    Name of your division within your organization. For example: Debit Card Processing Unit

    Common Name

    This field must be a fully qualified domain name. Format should be alias/hostname.domainname.com. This cannot have wildcard characters for hostname. For example: services.visa.com

  2. Generate the Certificate Signing Request (for example: 'certreq.csr') file from your Java Key Store as shown below. Be sure to copy the User ID and Password because you will need these to invoke APIs with Two-Way SSL.

    keytool -certreq -alias client -keystore clientkeystore.jks -storepass <password> -keypass <password> -file certreq.csr

    You now have the Java Key Store file (which contains your private key) and the CSR file.
    Certificate (root CA) and the certificate (client cert) to a local folder. You should see both VDPCA.pem and cert.pem in your local folder.
  3. Update Java Key Store with Root Certificate and Client Certificate using Java Keytool.

    To invoke an API using Two-Way SSL, you must have a client certificate and your root CA in your keystore, since your Java SSL library only accepts one input for all certificates – the keystore. Therefore, you will need to add the certificates downloaded from VDP to the keystore (for example: clientkeystore.jks) that you generated while creating the CSR.

To add a project-specific certificate to the keystore:

  1. Add the VDP CA Root Public Certificate to the keystore:

    keytool -import -alias ejbca -keystore clientkeystore.jks -file VDPCA-Sandbox.pem -storepass <password>

    Note: Replace the < password > above with the actual password that was used while creating the clientkeystore.jks.
    Click yes when prompted to trust the certificate option.

  2. Add the project specific certificate to the keystore:

    keytool -import -alias client -keystore clientkeystore.jks -file cert.pem -storepass <password>

    The resulting file, called clientkeystore.jks will contain your private key, your client certificate and your VDP CA root certificate.

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 developer's 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

In order 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), as described in the Configuring 2-way SSL Keystore section.
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 as shown below:
    soap_1
  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.
    soap_2

Creating a Helloworld REST Project

Once in SOAPUI, click Project > New REST Project. Then, provide the following helloworld URI in the URI field:
https://sandbox.api.visa.com/vdp/helloworld
soap_3

Configuring the Helloworld API Request and Testing the Connection

  1. Fully expand the newly created REST project and double click Request 1 (this will automatically open when the project is created successfully)Select the Auth tab to add HTTP basic authorization. 
    soap_4
  2. Select authorization type as Basic and click OK.
    soap_5
  3. Provide Username and Password availability from VDP for your project. For the Pre-emptive Auth option select Authenticate pre-emptively.
    soap_6
  4. Click Submit Request (green chevron icon below) to test your connection. If successful, you should see the current timestamp in the response panel, as shown below.
    soap_7

Sample Code for Two-Way (Mutual) SSL

Copied to clipboard
import javax.net.ssl.SSLContext;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.ssl.SSLContexts;

// Load client certificate into key store
SSLContext sslcontext = SSLContexts.custom()
        .loadKeyMaterial(new File(KEY_STORE_PATH), KEY_STORE_PASSWORD.toCharArray(),
                PRIVATE_KEY_PASSWORD.toCharArray())
        .loadTrustMaterial(new File(KEY_STORE_PATH), KEY_STORE_PASSWORD.toCharArray())
        .build();

// Allow TLSv1.2 protocol only
SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(sslcontext, new String[] { "TLSv1.2" }, null,
        SSLConnectionSocketFactory.getDefaultHostnameVerifier());

CloseableHttpClient httpClient = HttpClients.custom()
            .setSSLSocketFactory(sslSocketFactory).build();