client-encryption-java

Table of Contents

• Overview
• Compatibility
• References
• Versioning and Deprecation Policy
• Usage
• Prerequisites
• Adding the Library to Your Project
• Selecting a JSON Engine
• Loading the Encryption Certificate
• Loading the Decryption Key
• Performing Payload Encryption and Decryption
  • Introduction
  • JWE Encryption and Decryption
  • Mastercard Encryption and Decryption
• Integrating with OpenAPI Generator API Client Libraries

Overview

Library for Mastercard API compliant payload encryption/decryption.

Compatibility

Java 11+

References

• JSON Web Encryption (JWE)
• Securing Sensitive Data Using Payload Encryption

Versioning and Deprecation Policy

• Mastercard Versioning and Deprecation Policy

Usage

Prerequisites

Before using this library, you will need to set up a project in the Mastercard Developers Portal.

As part of this set up, you'll receive: * A public request encryption certificate (aka Client Encryption Keys) * A private response decryption key (aka Mastercard Encryption Keys)

Adding the Library to Your Project

Maven

<dependency>
    <groupId>com.mastercard.developer</groupId>
    <artifactId>client-encryption</artifactId>
    <version>${client-encryption-version}</version>
</dependency>

Gradle

dependencies {
    implementation "com.mastercard.developer:client-encryption:$clientEncryptionVersion"
}   

Other Dependency Managers

See: https://search..org/artifact/com.mastercard.developer/client-encryption

Selecting a JSON Engine

This library requires one of the following dependencies to be added to your classpath:

• Jackson 2.5.0+
• Google Gson 2.3.1+
• Json-smart 2.5.2+
• Jettison 1.0+
• Org JSON 20070829+

You can either let the library choose for you, or force the one to be used by calling withJsonEngine on the JsonParser class. Example:

JsonParser.withJsonEngine(new JettisonJsonEngine());

Available engine classes: * GsonJsonEngine * JacksonJsonEngine * JettisonJsonEngine * JsonOrgJsonEngine * JsonSmartJsonEngine

Loading the Encryption Certificate

A Certificate object can be created from a file by calling EncryptionUtils.loadEncryptionCertificate:

Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate("<insert certificate file path>");

Supported certificate formats: PEM, DER.

Loading the Decryption Key

From a PKCS#12 Key Store

A PrivateKey object can be created from a PKCS#12 key store by calling EncryptionUtils.loadDecryptionKey the following way:

PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(
                                    "<insert PKCS#12 key file path>", 
                                    "<insert key alias>", 
                                    "<insert key password>");

From an Unencrypted Key File

A PrivateKey object can be created from an unencrypted key file by calling EncryptionUtils.loadDecryptionKey the following way:

PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey("<insert key file path>");

Supported RSA key formats: * PKCS#1 PEM (starts with "-----BEGIN RSA PRIVATE KEY-----") * PKCS#8 PEM (starts with "-----BEGIN PRIVATE KEY-----") * Binary DER-encoded PKCS#8

Performing Payload Encryption and Decryption

• Introduction
• JWE Encryption and Decryption
• Mastercard Encryption and Decryption

Introduction

This library supports two types of encryption/decryption, both of which support field level and entire payload encryption: JWE encryption and what the library refers to as Field Level Encryption (Mastercard encryption), a scheme used by many services hosted on Mastercard Developers before the library added support for JWE.

JWE Encryption and Decryption

• Introduction
• Configuring the JWE Encryption
• Performing JWE Encryption
• Performing JWE Decryption
• Encrypting Entire Payloads
• Decrypting Entire Payloads
• Encrypting Payloads with Wildcards
• Decrypting Payloads with Wildcards

• Introduction

This library uses JWE compact serialization for the encryption of sensitive data. The core methods responsible for payload encryption and decryption are encryptPayload and decryptPayload in the JweEncryption class.

• encryptPayload usage:

String encryptedRequestPayload = JweEncryption.encryptPayload(requestPayload, config);

• decryptPayload usage:

String responsePayload = JweEncryption.decryptPayload(encryptedResponsePayload, config);

