{"id":28577532,"url":"https://github.com/mastercard/client-encryption-python","last_synced_at":"2025-09-10T08:37:23.912Z","repository":{"id":34902523,"uuid":"171892169","full_name":"Mastercard/client-encryption-python","owner":"Mastercard","description":"Library for Mastercard API compliant payload encryption/decryption.","archived":false,"fork":false,"pushed_at":"2025-07-31T12:37:02.000Z","size":225,"stargazers_count":18,"open_issues_count":0,"forks_count":11,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-07-31T16:27:24.926Z","etag":null,"topics":["decryption","encryption","field-level-encryption","fle","mastercard","openapi","python","python3"],"latest_commit_sha":null,"homepage":"https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/","language":"Python","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,"zenodo":null}},"created_at":"2019-02-21T15:01:14.000Z","updated_at":"2025-07-31T12:37:03.000Z","dependencies_parsed_at":"2024-02-20T13:49:05.132Z","dependency_job_id":"8551438c-fdbd-4aa2-a378-4366ad9c954a","html_url":"https://github.com/Mastercard/client-encryption-python","commit_stats":{"total_commits":98,"total_committers":13,"mean_commits":7.538461538461538,"dds":0.5510204081632653,"last_synced_commit":"5f8ecefabe293e15b2920fb103f87308a131882d"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/Mastercard/client-encryption-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/client-encryption-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-python/sbom","scorecard":{"id":90768,"data":{"date":"2025-08-11","repo":{"name":"github.com/Mastercard/client-encryption-python","commit":"76f4dc6129e44141a99c9024b530b7d44f5fda33"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.2,"checks":[{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"18 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/broken-links.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/python-publish.yml:8","Warn: no topLevel permission defined: .github/workflows/sonar.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/broken-links.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/broken-links.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/broken-links.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/broken-links.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/python-publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/sonar.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/sonar.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/sonar.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/sonar.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/sonar.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/sonar.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/Mastercard/client-encryption-python/test.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:23","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:24","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/sonar.yml:32","Warn: pipCommand not pinned by hash: .github/workflows/sonar.yml:33","Warn: pipCommand not pinned by hash: .github/workflows/sonar.yml:34","Warn: pipCommand not pinned by hash: .github/workflows/sonar.yml:35","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:32","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:33","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:34","Info:   0 out of   7 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of  10 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":5,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Info: 'branch protection settings apply to administrators' is required to merge on branch 'main'","Warn: 'stale review dismissal' is disabled on branch 'main'","Warn: required approving review count is 1 on branch 'main'","Warn: codeowners review is required - but no codeowners file found in repo","Warn: 'last push approval' is disabled on branch 'main'","Warn: no status checks found to merge onto branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":4,"reason":"6 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-225 / GHSA-6vqw-3v5j-54x4","Warn: Project is vulnerable to: GHSA-79v4-65xg-pq4g","Warn: Project is vulnerable to: GHSA-9v9h-cgj8-h64p","Warn: Project is vulnerable to: GHSA-h4gh-qq45-vh27","Warn: Project is vulnerable to: PYSEC-2025-49 / GHSA-5rjg-fvgr-3xxf","Warn: Project is vulnerable to: GHSA-cx63-2mw6-8hw5"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 2 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-15T07:52:52.377Z","repository_id":34902523,"created_at":"2025-08-15T07:52:52.378Z","updated_at":"2025-08-15T07:52:52.378Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274433831,"owners_count":25284427,"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","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","mastercard","openapi","python","python3"],"created_at":"2025-06-11T00:38:08.326Z","updated_at":"2025-09-10T08:37:23.900Z","avatar_url":"https://github.com/Mastercard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# client-encryption-python\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-python/workflows/Build%20\u0026%20Test/badge.svg)](https://github.com/Mastercard/client-encryption-python/actions?query=workflow%3A%22Build+%26+Test%22)\n[![](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_client-encryption-python\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=Mastercard_client-encryption-python)\n[![](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_client-encryption-python\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=Mastercard_client-encryption-python)\n[![](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_client-encryption-python\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=Mastercard_client-encryption-python)\n[![](https://github.com/Mastercard/client-encryption-python/workflows/broken%20links%3F/badge.svg)](https://github.com/Mastercard/client-encryption-python/actions?query=workflow%3A%22broken+links%3F%22)\n[![](https://img.shields.io/pypi/v/mastercard-client-encryption.svg?style=flat\u0026color=blue)](https://pypi.org/project/mastercard-client-encryption)\n[![](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/Mastercard/client-encryption-python/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  * [Performing Payload Encryption and Decryption](#performing-payload-encryption-and-decryption)\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\n## Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\nThis is the Python version of the Mastercard compliant payload encryption/decryption.\n\n### Compatibility \u003ca name=\"compatibility\"\u003e\u003c/a\u003e\nPython 3.8+\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### Installation \u003ca name=\"adding-the-libraries-to-your-project\"\u003e\u003c/a\u003e\nIf you want to use **mastercard-client-encryption** with [Python](https://www.python.org/), it is available through `PyPI`:\n- [https://pypi.org/project/mastercard-client-encryption](https://pypi.org/project/mastercard-client-encryption)\n\n**Adding the library to your project**\nInstall the library by pip:\n\n```bash\npip install mastercard-client-encryption\n```\n\nOr clone it from git:\n\n```bash\ngit clone https://github.com/Mastercard/client-encryption-python.git\n```\n\nand then execute from the repo folder:\n\n```bash\npython3 setup.py install\n```\n\nYou can then use it as a regular module:\n\n```python\n# Mastercard Encryption/Decryption\nfrom client_encryption.field_level_encryption_config import FieldLevelEncryptionConfig\nfrom client_encryption.field_level_encryption import encrypt_payload, decrypt_payload\n```\n\n```python\n# JWE Encryption/Decryption\nfrom client_encryption.jwe_encryption_config import JweEncryptionConfig\nfrom client_encryption.jwe_encryption import encrypt_payload, decrypt_payload\n```\n\n### Performing Payload Encryption and Decryption \u003ca name=\"performing-payload-encryption-and-decryption\"\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](#jwe-encryption-and-decryption)\n+ [Mastercard Encryption and Decryption](#mastercard-encryption-and-decryption)\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\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 `encrypt_payload` and `decrypt_payload` in the `jwe_encryption` module.\n\n- `encrypt_payload()` usage:\n\n```python\nconfig = JweEncryptionConfig(config_dictionary)\nencrypted_request_payload = encrypt_payload(body, config)\n```\n\n- `decrypt_payload()` usage:\n\n```python\nconfig = JweEncryptionConfig(config_dictionary)\ndecrypted_response_payload = decrypt_payload(body, config)\n```\n\n##### Configuring the JWE Encryption \u003ca name=\"configuring-the-jwe-encryption\"\u003e\u003c/a\u003e\n\n`jwe_encryption` needs a config dictionary to instruct how to decrypt/decrypt the payloads. Example:\n\n```json\n{\n  \"paths\": {\n    \"$\": {\n      \"toEncrypt\": {\n          \"path.to.foo\": \"path.to.encryptedFoo\"\n      },\n      \"toDecrypt\": {\n          \"path.to.encryptedFoo\": \"path.to.foo\"\n      }\n    }\n  },\n  \"encryptedValueFieldName\": \"encryptedData\",\n  \"encryptionCertificate\": \"./path/to/public.cert\",\n  \"decryptionKey\": \"./path/to/your/private.key\",\n}\n```\nYou can also pass in a PKCS12 file with the password to decrypt it:\n```json\n{\n  // .... rest of the config\n\n  \"decryptionKey\": \"./path/to/your/keyStore.p12\",\n  \"decryptionKeyPassword\": \"the-password\",\n}\n```\n\nThe above can be either stored to a file or passed to 'JweEncryptionConfig' as dictionary:\n```python\nconfig_dictionary = {\n                        \"paths\": {…},\n                        …\n                        \"decryptionKey\": \"./path/to/your/private.key\"\n                    }\n                    \nconfig = JweEncryptionConfig(config_dictionary)\n\nconfig_file_path = \"./config.json\"\nconfig = JweEncryptionConfig(config_file_path)\n```\n\n##### Performing JWE Encryption \u003ca name=\"performing-jwe-encryption\"\u003e\u003c/a\u003e\n\nCall `jwe_encryption.encrypt_payload()` with a JSON (dict) request payload, and optional `params` object.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n\n```python\nfrom client_encryption.session_key_params import SessionKeyParams\n\npayload = {\n  \"path\": {\n    \"to\": {\n      \"foo\": {\n        \"sensitiveField1\": \"sensitiveValue1\",\n        \"sensitiveField2\": \"sensitiveValue2\"\n      }\n    }\n  }\n}\n\nparams = SessionKeyParams.generate(conf) # optional\nrequest_payload = encrypt_payload(payload, config, params)\n```\n\nOutput:\n\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 `jwe_encryption.decrypt_payload()` with a JSON (dict) encrypted response payload.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n\n```python\nresponse = {\n  \"path\": {\n    \"to\": {\n      \"encryptedFoo\": {\n        \"encryptedValue\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM(...)==.Y+oPYKZEMTKyYcSIVEgtQw==\"\n      }\n    }\n  }\n}\n\nresponse_payload = decrypt_payload(response, config)\n\n```\n\nOutput:\n\n```json\n{\n  \"path\": {\n    \"to\": {\n      \"foo\": {\n        \"sensitiveField1\": \"sensitiveValue1\",\n        \"sensitiveField2\": \"sensitiveValue2\"\n      }\n    }\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\n##### Introduction \u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\nThe core methods responsible for payload encryption and decryption are `encrypt_payload` and `decrypt_payload` in the `field_level_encryption` module.\n\n- `encrypt_payload()` usage:\n\n```python\nconfig = FieldLevelEncryptionConfig(config_dictionary)\nencrypted_request_payload = encrypt_payload(body, config)\n```\n\n- `decrypt_payload()` usage:\n\n```python\nconfig = FieldLevelEncryptionConfig(config_dictionary)\ndecrypted_response_payload = decrypt_payload(body, config)\n```\n\n##### Configuring the Mastercard Encryption \u003ca name=\"configuring-the-mastercard-encryption\"\u003e\u003c/a\u003e\n\n`field_level_encryption` needs a config dictionary to instruct how to decrypt/decrypt the payloads. Example:\n\n```json\n{\n  \"paths\": {\n    \"$\": {\n      \"toEncrypt\": {\n          \"path.to.foo\": \"path.to.encryptedFoo\"\n      },\n      \"toDecrypt\": {\n          \"path.to.encryptedFoo\": \"path.to.foo\"\n      }\n    }\n  },\n  \"ivFieldName\": \"iv\",\n  \"encryptedKeyFieldName\": \"encryptedKey\",\n  \"encryptedValueFieldName\": \"encryptedData\",\n  \"dataEncoding\": \"hex\",\n  \"encryptionCertificate\": \"./path/to/public.cert\",\n  \"decryptionKey\": \"./path/to/your/private.key\",\n  \"oaepPaddingDigestAlgorithm\": \"SHA256\"\n}\n```\nYou can also pass in a PKCS12 file with the password to decrypt it:\n```json\n{\n  // .... rest of the config\n\n  \"decryptionKey\": \"./path/to/your/keyStore.p12\",\n  \"decryptionKeyPassword\": \"the-password\",\n}\n```\n\nThe above can be either stored to a file or passed to 'FieldLevelEncryptionConfig' as dictionary:\n```python\nconfig_dictionary = {\n                        \"paths\": {…},\n                        …\n                        \"decryptionKey\": \"./path/to/your/private.key\",\n                        \"oaepPaddingDigestAlgorithm\": \"SHA256\"\n                    }\n                    \nconfig = FieldLevelEncryptionConfig(config_dictionary)\n\nconfig_file_path = \"./config.json\"\nconfig = FieldLevelEncryptionConfig(config_file_path)\n```\n\n##### Performing Mastercard Encryption \u003ca name=\"performing-mastercard-encryption\"\u003e\u003c/a\u003e\n\nCall `field_level_encryption.encrypt_payload()` with a JSON (dict) request payload, and optional `params` object.\n\nExample using the configuration [above](#configuring-the-field-level-encryption):\n\n```python\nfrom client_encryption.session_key_params import SessionKeyParams\n\npayload = {\n  \"path\": {\n    \"to\": {\n      \"foo\": {\n        \"sensitiveField1\": \"sensitiveValue1\",\n        \"sensitiveField2\": \"sensitiveValue2\"\n      }\n    }\n  }\n}\n\nparams = SessionKeyParams.generate(conf) # optional\nrequest_payload = encrypt_payload(payload, config, params)\n```\n\nOutput:\n\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"encryptedFoo\": {\n                \"iv\": \"7f1105fb0c684864a189fb3709ce3d28\",\n                \"encryptedKey\": \"67f467d1b653d98411a0c6d3c…ffd4c09dd42f713a51bff2b48f937c8\",\n                \"encryptedData\": \"b73aabd267517fc09ed72455c2…dffb5fa04bf6e6ce9ade1ff514ed6141\",\n                \"publicKeyFingerprint\": \"80810fc13a8319fcf0e2e…82cc3ce671176343cfe8160c2279\",\n                \"oaepHashingAlgorithm\": \"SHA256\"\n            }\n        }\n    }\n}\n```\n\n##### Performing Mastercard Decryption \u003ca name=\"performing-mastercard-decryption\"\u003e\u003c/a\u003e\n\nCall `field_level_encryption.decrypt_payload()` with a JSON (dict) encrypted response payload.\n\nExample using the configuration [above](#configuring-the-field-level-encryption):\n\n```python\nresponse = {\n  \"path\": {\n    \"to\": {\n      \"encryptedFoo\": {\n        \"iv\": \"e5d313c056c411170bf07ac82ede78c9\",\n        \"encryptedKey\": \"e3a56746c0f9109d18b3a2652b76…f16d8afeff36b2479652f5c24ae7bd\",\n        \"encryptedData\": \"809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f\",\n        \"oaepHashingAlgorithm\": \"SHA256\",\n        \"publicKeyFingerprint\": \"80810fc13a8319fcf0e2e…3ce671176343cfe8160c2279\"\n      }\n    }\n  }\n}\n\nresponse_payload = decrypt_payload(response, config)\n\n```\n\nOutput:\n\n```json\n{\n  \"path\": {\n    \"to\": {\n      \"foo\": {\n        \"sensitiveField1\": \"sensitiveValue1\",\n        \"sensitiveField2\": \"sensitiveValue2\"\n      }\n    }\n  }\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 **client-encryption-python** library provides a method you can use to integrate the OpenAPI generated client with this library:\n```python\nfrom client_encryption.api_encryption import add_encryption_layer\n\nconfig = {\n  \"paths\": {\n    \"$\": {\n      …\n    }\n  },\n  \"encryptionCertificate\": \"path/to/cert.pem\",\n  …\n  \"decryptionKey\": \"path/to/to/key.pem\"\n}\n\nadd_encryption_layer(api_client, config)\n```\n\nAlternatively you can pass the configuration by a json file:\n```python\nfrom client_encryption.api_encryption import add_encryption_layer\n\nadd_encryption_layer(api_client, \"path/to/my/config.json\")\n```\n\nThis method will add the Mastercard/JWE encryption in the generated OpenApi client, taking care of encrypting request and decrypting response payloads, but also of updating HTTP headers when needed, automatically, without manually calling `encrypt_payload()`/`decrypt_payload()` functions for each API request or response.\n\n##### OpenAPI Generator \u003ca name=\"openapi-generator\"\u003e\u003c/a\u003e\n\nOpenAPI client can be generated, starting from your OpenAPI Spec using the following command:\n\n```shell\nopenapi-generator-cli generate -i openapi-spec.yaml -l python -o out\n```\n\nThe client library will be generated in the `out` folder.\n\nSee also: \n\n- [OpenAPI Generator CLI Installation](https://openapi-generator.tech/docs/installation/)\n\n##### Usage of the `api_encryption.add_encryption_layer`:\n\nTo use it:\n\n1. Generate the [OpenAPI client](#openapi-generator)\n\n2. Import the **mastercard-client-encryption** module and the generated OpenAPI client\n\n   ```python\n   from client_encryption.api_encryption import add_encryption_layer\n   from openapi_client.api_client import ApiClient # import generated OpenAPI client\n   ```\n\n3. Add the encryption layer to the generated client:\n\n   ```python\n   # Create a new instance of the generated client\n   api_client = ApiClient()\n   # Enable encryption\n   add_encryption_layer(api_client, \"path/to/my/config.json\")\n   ```\n\n4. Use the `ApiClient` instance with Encryption enabled:\n\n   Example:\n\n   ```python\n   request_body = {…}\n   response = MyServiceApi(api_client).do_some_action_post(body=request_body)\n   # requests and responses will be automatically encrypted and decrypted\n   # accordingly with the configuration object used\n   \n   # … use the (decrypted) response object here …\n   decrypted = response.json()\n\n   ```\n\n##### Integrating with `mastercard-client-encryption` module:\n\nIn order to use both signing and encryption layers, a defined order is required as signing library should calculate the hash of the encrypted payload.\nAccording to the above the signing layer must be applied first in order to work as inner layer. The outer layer - encryption - will be executed first, providing the signing layer the encrypted payload to sign.\n\n1. Generate the [OpenAPI client](#openapi-generator)\n\n2. Import both **mastercard-client-encryption** and **mastercard-client-encryption** modules and the generated OpenAPI client\n\n   ```python\n   from oauth1.signer_interceptor import add_signing_layer\n   from client_encryption.api_encryption import add_encryption_layer\n   from openapi_client.api_client import ApiClient # import generated OpenAPI client\n   ```\n\n3. Add the authentication layer to the generated client:\n   ```python\n   # Create a new instance of the generated client\n   api_client = ApiClient()\n\n   # Enable authentication\n   add_signing_layer(api_client, key_file, key_password, consumer_key)\n   ```\n     \n4. Then add the encryption layer:\n   ```python\n   add_encryption_layer(api_client, \"path/to/my/config.json\")\n   ```\n\n5. Use the `ApiClient` instance with Authentication and Encryption both enabled:\n   ```python\n   response = MyServiceApi(api_client).do_some_action_post(body=request_body)\n   decrypted = response.json()\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fclient-encryption-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fclient-encryption-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fclient-encryption-python/lists"}