com.mastercard.developer:client-encryption
Advanced tools
Library for Mastercard API compliant payload encryption/decryption
Library for Mastercard API compliant payload encryption/decryption.
Java 11+
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:
<dependency>
<groupId>com.mastercard.developer</groupId>
<artifactId>client-encryption</artifactId>
<version>${client-encryption-version}</version>
</dependency>
dependencies {
implementation "com.mastercard.developer:client-encryption:$clientEncryptionVersion"
}
See: https://search.maven.org/artifact/com.mastercard.developer/client-encryption
This library requires one of the following dependencies to be added to your classpath:
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:
GsonJsonEngineJacksonJsonEngineJettisonJsonEngineJsonOrgJsonEngineJsonSmartJsonEngineA 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.
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>");
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:
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.
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);
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();
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"
}
}
}
}
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"
}
}
}
}
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"
}
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"
}
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"}
]
}
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:
{
"list": [
{"sensitiveField1": "sensitiveValue1"},
{"sensitiveField2": "sensitiveValue2"}
]
}
The core methods responsible for payload encryption and decryption are encryptPayload and decryptPayload in the FieldLevelEncryption class.
encryptPayload usage:String encryptedRequestPayload = FieldLevelEncryption.encryptPayload(requestPayload, config);
decryptPayload usage:String responsePayload = FieldLevelEncryption.decryptPayload(encryptedResponsePayload, config);
Use the FieldLevelEncryptionConfigBuilder to create FieldLevelEncryptionConfig instances. Example:
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:
Call FieldLevelEncryption.encryptPayload with a JSON request payload and a FieldLevelEncryptionConfig instance.
Example using the configuration above:
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:
{
"path": {
"to": {
"encryptedFoo": {
"iv": "7f1105fb0c684864a189fb3709ce3d28",
"encryptedKey": "67f467d1b653d98411a0c6d3c…ffd4c09dd42f713a51bff2b48f937c8",
"encryptedValue": "b73aabd267517fc09ed72455c2…dffb5fa04bf6e6ce9ade1ff514ed6141"
}
}
}
}
Call FieldLevelEncryption.decryptPayload with a JSON response payload and a FieldLevelEncryptionConfig instance.
Example using the configuration above:
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:
{
"path": {
"to": {
"foo": {
"sensitiveField1": "sensitiveValue1",
"sensitiveField2": "sensitiveValue2"
}
}
}
}
Entire payloads can be encrypted using the "$" operator as encryption path:
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
.withEncryptionCertificate(encryptionCertificate)
.withEncryptionPath("$", "$")
// …
.build();
Example:
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:
{
"iv": "1b9396c98ab2bfd195de661d70905a45",
"encryptedKey": "7d5112fa08e554e3dbc455d0628…52e826dd10311cf0d63bbfb231a1a63ecc13",
"encryptedValue": "e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515"
}
Entire payloads can be decrypted using the "$" operator as decryption path:
FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
.withDecryptionKey(decryptionKey)
.withDecryptionPath("$", "$")
// …
.build();
Example:
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:
{
"sensitiveField1": "sensitiveValue1",
"sensitiveField2": "sensitiveValue2"
}
Wildcards can be encrypted using the "[*]" operator as part of encryption path:
FLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
.withEncryptionCertificate(encryptionCertificate)
.withEncryptionPath("$.list[*]sensitiveField1", "$.list[*]encryptedField")
// …
.build();
Example:
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:
{
"list": [
{"encryptedField": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"},
{"encryptedField": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm"}
]
}
Wildcards can be decrypted using the "[*]" operator as part of decryption path:
FLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
.withDecryptionKey(decryptionKey)
.withDecryptionPath("$.list[*]encryptedField", "$.list[*]sensitiveField1")
// …
.build();
Example:
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:
{
"list": [
{"sensitiveField1": "sensitiveValue1"},
{"sensitiveField2": "sensitiveValue2"}
]
}
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.
Call with{Param}HeaderName instead of with{Param}FieldName when building a FieldLevelEncryptionConfig instance. Example:
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:
Encryption can be performed using the following steps:
FieldLevelEncryptionParams.generate:FieldLevelEncryptionParams params = FieldLevelEncryptionParams.generate(config);
request.setHeader(config.getIvHeaderName(), params.getIvValue());
request.setHeader(config.getEncryptedKeyHeaderName(), params.getEncryptedKeyValue());
// …
encryptPayload with params:FieldLevelEncryption.encryptPayload(payload, config, params);
Example using the configuration above:
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:
{
"data": "53b5f07ee46403af2e92abab900853…d560a0a08a1ed142099e3f4c84fe5e5"
}
Decryption can be performed using the following steps:
String ivValue = response.getHeader(config.getIvHeaderName());
String encryptedKeyValue = response.getHeader(config.getEncryptedKeyHeaderName());
// …
FieldLevelEncryptionParams instance:FieldLevelEncryptionParams params = new FieldLevelEncryptionParams(ivValue, encryptedKeyValue, …, config);
decryptPayload with params:FieldLevelEncryption.decryptPayload(encryptedPayload, config, params);
Example using the configuration above:
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:
{
"sensitiveField1": "sensitiveValue1",
"sensitiveField2": "sensitiveValue2"
}
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:
See also:
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
<generatorName>java</generatorName>
<library>okhttp-gson</library>
<!-- … -->
</configuration>
OkHttp2EncryptionInterceptor (OpenAPI Generator 3.3.x)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);
// …
OkHttpEncryptionInterceptor (OpenAPI Generator 4+)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);
// …
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
<generatorName>java</generatorName>
<library>feign</library>
<!-- … -->
</configuration>
OpenFeignEncoderExecutor and OpenFeignDecoderExecutorApiClient 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);
// …
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
<generatorName>java</generatorName>
<library>retrofit</library>
<!-- … -->
</configuration>
OkHttp2EncryptionInterceptorApiClient 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);
// …
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
<generatorName>java</generatorName>
<library>retrofit2</library>
<!-- … -->
</configuration>
OkHttpEncryptionInterceptorApiClient 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);
// …
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi-spec.yaml</inputSpec>
<generatorName>java</generatorName>
<library>google-api-client</library>
<!-- … -->
</configuration>
HttpExecuteEncryptionInterceptor and HttpExecuteInterceptorChainHttpRequestInitializer 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();
// …
FAQs
Library for Mastercard API compliant payload encryption/decryption
We found that com.mastercard.developer:client-encryption demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.