# Encryption
source: https://developer.mastercard.com/mastercard-processing-core/documentation/api-basics-section/encryption/index.md

## Encryption {#encryption}

The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks.

The Mastercard Processing API also uses [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) to provide end-to-end payload encryption to secure sensitive data like Personally Identifiable Information (PII). You can manage your encryption keys using your [Developer Dashboard](https://developer.mastercard.com/dashboard).

To learn more, refer to our [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#overview) guides. We highly recommend using Mastercard client [encryption libraries](https://github.com/Mastercard?q=client-encryption) available in several popular programming languages.

For these, you will need a configuration object as follows (to be used at the [JWE -- Create encryption keys](https://developer.mastercard.com/mastercard-processing-core/tutorial/create-sandbox-apis/step6/index.md) step):
* Java
* C#

```java
// change these values accordingly
String clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#";
String mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#";
String mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#";
String mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#";

// This will be the certificate used to encrypt the payload before sending
Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath);

// The response received from the call will need to be decrypted using this key
PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(
        mastercardEncryptionKeyFilePath,
        mastercardEncryptionAlias,
        mastercardEncryptionPass);

// Prepare JweConfig 
JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
        .withEncryptionCertificate(encryptionCertificate)
        .withDecryptionKey(decryptionKey)
        .withEncryptionPath("$", "$")
        .withDecryptionPath("$.encryptedValue", "$")
        .withEncryptedValueFieldName("encryptedValue")
        .build();

```

```csharp
// change these values accordingly
var clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#";
var mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#";
var mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#";
var mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#";

// This will be the certificate used to encrypt the payload before sending
var encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath);

// The response received from the call will need to be decrypted using this key
var decryptionKey = EncryptionUtils.loadDecryptionKey(
        mastercardEncryptionKeyFilePath,
        mastercardEncryptionAlias,
        mastercardEncryptionPass);

// Prepare JweConfig 
var config = JweConfigBuilder.AJweEncryptionConfig()
        .WithEncryptionCertificate(encryptionCertificate)
        .WithDecryptionKey(decryptionKey)
        .WithEncryptionPath("$", "$")
        .WithDecryptionPath("$.encryptedValue", "$")
        .WithEncryptedValueFieldName("encryptedValue")
        .Build();
```

Tip: To learn how to build an API application with JWE, refer to the [Build and end-to-end application](https://developer.mastercard.com/mastercard-processing-core/tutorial/build-end-to-end-app/index.md) tutorial.

### PIN Block Encryption {#pin-block-encryption}

In addition to JWE, Mastercard Processing also provides PIN block encryption. The API does not allow PIN values to be sent in clear text. Instead, an encrypted PIN block must be sent using:

* A symmetrical Zone PIN Key (ZPK) which must be exchanged with a Mastercard Processing representative during the onboarding process.
* An asymmetric RSA public key should be received through the `GET` request sent to the `/public-keys` endpoint. Usually, we configure multiple public keys which are rotated at regular and short interval like 15 minutes. Hence, the RSA public key should be fetched just before applying the PIN block encryption.

Tip: To learn how to build and encrypt the PIN block, refer to the [PIN block formation and encryption process](https://developer.mastercard.com/mastercard-processing-core/tutorial/pin-encryption-process/index.md) and the [PIN display process](https://developer.mastercard.com/mastercard-processing-core/tutorial/pin-display-process/index.md) tutorials.

### Encryption Keys Exchange with Mastercard Processing {#encryption-keys-exchange-with-mastercard-processing}

During onboarding configuration, the ZPK must be exchanged with Mastercard Processing so it can be used to encrypt the PIN block for the `setPIN` or `verifyPIN` operations.

The following steps describe the process for key exchange.

1. Register your two security officers with the Mastercard Key Management Services (KMS) department.
2. Mastercard Processing (MP) initiates a key exchange with KMS, specifying which key should be generated and to whom it should be sent.
3. KMS generates transport key components (assuming this is the first key exchange between KMS and you) and sends them to previously registered security officers on your side.
4. You confirm receipt of the components and validity through the key check value.
5. KMS generates ZPK and sends its cryptogram under the transport key to you.
6. KMS shares the same ZPK with Mastercard Processing.

If you need to rotate the key or revoke the previous key and issue a new one, the steps above apply to the new key generation.

Mastercard Processing and the personalization bureau generate public and private Pretty Good Privacy (PGP) keys during onboarding configuration. They exchange the public keys to securely exchange files during the physical card [personalization process](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/issuing-card/index.md#personalization-process) through dedicated SFTP.