# Securing Sensitive Data Using Payload Encryption source: https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md ###### Reading Time: *15 minutes* ## Overview {#overview} The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data are encrypted *by default* when transmitted across networks. In addition to that, some of our services implement end-to-end payload encryption. For instance, services dealing with sensitive data like cardholder Personally Identifying Information (PII) must comply with the Payment Card Industry [Data Security Standard](https://www.pcisecuritystandards.org/documents/PCI_DSS_v3-2-1.pdf) (PCI DSS), and to the requirement of "*encrypting transmission of cardholder data across open, public networks*". > *Sensitive information must be encrypted during transmission over networks that are easily accessed by malicious individuals. Misconfigured wireless networks and vulnerabilities in legacy encryption and authentication protocols continue to be targets of malicious individuals who exploit these vulnerabilities to gain privileged access to cardholder data environments. **(Page 47, Requirement #4, PCI DSS Version 3.2.1 May 2018)*** Diagram simple-payload-encryption-diagram In the next sections, you will learn the [encryption scheme](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#overall-encryption-scheme) Mastercard uses and how to [set up encryption keys](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#getting-keys-for-your-application) for your project. You will also find links to our encryption [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#client-libraries), some [development tips](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#development-tips) and answers to [frequently asked questions](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#frequently-asked-questions). Tip: Want to see some code? Browse our client library projects on [GitHub](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#client-libraries). ## Overall Encryption Scheme {#overall-encryption-scheme} Sensitive data sent in requests are encrypted by your application for Mastercard, and sensitive data returned in responses are encrypted by Mastercard for your application. The image below shows an overview of the various elements of encryption, the flow between each of the modules and the supported encryption formats. ![Encryption Scheme](https://static.developer.mastercard.com/content/platform/img/encryption-base.png) ### The Encryption Keys {#the-encryption-keys} #### RSA {#rsa} Encryption involves 2048-bit [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) public/private key pairs. Data encrypted using a public key can only be decrypted using the corresponding private key. Both client application and service own a key pair, which allows to encrypt both request *and* response payloads. Your own key pair is generated by you (or your web browser) and the public key is certified by Mastercard. See also: [Getting Keys for Your Application](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#getting-keys-for-your-application). *** ** * ** *** #### AES {#aes} For performance reasons, RSA asymmetric encryption is combined with [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric encryption. For that, one-time usage 128 or 256-bit AES session keys are generated and encrypted using the RSA public key. The encrypted (or *wrapped*) key is sent in the payload along with the encrypted data. *** ** * ** *** ### The Encryption Process {#the-encryption-process} Here are the steps for sending an encrypted payload: 1. An AES session key is generated along with some encryption parameters 2. Sensitive data are encrypted using the AES key 3. The AES key is encrypted using the recipient's RSA public key 4. The payload is sent with the encrypted session key and parameters ### The Decryption Process {#the-decryption-process} Here are the steps for decrypting a payload: 1. The AES session key is decrypted using the recipient's RSA private key 2. Sensitive data are decrypted using the AES key *** ** * ** *** ### Encryption Parts {#encryption-parts} The encryption scheme involves an initialization vector, an encrypted or wrapped key, an encrypted value, a public key fingerprint and a digest algorithm #### Initialization Vector {#initialization-vector} An [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector) for the encryption of sensitive data *** ** * ** *** #### Encrypted Key {#encrypted-key} The symmetric AES session key encrypted with the recipient's RSA public key. *** ** * ** *** #### Encrypted Value {#encrypted-value} The sensitive JSON payload (or a child element) encrypted using the AES session key and the initialization vector (see above). *** ** * ** *** #### Public Key Fingerprint {#public-key-fingerprint} The hex-encoded SHA-256 digest of the recipient's RSA public key used for encryption, which serves as an identifier for the key. *** ** * ** *** #### OAEP Padding Digest Algorithm {#oaep-padding-digest-algorithm} The digest algorithm used with the RSA-OAEP scheme. Must be one of SHA256 or SHA512. *** ** * ** *** Tip: Mastercard services utilize two different methods of encryption, [JWE Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#jwe-encryption) and [Mastercard Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/index.md#mastercard-encryption). The method of encryption used by each respective service will be outlined in the service's documentation. Please refer to the next sections for an overview of each method and what their respective encrypted payloads look like. ## JWE Encryption {#jwe-encryption} ### Overview {#overview-1} JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures [RFC7159](https://tools.ietf.org/html/rfc7159) and base64url encoding. Mastercard uses [JWE compact serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.1) for the encryption of sensitive data and supports both field level encryption and entire payload encryption. Mastercard uses JWE with AES in both [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher_Block_Chaining_(CBC)) (Cipher Block Chaining) and [GCM](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Galois/counter_(GCM)) (Galois/Counter Mode) modes with [PKCS#7 padding](https://tools.ietf.org/html/rfc5652#section-6.3) and RSA with [OAEP](https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding) (Optimal Asymmetric Encryption Padding). ![Encryption Jwe](https://static.developer.mastercard.com/content/platform/img/encryption-jwe.png) ### Breaking the Encrypted Payload Down {#breaking-the-encrypted-payload-down} Here is an example of JSON payload to be entirely encrypted: ```json { "firstName": "Helena", "lastName": "Milner", "paymentCard": { "pan": "5500000000000004", "expiryYear": "2022", "expiryMonth": "12" } } ``` And here is an encrypted version of it: ```json { "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM(...)==.Y+oPYKZEMTKyYcSIVEgtQw==" } ``` Here is another example of JSON payload, with this time only one child element to be encrypted ("*Field Level Encryption*"): ```json { "action": "ORDER", "actionId": "91c693c6-4022-4341-ac6a-27c82f599fd8", "paymentCard": { "pan": "5500-0000-0000-0004", "expiry": "12/22" } } ``` And here is an encrypted version of it: ```json { "action": "ORDER", "actionId": "91c693c6-4022-4341-ac6a-27c82f599fd8", "encryptedPaymentCard": { "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM(...)==.Y+oPYKZEMTKyYcSIVEgtQw==" } } ``` #### encryptedValue {#encryptedvalue} `encryptedValue` is represented as the concatenation of the Base64 encoded JWE Protected Header, JWE Encrypted Key, JWE Initialization Vector, JWE Ciphertext, and JWE Authentication Tag separated by `.` BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag) *** ** * ** *** ## Mastercard Encryption {#mastercard-encryption} ### Overview {#overview-2} Mastercard encryption is a custom way of representing encrypted content in JSON format which supports both field level encryption and entire payload encryption. Mastercard encryption uses AES in [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher_Block_Chaining_(CBC)) (Cipher Block Chaining) mode with [PKCS#7 padding](https://tools.ietf.org/html/rfc5652#section-6.3) and RSA with [OAEP](https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding) (Optimal Asymmetric Encryption Padding). ![Encryption AES](https://static.developer.mastercard.com/content/platform/img/encryption-mastercard.png) ### Breaking the Encrypted Payload Down {#breaking-the-encrypted-payload-down-1} Here is an example of JSON payload to be entirely encrypted: ```json { "firstName": "Helena", "lastName": "Milner", "paymentCard": { "pan": "5500000000000004", "expiryYear": "2022", "expiryMonth": "12" } } ``` And here is an encrypted version of it: ```json { "iv": "1b9396c98ab2bfd195de661d70905a45", "encryptedKey": "7d5112fa08e554e3dbc455d0628(...)52e826dd10311cf0d63bbfb231a1a63ecc13", "encryptedValue": "e5e9340f4d2618d27f8955828c86(...)379b13901a3b1e2efed616b6750a90fd379515", "publicKeyFingerprint": "80810fc13a8319fcf0e2e(...)82cc3ce671176343cfe8160c2279", "oaepPaddingDigestAlgorithm": "SHA512" } ``` Here is another example of JSON payload, with this time only one child element to be encrypted ("*Field Level Encryption*"): ```json { "action": "ORDER", "actionId": "91c693c6-4022-4341-ac6a-27c82f599fd8", "paymentCard": { "pan": "5500-0000-0000-0004", "expiry": "12/22" } } ``` And here is an encrypted version of it: ```json { "action": "ORDER", "actionId": "91c693c6-4022-4341-ac6a-27c82f599fd8", "encryptedPaymentCard": { "iv": "7f1105fb0c684864a189fb3709ce3d28", "encryptedKey": "67f467d1b653d98411a0c6d3c(...)ffd4c09dd42f713a51bff2b48f937c8", "encryptedValue": "b73aabd267517fc09ed72455c2(...)dffb5fa04bf6e6ce9ade1ff514ed6141", "publicKeyFingerprint": "80810fc13a8319fcf0e2e(...)82cc3ce671176343cfe8160c2279", "oaepPaddingDigestAlgorithm": "SHA512" } } ``` ## Getting Keys for Your Application {#getting-keys-for-your-application} As seen above, payload encryption involves two RSA key pairs. Encryption keys for your projects are set up through your [Developer Dashboard](https://developer.mastercard.com/dashboard) and you can manage the keys' lifecycle from there. ### Key Pairs {#key-pairs} The public key your application uses to encrypt requests is listed under *Client Encryption Keys*: ![client-encryption-key-example](https://static.developer.mastercard.com/content/platform/img/20240110-client-encryption-keys.png) The public key Mastercard uses to encrypt responses is listed under *Mastercard Encryption Keys*: ![mastercard-encryption-key-example](https://static.developer.mastercard.com/content/platform/img/20240110-mastercard-encryption-keys.png) ### Keys and Environments {#keys-and-environments} There are two different types of keys, depending on the stage of your project: 1. Sandbox keys, to be used with an API sandbox that mimics a live production environment (*sandbox.api.mastercard.com*) 2. Production keys, which allow an application to encrypt/decrypt content in the production environment (*api.mastercard.com*) A pre-production environment called MTF (for "*Mastercard Test Facility*") can possibly be made available. In the following picture, MTF is using sandbox keys: ![encryption-key-usage-by-environment](https://static.developer.mastercard.com/content/platform/img/environment-encryption-keys.png) ### Creating Keys {#creating-keys} To add encryption keys to an existing project, click "*Add Key*" next to the service name you would like to add keys to and select the key type you want to add: ![select-key-type](https://static.developer.mastercard.com/content/platform/img/20240201-add-encryption-keys.png)
Two methods are available when creating a *Mastercard Encryption Key*: #### Method 1 {#method-1} * A key pair and a [certificate signing request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request) are generated inside your web browser * Mastercard signs and sends your browser back an [X509 certificate](https://en.wikipedia.org/wiki/X.509) matching your private key * Your browser generates a [PKCS#12](https://en.wikipedia.org/wiki/PKCS_12) key store file securing your private key with the provided passphrase ![create-key-browser](https://static.developer.mastercard.com/content/platform/img/20240110-create-key-in-browser.png) #### Method 2 {#method-2} * You manually upload a [certificate signing request (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request) generated in your own system * Mastercard issues an [X509 certificate](https://en.wikipedia.org/wiki/X.509) matching your private key (you can request this certificate to be sent to you through the "Support" section) ![create-key-from-csr](https://static.developer.mastercard.com/content/platform/img/20240110-create-key-from-csr.png) Warning: Mastercard doesn't know and never stores your private keys. It means *only you* can decrypt responses sent to your application, but it also means there is no way to recover a key you lost! ## Client Libraries {#client-libraries} Mastercard provides [client encryption libraries](https://github.com/Mastercard?q=client-encryption) in several languages you can integrate to your project or use as reference implementations: | | ![Java](https://static.developer.mastercard.com/content/platform/img/java.svg) | ![C#](https://static.developer.mastercard.com/content/platform/img/csharp.svg) | ![Python](https://static.developer.mastercard.com/content/platform/img/python.svg) | ![NodeJS](https://static.developer.mastercard.com/content/platform/img/nodejs.svg) | ![Go](https://static.developer.mastercard.com/content/platform/img/go.svg) | | | |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---| | **Download/install** | [![java-version](https://img.shields.io/maven-central/v/com.mastercard.developer/client-encryption.svg?style=flat&color=f99f1c&label=)](https://search.maven.org/artifact/com.mastercard.developer/client-encryption/) | [![c-sharp-version](https://img.shields.io/nuget/v/Mastercard.Developer.ClientEncryption.Core.svg?style=flat&color=f99f1c&label=)](https://www.nuget.org/packages/Mastercard.Developer.ClientEncryption.RestSharpV2/) | [![python-version](https://img.shields.io/pypi/v/mastercard-client-encryption.svg?style=flat&color=f99f1c&label=)](https://pypi.org/project/mastercard-client-encryption/) | [![node-js-version](https://img.shields.io/npm/v/mastercard-client-encryption.svg?style=flat&color=f99f1c&label=)](https://www.npmjs.com/package/mastercard-client-encryption) | [![go-version](https://img.shields.io/github/v/release/mastercard/client-encryption-go.svg?style=flat&color=f99f1c&label=)](https://github.com/Mastercard/client-encryption-go) | | | | **View on GitHub** | [![java-github-badge](https://img.shields.io/github/stars/mastercard/client-encryption-java.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-java) | [![c-sharp-github-badge](https://img.shields.io/github/stars/mastercard/client-encryption-csharp.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-csharp) | [![python-github-badge](https://img.shields.io/github/stars/mastercard/client-encryption-python.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-python) | [![node-js-github-badge](https://img.shields.io/github/stars/mastercard/client-encryption-nodejs.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-nodejs) | [![go-github-badge](https://img.shields.io/github/stars/mastercard/client-encryption-go.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-go) | | | To get started, simply add to your project the package matching your application development language. You can also refer to the different [README.md](https://github.com/Mastercard/client-encryption-csharp/blob/master/README.md) files for detailed how-to information. Tip: We strongly encourage you to use existing libraries rather than implementing the encryption and decryption steps yourself. ## Insomnia Plugin {#insomnia-plugin} While integrating with Mastercard APIs, you can also try our plugin for [Insomnia](https://insomnia.rest/). Click the links below to browse the project. | | ![Insomnia](https://static.developer.mastercard.com/content/platform/img/insomnia.svg) | | | | | | | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|---| | **Download/install** | [![insomnia-version](https://img.shields.io/npm/v/insomnia-plugin-mastercard.svg?style=flat&color=f99f1c&label=)](https://www.npmjs.com/package/insomnia-plugin-mastercard) | ![blank-image](https://static.developer.mastercard.com/content/platform/img/blank.png) | ![blank-image](https://static.developer.mastercard.com/content/platform/img/blank.png) | ![blank-image](https://static.developer.mastercard.com/content/platform/img/blank.png) | ![blank-image](https://static.developer.mastercard.com/content/platform/img/blank.png) | ![blank-image](https://static.developer.mastercard.com/content/platform/img/blank.png) | | | **View on GitHub** | [![insomnia-github-badge](https://img.shields.io/github/stars/mastercard/insomnia-plugin-mastercard.svg?label=&style=social)](https://github.com/Mastercard/insomnia-plugin-mastercard) | | | | | | | ## Development Tips {#development-tips} ### Extracting the Encryption Key {#extracting-the-encryption-key} The public request encryption key is provided through a PEM certificate file (`BEGIN CERTIFICATE`). To export it to a PKCS#8 PEM key file (`BEGIN PUBLIC KEY`), run: ```bash openssl x509 -pubkey -noout -in cert.pem > key.pem ``` ### Exporting Your Decryption Key {#exporting-your-decryption-key} Your private response decryption key is encrypted in a PKCS#12 password-protected file you can directly use with Mastercard client libraries. To export RSA keys to alternative formats, you can run the same commands as for [Exporting Your Signing Key](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/index.md#exporting-your-signing-key). Warning: Always keep your private signing keys safe, in a password-protected or hardware key store! ## Frequently Asked Questions {#frequently-asked-questions} No questions yet. ## Further Reading {#further-reading} * [Protecting the payments ecosystem](https://www.mastercard.com/sdp) * [PCI DSS v3.2.1](https://www.pcisecuritystandards.org/documents/PCI_DSS_v3-2-1.pdf)