{"id":28113283,"url":"https://github.com/Mastercard/client-encryption-java","last_synced_at":"2025-05-14T05:06:52.839Z","repository":{"id":38708058,"uuid":"171891883","full_name":"Mastercard/client-encryption-java","owner":"Mastercard","description":"Library for Mastercard API compliant payload encryption/decryption.","archived":false,"fork":false,"pushed_at":"2025-04-10T10:20:26.000Z","size":577,"stargazers_count":122,"open_issues_count":1,"forks_count":80,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-04-10T10:43:37.377Z","etag":null,"topics":["decryption","encryption","field-level-encryption","fle","java","jwe","mastercard","openapi"],"latest_commit_sha":null,"homepage":"https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mastercard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-21T14:59:33.000Z","updated_at":"2025-04-10T09:09:32.000Z","dependencies_parsed_at":"2024-01-17T18:28:21.328Z","dependency_job_id":"a75cbd12-d236-4ba2-89c8-f970767ceb18","html_url":"https://github.com/Mastercard/client-encryption-java","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/client-encryption-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076849,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decryption","encryption","field-level-encryption","fle","java","jwe","mastercard","openapi"],"created_at":"2025-05-14T05:01:35.958Z","updated_at":"2025-05-14T05:06:52.829Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","readme":"# client-encryption-java\n[![](https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-dark.svg)](https://developer.mastercard.com/)\n\n[![](https://github.com/Mastercard/client-encryption-java/workflows/Build%20\u0026%20Test/badge.svg)](https://github.com/Mastercard/client-encryption-java/actions?query=workflow%3A%22Build+%26+Test%22)\n[![](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_client-encryption-java\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=Mastercard_client-encryption-java)\n[![](https://github.com/Mastercard/client-encryption-java/workflows/broken%20links%3F/badge.svg)](https://github.com/Mastercard/client-encryption-java/actions?query=workflow%3A%22broken+links%3F%22)\n[![](https://img.shields.io/maven-central/v/com.mastercard.developer/client-encryption.svg)](https://search.maven.org/artifact/com.mastercard.developer/client-encryption/)\n[![](https://www.javadoc.io/badge/com.mastercard.developer/client-encryption.svg?color=blue)](https://www.javadoc.io/doc/com.mastercard.developer/client-encryption)\n[![](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/Mastercard/client-encryption-java/blob/master/LICENSE)\n\n## Table of Contents\n- [Overview](#overview)\n  * [Compatibility](#compatibility)\n  * [References](#references)\n  * [Versioning and Deprecation Policy](#versioning)\n- [Usage](#usage)\n  * [Prerequisites](#prerequisites)\n  * [Adding the Library to Your Project](#adding-the-library-to-your-project)\n  * [Selecting a JSON Engine](#selecting-a-json-engine)\n  * [Loading the Encryption Certificate](#loading-the-encryption-certificate) \n  * [Loading the Decryption Key](#loading-the-decryption-key)\n  * [Performing Payload Encryption and Decryption](#performing-payload-encryption-and-decryption)\n    * [Introduction](#introduction)\n    * [JWE Encryption and Decryption](#jwe-encryption-and-decryption)\n    * [Mastercard Encryption and Decryption](#mastercard-encryption-and-decryption)\n  * [Integrating with OpenAPI Generator API Client Libraries](#integrating-with-openapi-generator-api-client-libraries)\n\n## Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\nLibrary for Mastercard API compliant payload encryption/decryption.\n\n### Compatibility \u003ca name=\"compatibility\"\u003e\u003c/a\u003e\nJava 11+\n\n### References \u003ca name=\"references\"\u003e\u003c/a\u003e\n* [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516)\n* [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)\n\n### Versioning and Deprecation Policy \u003ca name=\"versioning\"\u003e\u003c/a\u003e\n* [Mastercard Versioning and Deprecation Policy](https://github.com/Mastercard/.github/blob/main/CLIENT_LIBRARY_DEPRECATION_POLICY.md)\n\n## Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n### Prerequisites \u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\nBefore using this library, you will need to set up a project in the [Mastercard Developers Portal](https://developer.mastercard.com). \n\nAs part of this set up, you'll receive:\n* A public request encryption certificate (aka _Client Encryption Keys_)\n* A private response decryption key (aka _Mastercard Encryption Keys_)\n\n### Adding the Library to Your Project \u003ca name=\"adding-the-library-to-your-project\"\u003e\u003c/a\u003e\n\n#### Maven\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.mastercard.developer\u003c/groupId\u003e\n    \u003cartifactId\u003eclient-encryption\u003c/artifactId\u003e\n    \u003cversion\u003e${client-encryption-version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Gradle\n```\ndependencies {\n    implementation \"com.mastercard.developer:client-encryption:$clientEncryptionVersion\"\n}\t\n```\n\n#### Other Dependency Managers\nSee: https://search.maven.org/artifact/com.mastercard.developer/client-encryption\n\n### Selecting a JSON Engine \u003ca name=\"selecting-a-json-engine\"\u003e\u003c/a\u003e\n\nThis library requires one of the following dependencies to be added to your classpath:\n\n* [Jackson](https://search.maven.org/artifact/com.fasterxml.jackson.core/jackson-databind) 2.5.0+\n* [Google Gson](https://search.maven.org/artifact/com.google.code.gson/gson) 2.3.1+\n* [Json-smart](https://search.maven.org/artifact/net.minidev/json-smart) 2.1.1+\n* [Jettison](https://search.maven.org/artifact/org.codehaus.jettison/jettison) 1.0+\n* [Org JSON](https://search.maven.org/artifact/org.json/json) 20070829+\n\nYou can either let the library choose for you, or force the one to be used by calling `withJsonEngine` on the `JsonParser` class.\nExample:\n\n```java\nJsonParser.withJsonEngine(new JettisonJsonEngine());\n```\n\nAvailable engine classes: \n* `GsonJsonEngine`\n* `JacksonJsonEngine`\n* `JettisonJsonEngine`\n* `JsonOrgJsonEngine`\n* `JsonSmartJsonEngine`\n\n### Loading the Encryption Certificate \u003ca name=\"loading-the-encryption-certificate\"\u003e\u003c/a\u003e\n\nA `Certificate` object can be created from a file by calling `EncryptionUtils.loadEncryptionCertificate`:\n```java\nCertificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(\"\u003cinsert certificate file path\u003e\");\n```\n\nSupported certificate formats: PEM, DER.\n\n### Loading the Decryption Key \u003ca name=\"loading-the-decryption-key\"\u003e\u003c/a\u003e\n\n#### From a PKCS#12 Key Store\n\nA `PrivateKey` object can be created from a PKCS#12 key store by calling `EncryptionUtils.loadDecryptionKey` the following way:\n```java\nPrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(\n                                    \"\u003cinsert PKCS#12 key file path\u003e\", \n                                    \"\u003cinsert key alias\u003e\", \n                                    \"\u003cinsert key password\u003e\");\n```\n\n#### From an Unencrypted Key File\n\nA `PrivateKey` object can be created from an unencrypted key file by calling `EncryptionUtils.loadDecryptionKey` the following way:\n```java\nPrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(\"\u003cinsert key file path\u003e\");\n```\n\nSupported RSA key formats:\n* PKCS#1 PEM (starts with \"-----BEGIN RSA PRIVATE KEY-----\")\n* PKCS#8 PEM (starts with \"-----BEGIN PRIVATE KEY-----\")\n* Binary DER-encoded PKCS#8\n\n### Performing Payload Encryption and Decryption \u003ca name=\"performing-payload-encryption-and-decryption\"\u003e\u003c/a\u003e\n\n+ [Introduction](#introduction)\n+ [JWE Encryption and Decryption](#jwe-encryption-and-decryption)\n+ [Mastercard Encryption and Decryption](#mastercard-encryption-and-decryption)\n\n#### Introduction \u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\nThis 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.\n\n#### JWE Encryption and Decryption \u003ca name=\"jwe-encryption-and-decryption\"\u003e\u003c/a\u003e\n\n+ [Introduction](#jwe-introduction)\n+ [Configuring the JWE Encryption](#configuring-the-jwe-encryption)\n+ [Performing JWE Encryption](#performing-jwe-encryption)\n+ [Performing JWE Decryption](#performing-jwe-decryption)\n+ [Encrypting Entire Payloads](#encrypting-entire-payloads-jwe)\n+ [Decrypting Entire Payloads](#decrypting-entire-payloads-jwe)\n+ [Encrypting Payloads with Wildcards](#encrypting-wildcard-payloads-jwe)\n+ [Decrypting Payloads with Wildcards](#decrypting-wildcard-payloads-jwe)\n\n##### • Introduction \u003ca name=\"jwe-introduction\"\u003e\u003c/a\u003e\n\nThis library uses [JWE compact serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.1) for the encryption of sensitive data.\nThe core methods responsible for payload encryption and decryption are `encryptPayload` and `decryptPayload` in the `JweEncryption` class.\n\n* `encryptPayload` usage:\n```java\nString encryptedRequestPayload = JweEncryption.encryptPayload(requestPayload, config);\n\n```\n\n* `decryptPayload` usage:\n```java\nString responsePayload = JweEncryption.decryptPayload(encryptedResponsePayload, config);\n```\n\n##### • Configuring the JWE Encryption \u003ca name=\"configuring-the-jwe-encryption\"\u003e\u003c/a\u003e\nUse the `JweConfigBuilder` to create `JweConfig` instances. Example:\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withDecryptionKey(decryptionKey)\n    .withEncryptionPath(\"$.path.to.foo\", \"$.path.to.encryptedFoo\")\n    .withDecryptionPath(\"$.path.to.encryptedFoo.encryptedValue\", \"$.path.to.foo\")\n    .withEncryptedValueFieldName(\"encryptedValue\")\n    .withIVSize(16) // available values are 12 or 16. If not specified, default value is 16.\n    .build();\n```\n\n##### • Performing JWE Encryption \u003ca name=\"performing-jwe-encryption\"\u003e\u003c/a\u003e\n\nCall `JweEncryption.encryptPayload` with a JSON request payload and a `JweConfig` instance.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n```java\nString payload = \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"foo\\\": {\" +\n    \"                \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"                \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\";\nString encryptedPayload = JweEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"encryptedFoo\": {\n                \"encryptedValue\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"\n            }\n        }\n    }\n}\n```\n\n##### • Performing JWE Decryption \u003ca name=\"performing-jwe-decryption\"\u003e\u003c/a\u003e\n\nCall `JweEncryption.decryptPayload` with a JSON response payload and a `JweConfig` instance.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n```java\nString encryptedPayload = \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"encryptedFoo\\\": {\" +\n    \"                \\\"encryptedValue\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\";\nString payload = JweEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"foo\": {\n                \"sensitiveField1\": \"sensitiveValue1\",\n                \"sensitiveField2\": \"sensitiveValue2\"\n            }\n        }\n    }\n}\n```\n\n##### • Encrypting Entire Payloads \u003ca name=\"encrypting-entire-payloads-jwe\"\u003e\u003c/a\u003e\n\nEntire payloads can be encrypted using the \"$\" operator as encryption path:\n\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withEncryptionPath(\"$\", \"$\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString payload = \"{\" +\n    \"    \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"    \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"}\";\nString encryptedPayload = JweEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n    \"encryptedValue\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"\n}\n```\n\n##### • Decrypting Entire Payloads \u003ca name=\"decrypting-entire-payloads-jwe\"\u003e\u003c/a\u003e\n\nEntire payloads can be decrypted using the \"$\" operator as decryption path:\n\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n    .withDecryptionKey(decryptionKey)\n    .withDecryptionPath(\"$.encryptedValue\", \"$\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString encryptedPayload = \"{\" +\n    \"  \\\"encryptedValue\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"\" +\n    \"}\";\nString payload = JweEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n    \"sensitiveField1\": \"sensitiveValue1\",\n    \"sensitiveField2\": \"sensitiveValue2\"\n}\n```\n\n##### • Encrypting Payloads with Wildcards \u003ca name=\"encrypting-wildcard-payloads-jwe\"\u003e\u003c/a\u003e\n\nWildcards can be encrypted using the \"[*]\" operator as part of encryption path:\n\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withEncryptionPath(\"$.list[*]sensitiveField1\", \"$.list[*]encryptedField\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString payload = \"{ \\\"list\\\": [ \" +\n    \"   { \\\"sensitiveField1\\\" : \\\"sensitiveValue1\\\"}, \"+\n    \"   { \\\"sensitiveField1\\\" : \\\"sensitiveValue2\\\"} \" +\n    \"]}\";\nString encryptedPayload = JweEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n  \"list\": [\n    {\"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"},\n    {\"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm\"}\n  ]\n}\n```\n\n##### • Decrypting Payloads with Wildcards \u003ca name=\"decrypting-wildcard-payloads-jwe\"\u003e\u003c/a\u003e\n\nWildcards can be decrypted using the \"[*]\" operator as part of decryption path:\n\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n    .withDecryptionKey(decryptionKey)\n    .withDecryptionPath(\"$.list[*]encryptedField\", \"$.list[*]sensitiveField1\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString encryptedPayload = \"{ \\\"list\\\": [ \" +\n        \" { \\\"encryptedField\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"}, \" +\n        \" { \\\"encryptedField\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm\\\"} \" +\n        \" ]}\";\nString payload = JweEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n  \"list\": [\n    {\"sensitiveField1\": \"sensitiveValue1\"},\n    {\"sensitiveField2\": \"sensitiveValue2\"}\n  ]\n}\n```\n\n#### Mastercard Encryption and Decryption \u003ca name=\"mastercard-encryption-and-decryption\"\u003e\u003c/a\u003e\n\n+ [Introduction](#mastercard-introduction)\n+ [Configuring the Mastercard Encryption](#configuring-the-mastercard-encryption)\n+ [Performing Mastercard Encryption](#performing-mastercard-encryption)\n+ [Performing Mastercard Decryption](#performing-mastercard-decryption)\n+ [Encrypting Entire Payloads](#encrypting-entire-mastercard-payloads)\n+ [Decrypting Entire Payloads](#decrypting-entire-mastercard-payloads)\n+ [Encrypting Payloads with Wildcards](#encrypting-wildcard-mastercard-payloads)\n+ [Decrypting Payloads with Wildcards](#decrypting-wildcard-mastercard-payloads)\n+ [Using HTTP Headers for Encryption Params](#using-http-headers-for-encryption-params)\n\n##### • Introduction \u003ca name=\"mastercard-introduction\"\u003e\u003c/a\u003e\n \nThe core methods responsible for payload encryption and decryption are `encryptPayload` and `decryptPayload` in the `FieldLevelEncryption` class.\n\n* `encryptPayload` usage:\n```java\nString encryptedRequestPayload = FieldLevelEncryption.encryptPayload(requestPayload, config);\n\n```\n\n* `decryptPayload` usage:\n```java\nString responsePayload = FieldLevelEncryption.decryptPayload(encryptedResponsePayload, config);\n```\n\n##### • Configuring the Mastercard Encryption \u003ca name=\"configuring-the-mastercard-encryption\"\u003e\u003c/a\u003e\nUse the `FieldLevelEncryptionConfigBuilder` to create `FieldLevelEncryptionConfig` instances. Example:\n```java\nFieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withDecryptionKey(decryptionKey)\n    .withEncryptionPath(\"$.path.to.foo\", \"$.path.to.encryptedFoo\")\n    .withDecryptionPath(\"$.path.to.encryptedFoo\", \"$.path.to.foo\")\n    .withOaepPaddingDigestAlgorithm(\"SHA-256\")\n    .withEncryptedValueFieldName(\"encryptedValue\")\n    .withEncryptedKeyFieldName(\"encryptedKey\")\n    .withIvFieldName(\"iv\")\n    .withFieldValueEncoding(FieldValueEncoding.HEX)\n    .build();\n```\n\nSee also:\n* [FieldLevelEncryptionConfig.java](https://www.javadoc.io/page/com.mastercard.developer/client-encryption/latest/com/mastercard/developer/encryption/FieldLevelEncryptionConfig.html) for all config options\n\n##### • Performing Mastercard Encryption \u003ca name=\"performing-mastercard-encryption\"\u003e\u003c/a\u003e\n\nCall `FieldLevelEncryption.encryptPayload` with a JSON request payload and a `FieldLevelEncryptionConfig` instance.\n\nExample using the configuration [above](#configuring-the-field-level-encryption):\n```java\nString payload = \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"foo\\\": {\" +\n    \"                \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"                \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\";\nString encryptedPayload = FieldLevelEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"encryptedFoo\": {\n                \"iv\": \"7f1105fb0c684864a189fb3709ce3d28\",\n                \"encryptedKey\": \"67f467d1b653d98411a0c6d3c…ffd4c09dd42f713a51bff2b48f937c8\",\n                \"encryptedValue\": \"b73aabd267517fc09ed72455c2…dffb5fa04bf6e6ce9ade1ff514ed6141\"\n            }\n        }\n    }\n}\n```\n\n##### • Performing Mastercard Decryption \u003ca name=\"performing-mastercard-decryption\"\u003e\u003c/a\u003e\n\nCall `FieldLevelEncryption.decryptPayload` with a JSON response payload and a `FieldLevelEncryptionConfig` instance.\n\nExample using the configuration [above](#configuring-the-field-level-encryption):\n```java\nString encryptedPayload = \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"encryptedFoo\\\": {\" +\n    \"                \\\"iv\\\": \\\"e5d313c056c411170bf07ac82ede78c9\\\",\" +\n    \"                \\\"encryptedKey\\\": \\\"e3a56746c0f9109d18b3a2652b76…f16d8afeff36b2479652f5c24ae7bd\\\",\" +\n    \"                \\\"encryptedValue\\\": \\\"809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\";\nString payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"foo\": {\n                \"sensitiveField1\": \"sensitiveValue1\",\n                \"sensitiveField2\": \"sensitiveValue2\"\n            }\n        }\n    }\n}\n```\n\n##### • Encrypting Entire Payloads \u003ca name=\"encrypting-entire-mastercard-payloads\"\u003e\u003c/a\u003e\n\nEntire payloads can be encrypted using the \"$\" operator as encryption path:\n\n```java\nFieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withEncryptionPath(\"$\", \"$\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString payload = \"{\" +\n    \"    \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"    \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"}\";\nString encryptedPayload = FieldLevelEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n    \"iv\": \"1b9396c98ab2bfd195de661d70905a45\",\n    \"encryptedKey\": \"7d5112fa08e554e3dbc455d0628…52e826dd10311cf0d63bbfb231a1a63ecc13\",\n    \"encryptedValue\": \"e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515\"\n}\n```\n\n##### • Decrypting Entire Payloads \u003ca name=\"decrypting-entire-mastercard-payloads\"\u003e\u003c/a\u003e\n\nEntire payloads can be decrypted using the \"$\" operator as decryption path:\n\n```java\nFieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withDecryptionKey(decryptionKey)\n    .withDecryptionPath(\"$\", \"$\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString encryptedPayload = \"{\" +\n    \"  \\\"iv\\\": \\\"1b9396c98ab2bfd195de661d70905a45\\\",\" +\n    \"  \\\"encryptedKey\\\": \\\"7d5112fa08e554e3dbc455d0628…52e826dd10311cf0d63bbfb231a1a63ecc13\\\",\" +\n    \"  \\\"encryptedValue\\\": \\\"e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515\\\"\" +\n    \"}\";\nString payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n    \"sensitiveField1\": \"sensitiveValue1\",\n    \"sensitiveField2\": \"sensitiveValue2\"\n}\n\n```\n##### • Encrypting Payloads with Wildcards \u003ca name=\"encrypting-wildcard-mastercard-payloads\"\u003e\u003c/a\u003e\n\nWildcards can be encrypted using the \"[*]\" operator as part of encryption path:\n\n```java\nFLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withEncryptionPath(\"$.list[*]sensitiveField1\", \"$.list[*]encryptedField\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString payload = \"{ \\\"list\\\": [ \" +\n    \"   { \\\"sensitiveField1\\\" : \\\"sensitiveValue1\\\"}, \"+\n    \"   { \\\"sensitiveField1\\\" : \\\"sensitiveValue2\\\"} \" +\n    \"]}\";\nString encryptedPayload = FieldLevelEncryption.encryptPayload(payload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n  \"list\": [\n    {\"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"},\n    {\"encryptedField\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm\"}\n  ]\n}\n```\n\n##### • Decrypting Payloads with Wildcards \u003ca name=\"decrypting-wildcard-mastercard-payloads\"\u003e\u003c/a\u003e\n\nWildcards can be decrypted using the \"[*]\" operator as part of decryption path:\n\n```java\nFLEConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withDecryptionKey(decryptionKey)\n    .withDecryptionPath(\"$.list[*]encryptedField\", \"$.list[*]sensitiveField1\")\n    // …\n    .build();\n```\n\nExample:\n```java\nString encryptedPayload = \"{ \\\"list\\\": [ \" +\n        \" { \\\"encryptedField\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"}, \" +\n        \" { \\\"encryptedField\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+asdvarvasdvfdvakmkmm\\\"} \" +\n        \" ]}\";\nString payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n  \"list\": [\n    {\"sensitiveField1\": \"sensitiveValue1\"},\n    {\"sensitiveField2\": \"sensitiveValue2\"}\n  ]\n}\n```\n\n##### • Using HTTP Headers for Encryption Params \u003ca name=\"using-http-headers-for-encryption-params\"\u003e\u003c/a\u003e\n\nIn the sections above, encryption parameters (initialization vector, encrypted symmetric key, etc.) are part of the HTTP payloads.\n\nHere is how to configure the library for using HTTP headers instead.\n\n###### Configuration for Using HTTP Headers \u003ca name=\"configuration-for-using-http-headers\"\u003e\u003c/a\u003e\n\nCall `with{Param}HeaderName` instead of `with{Param}FieldName` when building a `FieldLevelEncryptionConfig` instance. Example:\n```java\nFieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()\n    .withEncryptionCertificate(encryptionCertificate)\n    .withDecryptionKey(decryptionKey)\n    .withEncryptionPath(\"$\", \"$\")\n    .withDecryptionPath(\"$\", \"$\")\n    .withOaepPaddingDigestAlgorithm(\"SHA-256\")\n    .withEncryptedValueFieldName(\"data\")\n    .withIvHeaderName(\"x-iv\")\n    .withEncryptedKeyHeaderName(\"x-encrypted-key\")\n    // …\n    .withFieldValueEncoding(FieldValueEncoding.HEX)\n    .build();\n```\n\nSee also:\n* [FieldLevelEncryptionConfig.java](https://www.javadoc.io/page/com.mastercard.developer/client-encryption/latest/com/mastercard/developer/encryption/FieldLevelEncryptionConfig.html) for all config options\n\n###### Encrypting Using HTTP Headers\n\nEncryption can be performed using the following steps:\n\n1. Generate parameters by calling `FieldLevelEncryptionParams.generate`:\n\n```java\nFieldLevelEncryptionParams params = FieldLevelEncryptionParams.generate(config);\n```\n\n2. Update the request headers:\n\n```java\nrequest.setHeader(config.getIvHeaderName(), params.getIvValue());\nrequest.setHeader(config.getEncryptedKeyHeaderName(), params.getEncryptedKeyValue());\n// …\n```\n\n3. Call `encryptPayload` with params:\n```java\nFieldLevelEncryption.encryptPayload(payload, config, params);\n```\n\nExample using the configuration [above](#configuration-for-using-http-headers):\n\n```java\nString payload = \"{\" +\n    \"    \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"    \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"}\";\nString encryptedPayload = FieldLevelEncryption.encryptPayload(payload, config, params);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(encryptedPayload)));\n```\n\nOutput:\n```json\n{\n    \"data\": \"53b5f07ee46403af2e92abab900853…d560a0a08a1ed142099e3f4c84fe5e5\"\n}\n```\n\n###### Decrypting Using HTTP Headers\n\nDecryption can be performed using the following steps:\n\n1. Read the response headers:\n\n```java\nString ivValue = response.getHeader(config.getIvHeaderName());\nString encryptedKeyValue = response.getHeader(config.getEncryptedKeyHeaderName());\n// …\n```\n\n2. Create a `FieldLevelEncryptionParams` instance:\n\n```java\nFieldLevelEncryptionParams params = new FieldLevelEncryptionParams(ivValue, encryptedKeyValue, …, config);\n```\n\n3. Call `decryptPayload` with params:\n```java\nFieldLevelEncryption.decryptPayload(encryptedPayload, config, params);\n```\n\nExample using the configuration [above](#configuration-for-using-http-headers):\n\n```java\nString encryptedPayload = \"{\" +\n    \"  \\\"data\\\": \\\"53b5f07ee46403af2e92abab900853…d560a0a08a1ed142099e3f4c84fe5e5\\\"\" +\n    \"}\";\nString payload = FieldLevelEncryption.decryptPayload(encryptedPayload, config, params);\nSystem.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(new JsonParser().parse(payload)));\n```\n\nOutput:\n```json\n{\n    \"sensitiveField1\": \"sensitiveValue1\",\n    \"sensitiveField2\": \"sensitiveValue2\"\n}\n```\n\n### Integrating with OpenAPI Generator API Client Libraries \u003ca name=\"integrating-with-openapi-generator-api-client-libraries\"\u003e\u003c/a\u003e\n\n[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification). \nIt provides generators and library templates for supporting multiple languages and frameworks.\n\nThe `com.mastercard.developer.interceptors` package will provide you with some interceptor classes you can use when configuring your API client. \nThese classes will take care of encrypting request and decrypting response payloads, but also of updating HTTP headers when needed.\n\nLibrary options currently supported for the `java` generator:\n+ [okhttp-gson](#okhttp-gson)\n+ [feign](#feign)\n+ [retrofit](#retrofit)\n+ [retrofit2](#retrofit2)\n+ [google-api-client](#google-api-client)\n\nSee also:\n* [OpenAPI Generator (maven Plugin)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin)\n* [OpenAPI Generator (executable)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli)\n* [CONFIG OPTIONS for java](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/java.md)\n\n#### okhttp-gson \u003ca name=\"okhttp-gson\"\u003e\u003c/a\u003e\n##### OpenAPI Generator Plugin Configuration\n```xml\n\u003cconfiguration\u003e\n    \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi-spec.yaml\u003c/inputSpec\u003e\n    \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n    \u003clibrary\u003eokhttp-gson\u003c/library\u003e\n    \u003c!-- … --\u003e\n\u003c/configuration\u003e\n```\n\n##### Usage of the `OkHttp2EncryptionInterceptor` (OpenAPI Generator 3.3.x)\n```java\nApiClient client = new ApiClient();\nclient.setBasePath(\"https://sandbox.api.mastercard.com\");\nList\u003cInterceptor\u003e interceptors = client.getHttpClient().interceptors();\ninterceptors.add(OkHttp2EncryptionInterceptor.from(config));\ninterceptors.add(new OkHttp2OAuth1Interceptor(consumerKey, signingKey));\nServiceApi serviceApi = new ServiceApi(client);\n// …\n```\n\n##### Usage of the `OkHttpEncryptionInterceptor` (OpenAPI Generator 4+)\n```java\nApiClient client = new ApiClient();\nclient.setBasePath(\"https://sandbox.api.mastercard.com\");\nclient.setHttpClient(\n    client.getHttpClient()\n        .newBuilder()\n        .addInterceptor(OkHttpEncryptionInterceptor.from(config))\n        .addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, signingKey))\n        .build()\n);\nServiceApi serviceApi = new ServiceApi(client);\n// …\n```\n\n#### feign \u003ca name=\"feign\"\u003e\u003c/a\u003e\n##### OpenAPI Generator Plugin Configuration\n```xml\n\u003cconfiguration\u003e\n    \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi-spec.yaml\u003c/inputSpec\u003e\n    \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n    \u003clibrary\u003efeign\u003c/library\u003e\n    \u003c!-- … --\u003e\n\u003c/configuration\u003e\n```\n\n##### Usage of `OpenFeignEncoderExecutor` and `OpenFeignDecoderExecutor`\n```java\nApiClient client = new ApiClient();\nObjectMapper objectMapper = client.getObjectMapper();\nclient.setBasePath(\"https://sandbox.api.mastercard.com\");\nFeign.Builder feignBuilder = client.getFeignBuilder();\nArrayList\u003cRequestInterceptor\u003e interceptors = new ArrayList\u003c\u003e();\ninterceptors.add(new OpenFeignOAuth1Interceptor(consumerKey, signingKey, client.getBasePath()));\nfeignBuilder.requestInterceptors(interceptors);\nfeignBuilder.encoder(OpenFeignEncoderExecutor.from(config, new FormEncoder(new JacksonEncoder(objectMapper))));\nfeignBuilder.decoder(OpenFeignDecoderExecutor.from(config, new JacksonDecoder(objectMapper)));\nServiceApi serviceApi = client.buildClient(ServiceApi.class);\n// …\n```\n\n#### retrofit \u003ca name=\"retrofit\"\u003e\u003c/a\u003e\n##### OpenAPI Generator Plugin Configuration\n```xml\n\u003cconfiguration\u003e\n    \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi-spec.yaml\u003c/inputSpec\u003e\n    \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n    \u003clibrary\u003eretrofit\u003c/library\u003e\n    \u003c!-- … --\u003e\n\u003c/configuration\u003e\n```\n\n##### Usage of the `OkHttp2EncryptionInterceptor`\n```java\nApiClient client = new ApiClient();\nRestAdapter.Builder adapterBuilder = client.getAdapterBuilder();\nadapterBuilder.setEndpoint(\"https://sandbox.api.mastercard.com\"); \nList\u003cInterceptor\u003e interceptors = client.getOkClient().interceptors();\ninterceptors.add(OkHttp2EncryptionInterceptor.from(config));\ninterceptors.add(new OkHttp2OAuth1Interceptor(consumerKey, signingKey));\nServiceApi serviceApi = client.createService(ServiceApi.class);\n// …\n```\n\n#### retrofit2 \u003ca name=\"retrofit2\"\u003e\u003c/a\u003e\n##### OpenAPI Generator Plugin Configuration\n```xml\n\u003cconfiguration\u003e\n    \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi-spec.yaml\u003c/inputSpec\u003e\n    \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n    \u003clibrary\u003eretrofit2\u003c/library\u003e\n    \u003c!-- … --\u003e\n\u003c/configuration\u003e\n```\n\n##### Usage of the `OkHttpEncryptionInterceptor`\n```java\nApiClient client = new ApiClient();\nRetrofit.Builder adapterBuilder = client.getAdapterBuilder();\nadapterBuilder.baseUrl(\"https://sandbox.api.mastercard.com\"); \nOkHttpClient.Builder okBuilder = client.getOkBuilder();\nokBuilder.addInterceptor(OkHttpEncryptionInterceptor.from(config));\nokBuilder.addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, signingKey));\nServiceApi serviceApi = client.createService(ServiceApi.class);\n// …\n```\n\n#### google-api-client \u003ca name=\"google-api-client\"\u003e\u003c/a\u003e\n##### OpenAPI Generator Plugin Configuration\n```xml\n\u003cconfiguration\u003e\n    \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi-spec.yaml\u003c/inputSpec\u003e\n    \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n    \u003clibrary\u003egoogle-api-client\u003c/library\u003e\n    \u003c!-- … --\u003e\n\u003c/configuration\u003e\n```\n\n##### Usage of `HttpExecuteEncryptionInterceptor` and `HttpExecuteInterceptorChain`\n```java\nHttpRequestInitializer initializer = new HttpRequestInitializer() {\n    @Override\n    public void initialize(HttpRequest request) {\n        HttpExecuteOAuth1Interceptor authenticationInterceptor = new HttpExecuteOAuth1Interceptor(consumerKey, signingKey);\n        HttpExecuteEncryptionInterceptor encryptionInterceptor = HttpExecuteEncryptionInterceptor.from(config);\n        request.setInterceptor(new HttpExecuteInterceptorChain(Arrays.asList(encryptionInterceptor, authenticationInterceptor)));\n        request.setResponseInterceptor(encryptionInterceptor);\n    }\n};\nApiClient client = new ApiClient(\"https://sandbox.api.mastercard.com\", null, initializer, null);\nServiceApi serviceApi = client.serviceApi();\n// …\n```\n","funding_links":[],"categories":["安全"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMastercard%2Fclient-encryption-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMastercard%2Fclient-encryption-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMastercard%2Fclient-encryption-java/lists"}