client-encryption-java

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-light.svg"> <img src="https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-dark.svg" alt="mastercard developers logo"> </picture>

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 <a name="overview"></a>

Library for Mastercard API compliant payload encryption/decryption.

Compatibility <a name="compatibility"></a>

Java 11+

References <a name="references"></a>

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

Versioning and Deprecation Policy <a name="versioning"></a>

• Mastercard Versioning and Deprecation Policy

Usage <a name="usage"></a>

Prerequisites <a name="prerequisites"></a>

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 <a name="adding-the-library-to-your-project"></a>

Maven

xmlCopy
<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 <a name="selecting-a-json-engine"></a>

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:

javaCopy
JsonParser.withJsonEngine(new JettisonJsonEngine());

Available engine classes:

• GsonJsonEngine
• JacksonJsonEngine
• JettisonJsonEngine
• JsonOrgJsonEngine
• JsonSmartJsonEngine

Loading the Encryption Certificate <a name="loading-the-encryption-certificate"></a>

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

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

Supported certificate formats: PEM, DER.

Loading the Decryption Key <a name="loading-the-decryption-key"></a>

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:

javaCopy
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:

javaCopy
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 <a name="performing-payload-encryption-and-decryption"></a>

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

Introduction <a name="introduction"></a>

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 <a name="jwe-encryption-and-decryption"></a>

• 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 <a name="jwe-introduction"></a>

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:

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

• decryptPayload usage:

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

• Configuring the JWE Encryption <a name="configuring-the-jwe-encryption"></a>

Use the JweConfigBuilder to create JweConfig instances. Example:

javaCopy
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 <a name="performing-jwe-encryption"></a>

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

Example using the configuration above:

javaCopy
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:

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

• Performing JWE Decryption <a name="performing-jwe-decryption"></a>

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

Example using the configuration above:

javaCopy
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:

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

• Encrypting Entire Payloads <a name="encrypting-entire-payloads-jwe"></a>

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

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

Example:

javaCopy
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:

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

• Decrypting Entire Payloads <a name="decrypting-entire-payloads-jwe"></a>

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

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

Example:

javaCopy
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:

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

• Encrypting Payloads with Wildcards <a name="encrypting-wildcard-payloads-jwe"></a>

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

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

Example:

javaCopy
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:

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

• Decrypting Payloads with Wildcards <a name="decrypting-wildcard-payloads-jwe"></a>

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

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

Example:

javaCopy
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:

jsonCopy
{
  "list": [
    {"sensitiveField1": "sensitiveValue1"},
    {"sensitiveField2": "sensitiveValue2"}
  ]
}

Mastercard Encryption and Decryption <a name="mastercard-encryption-and-decryption"></a>

• Introduction
• Configuring the Mastercard Encryption
• Performing Mastercard Encryption
• Performing Mastercard Decryption
• Encrypting Entire Payloads
• Decrypting Entire Payloads
• Encrypting Payloads with Wildcards
• Decrypting Payloads with Wildcards
• Using HTTP Headers for Encryption Params

• Introduction <a name="mastercard-introduction"></a>

The core methods responsible for payload encryption and decryption are encryptPayload and decryptPayload in the FieldLevelEncryption class.

• encryptPayload usage:

javaCopy
String encryptedRequestPayload = FieldLevelEncryption.encryptPayload(requestPayload, config);

• decryptPayload usage:

javaCopy
String responsePayload = FieldLevelEncryption.decryptPayload(encryptedResponsePayload, config);

• Configuring the Mastercard Encryption <a name="configuring-the-mastercard-encryption"></a>

Use the FieldLevelEncryptionConfigBuilder to create FieldLevelEncryptionConfig instances. Example:

javaCopy
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withEncryptionPath("$.path.to.foo", "$.path.to.encryptedFoo")
    .withDecryptionPath("$.path.to.encryptedFoo", "$.path.to.foo")
    .withOaepPaddingDigestAlgorithm("SHA-256")
    .withEncryptedValueFieldName("encryptedValue")
    .withEncryptedKeyFieldName("encryptedKey")
    .withIvFieldName("iv")
    .withFieldValueEncoding(FieldValueEncoding.HEX)
    .build();