• Configuring the JWE Encryption

Use the JweConfigBuilder to create JweConfig instances. Example:

JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withEncryptionPath("$.path.to.foo", "$.path.to.encryptedFoo")
    .withDecryptionPath("$.path.to.encryptedFoo.encryptedValue", "$.path.to.foo")
    .withEncryptedValueFieldName("encryptedValue")
    .withIVSize(16) // available values are 12 or 16. If not specified, default value is 16.
    .build();

• Performing JWE Encryption

Call JweEncryption.encryptPayload with a JSON request payload and a JweConfig instance.

Example using the configuration above:

String payload = "{" +
    "    \"path\": {" +
    "        \"to\": {" +
    "            \"foo\": {" +
    "                \"sensitiveField1\": \"sensitiveValue1\"," +
    "                \"sensitiveField2\": \"sensitiveValue2\"" +
    "            }" +
    "        }" +
    "    }" +
    "}";
String encryptedPayload = JweEncryption.encryptPayload(payload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));

Output:

{
    "path": {
        "to": {
            "encryptedFoo": {
                "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
            }
        }
    }
}

• Performing JWE Decryption

Call JweEncryption.decryptPayload with a JSON response payload and a JweConfig instance.

Example using the configuration above:

String encryptedPayload = "{" +
    "    \"path\": {" +
    "        \"to\": {" +
    "            \"encryptedFoo\": {" +
    "                \"encryptedValue\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"" +
    "            }" +
    "        }" +
    "    }" +
    "}";
String payload = JweEncryption.decryptPayload(encryptedPayload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output:

{
    "path": {
        "to": {
            "foo": {
                "sensitiveField1": "sensitiveValue1",
                "sensitiveField2": "sensitiveValue2"
            }
        }
    }
}

• Encrypting Entire Payloads

Entire payloads can be encrypted using the "$" operator as encryption path:

JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withEncryptionPath("$", "$")
    // …
    .build();

Example:

String payload = "{" +
    "    \"sensitiveField1\": \"sensitiveValue1\"," +
    "    \"sensitiveField2\": \"sensitiveValue2\"" +
    "}";
String encryptedPayload = JweEncryption.encryptPayload(payload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));

Output:

{
    "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
}

• Decrypting Entire Payloads

Entire payloads can be decrypted using the "$" operator as decryption path:

JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withDecryptionKey(decryptionKey)
    .withDecryptionPath("$.encryptedValue", "$")
    // …
    .build();

Example:

String encryptedPayload = "{" +
    "  \"encryptedValue\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"" +
    "}";
String payload = JweEncryption.decryptPayload(encryptedPayload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output:

{
    "sensitiveField1": "sensitiveValue1",
    "sensitiveField2": "sensitiveValue2"
}

• Encrypting Payloads with Wildcards

Wildcards can be encrypted using the "[*]" operator as part of encryption path:

JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withEncryptionPath("$.list[*]sensitiveField1", "$.list[*]encryptedField")
    // …
    .build();

Example:

String payload = "{ \"list\": [ " +
    "   { \"sensitiveField1\" : \"sensitiveValue1\"}, "+
    "   { \"sensitiveField1\" : \"sensitiveValue2\"} " +
    "]}";
String encryptedPayload = JweEncryption.encryptPayload(payload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));

Output:

{
  "list": [
    {"encryptedField": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"},
    {"encryptedField": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm"}
  ]
}

• Decrypting Payloads with Wildcards

Wildcards can be decrypted using the "[*]" operator as part of decryption path:

JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withDecryptionKey(decryptionKey)
    .withDecryptionPath("$.list[*]encryptedField", "$.list[*]sensitiveField1")
    // …
    .build();

Example:

String encryptedPayload = "{ \"list\": [ " +
        " { \"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"}, " +
        " { \"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm\"} " +
        " ]}";
String payload = JweEncryption.decryptPayload(encryptedPayload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output: ```json { "list": [ {"sensitiveField1": "sensitiveValue1"}, {"sensitiveField2": "sensi