# Using MTLS to access Cross-Border Services API
source: https://developer.mastercard.com/cross-border-services/documentation/api-basics/oauth2-mtls-setup/index.md

### Overview: {#overview}

MTLS authentication require two-way TLS certificate exchange between the API client and Mastercard Server.
The [Transport Layer Security (TLS) Protocol Version 1.2](https://datatracker.ietf.org/doc/html/rfc5246) describes the mutual TLS handshake protocol to establish a secure connection between client and server.
Note:   

* The below provided steps are for MTLS certificate exchange exclusively for connecting to the Mastercard Cross-Border APIs(Inbound).
* The MTLS certificate exchange procedure for Push notification(outbound) is handled separately.

### Step 1: Obtain access to Key Management Portal {#step-1-obtain-access-to-key-management-portal}

The Key Management Portal (KMP) is an application available in [Mastercard Connect](https://mastercardconnect.com) as a self-service portal for Mastercard customers, which allows them to request and exchange keys and certificates with Mastercard.
The portal provides guided workflows to create and manage requests for key and certificate exchange, as well as an inventory of all PKI for Business Partners keys and certificates that have been exchanged between you and Mastercard using KMP.

##### Pre-Requisite: {#pre-requisite}

To access KMP, you must be signed up to [Mastercard Connect](https://mastercardconnect.com). Please contact your Mastercard representative to get help with Mastercard Connect Signup.

##### How to request access to KMP: {#how-to-request-access-to-kmp}

* Sign in to [Mastercard Connect](https://mastercardconnect.com).
* Click Store in the top menu.
* Search for Key Management Portal. You can also select Administration under Business capabilities to narrow down the results. ![kmp-tile](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_01.png)
* On the Key Management Portal card, select Request.
* Select Security Officer Level 1 access.
* Click Request access.

### Step 2: Ensure complete setup in KMP {#step-2-ensure-complete-setup-in-kmp}

* Your company must have at least 2 active Security Officers on the Key Management Portal to be permitted to create new requests in KMP. If you see the following message when logging into KMP then your company needs to have at least 1 additional Security Officer registered on the Key Management Portal application in Mastercard Connect.

![security-officer-required](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_40.png)

* Furthermore, if not already done, a Certificate Management Group email must be added to your company profile.

##### How to add a Certificate Management Group email {#how-to-add-a-certificate-management-group-email}

Your Certificate Management Group email is an alternative means of communication which the Mastercard
Key Management Delivery team will use for crucial communication with your organization and in case there
is no longer an active user on the Key Management Portal. Follow below steps to add a Certificate Management Group email:

1. Click **My Company**
   ![my-company](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_03.png)

2. Click on the pencil icon next to Certificate Management Group Email
   ![edit-group-email](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_04.png)

3. Enter your Certificate Management Group email and click Save
   ![save-grou-email](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_05.png)

### Step 3: Generate CSR {#step-3-generate-csr}

There are multiple tools that you can use to create a CSR, such as Java keytool, OpenSSL etc. Here, we will be using OpenSSL's req utility to generate both the private key and CSR in one command. Generating the private key in this way will ensure that you will be prompted for a pass phrase to protect the private key.

The OpenSSL command below will generate a 2048-bit RSA private key and CSR:

```OpenSSL_Command
openssl req -newkey rsa:2048 -keyout PRIVATEKEY.key -out MYCSR.csr
```

where

```Where

 * openssl is the command for running OpenSSL.
 * req is the OpenSSL utility for generating a CSR.
 * -newkey rsa:2048 tells OpenSSL to generate a new 2048-bit RSA private key. If you would prefer a 4096-bit key, you can change this number to 
4096.
 * -keyout PRIVATEKEY.key specifies where to save the private key file.
 * -out MYCSR.csr specifies where to save the CSR file.

Note: Replace the filenames shown in ALL CAPS with the actual paths and filenames you want to use.
```

After typing the command, press enter and you will be presented with a series of prompts:

First create and verify a pass phrase. Remember this pass phrase because you will need it again to access your private key.

* You will now be prompted to enter the information which will be included into your CSR. This information is also known as the Distinguished Name, or DN. \*The Common Name field is required, when submitting your CSR, but the others are optional. (If you would like to skip an optional item, simply type enter when it appears)
* The Country Name takes a two-letter country code.
* The Locality Name field is for your city or town.
* The Organization Name field is for the name of your company or organization.
* The Organizational Unit Name (eg, section):\<department/section name\>
* The Common Name field is used for the Fully Qualified Domain Name (FQDN) of the website this certificate will protect. Please use "MTF XBS" for MTF environment and "PROD XBS" for Prod environment.
* Email Address

Upon completion of this process, you will be returned to the command prompt.
The newly created CSR file can be found within the specified folder in the OpenSSL command.
Please ensure to store the generated private key securely for future use.

For your reference, here's a sample CSR (represented as a Base64 encoded):

```Sample_CSR

----BEGIN CERTIFICATE REQUEST-----
MIICzDCCAbQCAQAwgYYxCzAJBgsdfsdNVBAYTAkVOMQ0wCwYDVQQIDARub25lMQ0wCwYD
VQQHDARub25lMRIwEAYDVQsdfQKDAlXaWtpcGVkaWExDTALBgNVBAsMBG5vbmUxGDAW
BgNVBAMMDyoud2lraXBlZGlhLm9yZzEcMBoGCSqGSIb3DQEJARYNbm9uZUBub25l
LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMP/U8RlcCD6E8AL
PT8LLUR9ygyygPCaSmIEC8zsdfXsdfGJung3ykElXFRz/Jc/bu0hxCxi2YDz5IjxBBOpB/
kieG83HsSmZZtR+drZIQ6vsdfOsr/ucvpnB9z4XzKuabNGZ5ZiTSQ9L7Mx8FzvUTq5y
/ArIuM+FBeuno/IV8zvwAe/sdfVRa8i0QjFXT9vBBp35aeatdnJ2ds50yKCsHHcjvtr
9/8zPVqqmhl2XFS3Qdqlsprzsdfbgksom67OobJGjaV+fNHNQ0o/rzP//Pl3i7vvaEG
7Ff8tQhEwR9nJUR1T6Z7ln7S6cOr23YozgWVkEJ/dSr6LAopb+cZ88FzW5NszU6i
57HhA7ECAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4IBAQBn8OCVOIx+n0AS6WbEmYDR
SspR9xOCoOwYfamB+2sdfBpmtsdf82R01zJ/kaqzUtZUjaGvQvAaz5lUwoMdaO0X7I5Xfl
sllMFDaYoGD4Rru4s8gz2qG/QHWA8uPXzJVAj6X0olbIdLTEqTKsnBj4Zr1AJCNy
/YcG4ouLJr140o26MhsdfwBpoCsdfRpPjAgdYMH60BYfnc4/DILxMVqR9xqK1s98d6Ob/+
3wHFK+S7BRWrJQXcsdfM8veAexXuk9lHQ+FgGfD0eSYGz0kyP26Qa2pLTwumjt+nBPl
rfJxaLHwTQ/1988G0Hsdf35ED0sdff9Md5fzoKi5evU1wG5WRxdEUPyt3QUXxdQ69i0C+7
----END CERTIFICATE REQUEST-----
```

### Step 4: Request certificate in KMP using CSR {#step-4-request-certificate-in-kmp-using-csr}

To request certificate in KMP using your CSR, please follow the below steps:

1. Sign in to [Mastercard Connect](https://mastercardconnect.com).
2. Click My Items. ![kmp-tile](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_02.png)
3. Click on the Key Management Portal card to Open it.
4. To get registered, see Registration and Access to the Key Management Portal.
5. Furthermore, a Certificate Management Group email must be added to your company profile, see Adding your Certificate Management Group email.
6. On the Certificates page or on the Certificate Requests page, click Start New Request.
7. Select Crossborder Services API-MTLS Application.
8. Select the Request Type, Environment, Certificate Profile and Mastercard Project Contact email, if prompted. The email must have the @mastercard.com domain. ![cert-request-form](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/reqcertkmp.png)
9. The DN Requirements appear to indicate you must adhere to the DN requirements in your CSR.
10. Upload your CSR file generated and click Next. ![upload-csr-file](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/csr.png)
11. Review the CSR values to ensure they adhere to the DN requirements. ![review-csr-values](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_18.png)
12. Enter Subject Alternate Names (SAN) if necessary (domain names need to be comma-separated) and Click Submit.

At this stage, the Mastercard's Key management Security officer will receive the request. Once your certificate has been approved, you will get an email notification that the certification has been approved and then you may proceed to download the signed certificate from KMP.

### Step 5: Download the certificate from KMP {#step-5-download-the-certificate-from-kmp}

Once you receive the approval on your certificate generation request, you need to go to KMP to download the certificate.

##### How to download certificate on KMP: {#how-to-download-certificate-on-kmp}

1. Login to KMP
2. On the Detail screen, click Actions, then Download. ![download-button](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_11.png)
3. If you're downloading a certificate or a CA Chain, select a Format from list. ![choose-format](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_12.png)
4. Select the preferred ordering of Root CA (unless you select the DER format in which case the Root Chain cannot be included). ![choose-chain-order](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/kmp_13.png)
5. Click Download.

Now, the downloaded file will be saved in the default download folder of your browser.

Following are the several different outcomes that may be observed:  

1. For any certificate or CA chain being downloaded in the PEM (PKCS #8), PEM (Open SSL) or PKCS #7 format, the root chain is always included in the downloaded file containing the certificate and chaining:  
   i) For PEM (PKCS #8), PEM (Open SSL), the downloaded file is a .pem file   
   ii) For PKCS #7, the downloaded file is a .p7b file  
2. Where the user is downloading a certificate for an application which requires mutual authentication, an extra CA Chain is delivered along with the certificate chaining inside a zip file
3. Where the DER format was selected, only the end entity certificate is provided in a .cer file, the CA chain (Sub and Root CA) is not included.

### Step 6: Create trust store for the downloaded certificate and private key {#step-6-create-trust-store-for-the-downloaded-certificate-and-private-key}

For your convenience, here's a sample on creating trust store using Open SSL command:

```OpenSSL

 openssl pkcs12 -export -out cert.p12 -in cert.pem -inkey key.pem -passin pass:root -passout pass:root
    
```

where

        pkcs12: This option combines a PEM certificate file and a private key to PKCS#12 file format
        export: This option exports the file 
        out: It creates an output file as cert.p12, this name can be anything but the extension must be .p12
        in: It takes an input file, this is a pem file which you get from the above steps
        inkey: This is the private key file which was obtained from above steps
        passin: pass phrase source to decrypt any input private keys with
        passout: pass phrase source to encrypt any output private keys with

You will need the above .p12 file to connect to Cross-Border Services APIs.

### Step 7: Trust Mastercard's certificate {#step-7-trust-mastercards-certificate}

To obtain Mastercard's certificate, please contact your Mastercard representative to create a new request on your behalf.
Once available, add the certificate to your trust store.
Note: Well Done! 👏. You have successfully completed the MTLS setup required to connect to the Mastercard Cross-Border Services API.