See also:

• FieldLevelEncryptionConfig.java for all config options

• Performing Mastercard Encryption <a name="performing-mastercard-encryption"></a>

Call FieldLevelEncryption.encryptPayload with a JSON request payload and a FieldLevelEncryptionConfig instance.

Example using the configuration above:

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

Output:

jsonCopy
{
    "path": {
        "to": {
            "encryptedFoo": {
                "iv": "7f1105fb0c684864a189fb3709ce3d28",
                "encryptedKey": "67f467d1b653d98411a0c6d3c…ffd4c09dd42f713a51bff2b48f937c8",
                "encryptedValue": "b73aabd267517fc09ed72455c2…dffb5fa04bf6e6ce9ade1ff514ed6141"
            }
        }
    }
}

• Performing Mastercard Decryption <a name="performing-mastercard-decryption"></a>

Call FieldLevelEncryption.decryptPayload with a JSON response payload and a FieldLevelEncryptionConfig instance.

Example using the configuration above:

javaCopy
String encryptedPayload = "{" +
    "    \"path\": {" +
    "        \"to\": {" +
    "            \"encryptedFoo\": {" +
    "                \"iv\": \"e5d313c056c411170bf07ac82ede78c9\"," +
    "                \"encryptedKey\": \"e3a56746c0f9109d18b3a2652b76…f16d8afeff36b2479652f5c24ae7bd\"," +
    "                \"encryptedValue\": \"809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f\"" +
    "            }" +
    "        }" +
    "    }" +
    "}";
String payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output:

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

• Encrypting Entire Payloads <a name="encrypting-entire-mastercard-payloads"></a>

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

javaCopy
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withEncryptionPath("$", "$")
    // …
    .build();

Example:

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

Output:

jsonCopy
{
    "iv": "1b9396c98ab2bfd195de661d70905a45",
    "encryptedKey": "7d5112fa08e554e3dbc455d0628…52e826dd10311cf0d63bbfb231a1a63ecc13",
    "encryptedValue": "e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515"
}

• Decrypting Entire Payloads <a name="decrypting-entire-mastercard-payloads"></a>

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

javaCopy
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withDecryptionKey(decryptionKey)
    .withDecryptionPath("$", "$")
    // …
    .build();

Example:

javaCopy
String encryptedPayload = "{" +
    "  \"iv\": \"1b9396c98ab2bfd195de661d70905a45\"," +
    "  \"encryptedKey\": \"7d5112fa08e554e3dbc455d0628…52e826dd10311cf0d63bbfb231a1a63ecc13\"," +
    "  \"encryptedValue\": \"e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515\"" +
    "}";
String payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output:

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

• Encrypting Payloads with Wildcards <a name="encrypting-wildcard-mastercard-payloads"></a>

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

javaCopy
FLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withEncryptionPath("$.list[*]sensitiveField1", "$.list[*]encryptedField")
    // …
    .build();

Example:

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

Output:

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

• Decrypting Payloads with Wildcards <a name="decrypting-wildcard-mastercard-payloads"></a>

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

javaCopy
FLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withDecryptionKey(decryptionKey)
    .withDecryptionPath("$.list[*]encryptedField", "$.list[*]sensitiveField1")
    // …
    .build();

Example:

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

Output:

jsonCopy
{
  "list": [
    {"sensitiveField1": "sensitiveValue1"},
    {"sensitiveField2": "sensitiveValue2"}
  ]
}

• Using HTTP Headers for Encryption Params <a name="using-http-headers-for-encryption-params"></a>

In the sections above, encryption parameters (initialization vector, encrypted symmetric key, etc.) are part of the HTTP payloads.

Here is how to configure the library for using HTTP headers instead.

Configuration for Using HTTP Headers <a name="configuration-for-using-http-headers"></a>

Call with{Param}HeaderName instead of with{Param}FieldName when building a FieldLevelEncryptionConfig instance. Example:

javaCopy
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withEncryptionPath("$", "$")
    .withDecryptionPath("$", "$")
    .withOaepPaddingDigestAlgorithm("SHA-256")
    .withEncryptedValueFieldName("data")
    .withIvHeaderName("x-iv")
    .withEncryptedKeyHeaderName("x-encrypted-key")
    // …
    .withFieldValueEncoding(FieldValueEncoding.HEX)
    .build();

See also:

• FieldLevelEncryptionConfig.java for all config options

Encrypting Using HTTP Headers

Encryption can be performed using the following steps:

1. Generate parameters by calling FieldLevelEncryptionParams.generate:

javaCopy
FieldLevelEncryptionParams params = FieldLevelEncryptionParams.generate(config);

2. Update the request headers:

javaCopy
request.setHeader(config.getIvHeaderName(), params.getIvValue());
request.setHeader(config.getEncryptedKeyHeaderName(), params.getEncryptedKeyValue());
// …

3. Call encryptPayload with params:

javaCopy
FieldLevelEncryption.encryptPayload(payload, config, params);

Example using the configuration above:

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

Output:

jsonCopy
{
    "data": "53b5f07ee46403af2e92abab900853…d560a0a08a1ed142099e3f4c84fe5e5"
}

Decrypting Using HTTP Headers

Decryption can be performed using the following steps:

1. Read the response headers:

javaCopy
String ivValue = response.getHeader(config.getIvHeaderName());
String encryptedKeyValue = response.getHeader(config.getEncryptedKeyHeaderName());
// …

2. Create a FieldLevelEncryptionParams instance:

javaCopy
FieldLevelEncryptionParams params = new FieldLevelEncryptionParams(ivValue, encryptedKeyValue, …, config);

3. Call decryptPayload with params:

javaCopy
FieldLevelEncryption.decryptPayload(encryptedPayload, config, params);

Example using the configuration above:

javaCopy
String encryptedPayload = "{" +
    "  \"data\": \"53b5f07ee46403af2e92abab900853…d560a0a08a1ed142099e3f4c84fe5e5\"" +
    "}";
String payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config, params);
System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));

Output:

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

Integrating with OpenAPI Generator API Client Libraries <a name="integrating-with-openapi-generator-api-client-libraries"></a>

OpenAPI Generator generates API client libraries from OpenAPI Specs.
It provides generators and library templates for supporting multiple languages and frameworks.

The com.mastercard.developer.interceptors package will provide you with some interceptor classes you can use when configuring your API client.
These classes will take care of encrypting request and decrypting response payloads, but also of updating HTTP headers when needed.

Library options currently supported for the java generator:

• okhttp-gson
• feign
• retrofit
• retrofit2
• google-api-client

See also:

• OpenAPI Generator (maven Plugin)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for java

okhttp-gson <a name="okhttp-gson"></a>

OpenAPI Generator Plugin Configuration

xmlCopy
<configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
    <generatorName>java</generatorName>
    <library>okhttp-gson</library>
    <!-- … -->
</configuration>

Usage of the OkHttp2EncryptionInterceptor (OpenAPI Generator 3.3.x)

javaCopy
ApiClient client = new ApiClient();
client.setBasePath("https://sandbox.api.mastercard.com");
List<Interceptor> interceptors = client.getHttpClient().interceptors();
interceptors.add(OkHttp2EncryptionInterceptor.from(config));
interceptors.add(new OkHttp2OAuth1Interceptor(consumerKey, signingKey));
ServiceApi serviceApi = new ServiceApi(client);
// …

Usage of the OkHttpEncryptionInterceptor (OpenAPI Generator 4+)

javaCopy
ApiClient client = new ApiClient();
client.setBasePath("https://sandbox.api.mastercard.com");
client.setHttpClient(
    client.getHttpClient()
        .newBuilder()
        .addInterceptor(OkHttpEncryptionInterceptor.from(config))
        .addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, signingKey))
        .build()
);
ServiceApi serviceApi = new ServiceApi(client);
// …

feign <a name="feign"></a>

OpenAPI Generator Plugin Configuration

xmlCopy
<configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
    <generatorName>java</generatorName>
    <library>feign</library>
    <!-- … -->
</configuration>

Usage of OpenFeignEncoderExecutor and OpenFeignDecoderExecutor

javaCopy
ApiClient client = new ApiClient();
ObjectMapper objectMapper = client.getObjectMapper();
client.setBasePath("https://sandbox.api.mastercard.com");
Feign.Builder feignBuilder = client.getFeignBuilder();
ArrayList<RequestInterceptor> interceptors = new ArrayList<>();
interceptors.add(new OpenFeignOAuth1Interceptor(consumerKey, signingKey, client.getBasePath()));
feignBuilder.requestInterceptors(interceptors);
feignBuilder.encoder(OpenFeignEncoderExecutor.from(config, new FormEncoder(new JacksonEncoder(objectMapper))));
feignBuilder.decoder(OpenFeignDecoderExecutor.from(config, new JacksonDecoder(objectMapper)));
ServiceApi serviceApi = client.buildClient(ServiceApi.class);
// …

retrofit <a name="retrofit"></a>

OpenAPI Generator Plugin Configuration

xmlCopy
<configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
    <generatorName>java</generatorName>
    <library>retrofit</library>
    <!-- … -->
</configuration>

Usage of the OkHttp2EncryptionInterceptor

javaCopy
ApiClient client = new ApiClient();
RestAdapter.Builder adapterBuilder = client.getAdapterBuilder();
adapterBuilder.setEndpoint("https://sandbox.api.mastercard.com"); 
List<Interceptor> interceptors = client.getOkClient().interceptors();
interceptors.add(OkHttp2EncryptionInterceptor.from(config));
interceptors.add(new OkHttp2OAuth1Interceptor(consumerKey, signingKey));
ServiceApi serviceApi = client.createService(ServiceApi.class);
// …

retrofit2 <a name="retrofit2"></a>

OpenAPI Generator Plugin Configuration

xmlCopy
<configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
    <generatorName>java</generatorName>
    <library>retrofit2</library>
    <!-- … -->
</configuration>

Usage of the OkHttpEncryptionInterceptor

javaCopy
ApiClient client = new ApiClient();
Retrofit.Builder adapterBuilder = client.getAdapterBuilder();
adapterBuilder.baseUrl("https://sandbox.api.mastercard.com"); 
OkHttpClient.Builder okBuilder = client.getOkBuilder();
okBuilder.addInterceptor(OkHttpEncryptionInterceptor.from(config));
okBuilder.addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, signingKey));
ServiceApi serviceApi = client.createService(ServiceApi.class);
// …

google-api-client <a name="google-api-client"></a>

OpenAPI Generator Plugin Configuration

xmlCopy
<configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
    <generatorName>java</generatorName>
    <library>google-api-client</library>
    <!-- … -->
</configuration>

Usage of HttpExecuteEncryptionInterceptor and HttpExecuteInterceptorChain

javaCopy
HttpRequestInitializer initializer = new HttpRequestInitializer() {
    @Override
    public void initialize(HttpRequest request) {
        HttpExecuteOAuth1Interceptor authenticationInterceptor = new HttpExecuteOAuth1Interceptor(consumerKey, signingKey);
        HttpExecuteEncryptionInterceptor encryptionInterceptor = HttpExecuteEncryptionInterceptor.from(config);
        request.setInterceptor(new HttpExecuteInterceptorChain(Arrays.asList(encryptionInterceptor, authenticationInterceptor)));
        request.setResponseInterceptor(encryptionInterceptor);
    }
};
ApiClient client = new ApiClient("https://sandbox.api.mastercard.com", null, initializer, null);
ServiceApi serviceApi = client.serviceApi();
// …