{"id":28577510,"url":"https://github.com/mastercard/client-encryption-go","last_synced_at":"2025-07-07T11:06:47.786Z","repository":{"id":45721634,"uuid":"514213181","full_name":"Mastercard/client-encryption-go","owner":"Mastercard","description":"Library for Mastercard API compliant payload encryption/decryption.","archived":false,"fork":false,"pushed_at":"2024-09-02T14:13:00.000Z","size":57,"stargazers_count":14,"open_issues_count":0,"forks_count":8,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-31T09:36:53.901Z","etag":null,"topics":["decryption","encryption","fle","go","jwe","mastercard","openapi"],"latest_commit_sha":null,"homepage":"","language":"Go","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}},"created_at":"2022-07-15T09:35:12.000Z","updated_at":"2024-10-03T11:22:12.000Z","dependencies_parsed_at":"2024-02-02T11:26:08.033Z","dependency_job_id":null,"html_url":"https://github.com/Mastercard/client-encryption-go","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/client-encryption-go/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fclient-encryption-go/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177332,"owners_count":22817349,"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","fle","go","jwe","mastercard","openapi"],"created_at":"2025-06-11T00:38:00.812Z","updated_at":"2025-06-11T00:38:52.103Z","avatar_url":"https://github.com/Mastercard.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# client-encryption-go\n[![](https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-dark.svg)](https://developer.mastercard.com/)\n\n## Table of Contents\n- [Overview](#overview)\n    * [Compatibility](#compatibility)\n    * [References](#references)\n    * [Versioning and Deprecation Policy](#versioning)\n- [Usage](#library-usage)\n    * [Prerequisites](#prerequisites)\n    * [Installation](#installation)\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    * [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\nGo 1.15+\n\n### References \u003ca name=\"references\"\u003e\u003c/a\u003e\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=\"library-usage\"\u003e\u003c/a\u003e\n\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=\"installation\"\u003e\u003c/a\u003e\n\n####\n```go\nimport github.com/mastercard/client-encryption-go\n```\n\n### Loading the Encryption Certificate \u003ca name=\"loading-the-encryption-certificate\"\u003e\u003c/a\u003e\nA `Certificate` can be created by calling the `utils.LoadEncryptionCertificate` function:\n```go\nimport \"github.com/mastercard/client-encryption-go/utils\"\n\n//…\nencryptionCertificate, err := utils.LoadEncryptionCertificate(\"\u003cinsert certificate file path\u003e\")\n//…\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` can be created from a PKCS#12 key store by calling `utils.LoadDecryptionKey` the following way:\n```go\nimport \"github.com/mastercard/client-encryption-go/utils\"\n\n//…\ndecryptionKey, err := utils.LoadDecryptionKey(\n\t\"\u003cinsert PKCS#12 key file path\u003e\",\n    \"\u003cinsert key password\u003e\")\n//…\n```\n\n#### From an Unencrypted Key File\n\nA `PrivateKey` can be created from an unencrypted key file by calling `utils.LoadUnencryptedDecryptionKey` the following way:\n```go\nimport \"github.com/mastercard/client-encryption-go/utils\"\n\n//…\ndecryptionKey, err := utils.LoadUnencryptedDecryptionKey(\"\u003cinsert key file path\u003e\")\n//…\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\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+ [Encrypting Entire Payloads](#encrypting-entire-payloads-jwe)\n+ [Decrypting Entire Payloads](#decrypting-entire-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 `encryption` package.\n\n* `EncryptPayload` usage:\n```go\nimport \"github.com/mastercard/client-encryption-go/encryption\"\n// …\n\nencryptedPayload := encryption.EncryptPayload(payload, *config)\n```\n\n* `DecryptPayload` usage:\n```go\nimport \"github.com/mastercard/client-encryption-go/encryption\"\n// …\n\ndecryptedPayload := encryption.DecryptPayload(payload, *config)\n```\n\n#### • Configuring the JWE Encryption \u003ca name=\"configuring-the-jwe-encryption\"\u003e\u003c/a\u003e\n\nUse the `JWEConfigBuilder` to create `JWEConfig` instances. Example:\n```go\nimport \"github.com/mastercard/client-encryption-go/jwe\"\n// …\n\ncb := jwe.NewJWEConfigBuilder()\nconfig := cb.WithDecryptionKey(decryptionKey).\n    WithCertificate(encryptionCertificate).\n    WithEncryptionPath(\"$.path.to.foo\", \"$.path.to.encryptedFoo\").\n    WithDecryptionPath(\"$.path.to.encryptedFoo.encryptedData\", \"$.path.to.foo\").\n    WithEncryptedValueFieldName(\"encryptedData\").\n    Build()\n```\n\n#### • Performing JWE Encryption \u003ca name=\"performing-jwe-encryption\"\u003e\u003c/a\u003e\n\nCall `encryption.EncryptPayload` with a JSON request payload and a `JWEConfig` instance.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n```go\n//…\npayload := \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"foo\\\": {\" +\n    \"                \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"                \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\"\nencryptedPayload := encryption.EncryptPayload(payload, config)\n//…\n```\n\nOutput:\n```json\n{\n    \"path\": {\n        \"to\": {\n            \"encryptedFoo\": {\n                \"encryptedData\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"\n            }\n        }\n    }\n}\n```\n\n#### • Performing JWE Decryption \u003ca name=\"performing-jwe-decryption\"\u003e\u003c/a\u003e\n\nCall `encryption.DecryptPayload` with a JSON response payload and a `JWEConfig` instance.\n\nExample using the configuration [above](#configuring-the-jwe-encryption):\n```go\nencryptedPayload := \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"encryptedFoo\\\": {\" +\n    \"                \\\"encryptedData\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\"\ndecryptedPayload := encryption.DecryptPayload(payload, config)\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```go\nimport \"github.com/mastercard/client-encryption-go/jwe\"\n// …\n\ncb := jwe.NewJWEConfigBuilder()\nconfig := cb.WithCertificate(encryptionCertificate).\n    WithEncryptionPath(\"$\", \"$\").\n    // …\n    Build()\n```\n\nExample:\n```go\npayload := \"{\" +\n    \"    \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"    \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"}\"\nencryptedPayload := encryption.EncryptPayload(payload, config)\n```\n\nOutput:\n```json\n{\n    \"encryptedData\": \"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```go\nimport \"github.com/mastercard/client-encryption-go/jwe\"\n// …\n\ncb := jwe.NewJWEConfigBuilder()\nconfig := cb.WithDecryptionKey(decryptionKey).\n    WithDecryptionPath(\"$\", \"$\").\n    // …\n    Build()\n```\n\nExample:\n```go\nencryptedPayload := \"{\" +\n    \"  \\\"encryptedData\\\": \\\"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\\\"\" +\n    \"}\"\npayload = encryption.DecryptPayload(encryptedPayload, config)\n```\n\nOutput:\n```json\n{\n    \"sensitiveField1\": \"sensitiveValue1\",\n    \"sensitiveField2\": \"sensitiveValue2\"\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=\"mastercard-introduction\"\u003e\u003c/a\u003e\n\nThe core methods responsible for payload encryption and decryption are `EncryptPayload` and `DecryptPayload` in the `mastercard_encryption` package.\n\n* `EncryptPayload` usage:\n```go\nimport \"github.com/mastercard/client-encryption-go/mastercard_encryption\"\n// …\n\nencryptedPayload := encryption.EncryptPayload(payload, *config)\n```\n\n* `DecryptPayload` usage:\n```go\nimport \"github.com/mastercard/client-encryption-go/mastercard_encryption\"\n// …\n\ndecryptedPayload := encryption.DecryptPayload(payload, *config)\n```\n\n#### • Configuring the Mastercard Encryption \u003ca name=\"#configuring-the-mastercard-encryption\"\u003e\u003c/a\u003e\n\nUse the `FieldLevelEncryptionConfigBuilder` to create `FieldLevelEncryptionConfig` instances. Example:\n```go\nimport \"github.com/mastercard/client-encryption-go/field_level_encryption\"\n// …\n\ncb := field_level_encryption.NewFieldLevelEncryptionConfigBuilder()\nconfig, err := cb.WithDecryptionKey(decryptionKey).\n    WithEncryptionCertificate(encryptionCertificate).\n    WithEncryptionPath(\"$.path.to.foo\", \"$.path.to.encryptedFoo\").\n    WithDecryptionPath(\"$.path.to.encryptedFoo.encryptedData\", \"$.path.to.foo\").\n    WithEncryptedValueFieldName(\"encryptedData\").\n    WithEncryptedKeyFieldName(\"encryptedKey\").\n    WithIvFieldName(\"iv\").\n    WithFieldValueEncoding(field_level_encryption.HEX).\n    WithOaepPaddingDigestAlgorithm(field_level_encryption.SHA256).\n    Build()\n```\n\n##### Performing Mastercard Encryption \u003ca name=\"performing-mastercard-encryption\"\u003e\u003c/a\u003e\n\nCall `mastercard_encryption.EncryptPayload` with a JSON request payload and a `FieldLevelEncryptionConfig` instance.\n\nExample using the configuration [above](#configuring-the-mastercard-encryption):\n```go\n//…\npayload := \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"foo\\\": {\" +\n    \"                \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"                \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\"\nencryptedPayload := mastercard_encryption.EncryptPayload(payload, config)\n//…\n```\n\nOutput:\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 `mastercard_encryption.DecryptPayload` with a JSON response payload and a `FieldLevelEncryptionConfig` instance.\n\nExample using the configuration [above](#configuring-the-mastercard-encryption):\n```go\nresponse := \"{\" +\n    \"    \\\"path\\\": {\" +\n    \"        \\\"to\\\": {\" +\n    \"            \\\"encryptedFoo\\\": {\" +\n    \"               \\\"iv\\\": \\\"e5d313c056c411170bf07ac82ede78c9\\\",\" +\n\t\"               \\\"encryptedKey\": \"e3a56746c0f9109d18b3a2652b76…f16d8afeff36b2479652f5c24ae7bd\\\",\" +\n    \"               \\\"encryptedData\\\": \\\"809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f\\\",\" +\n    \"               \\\"oaepHashingAlgorithm\\\": \\\"SHA256\\\",\" +\n    \"               \\\"publicKeyFingerprint\\\": \\\"80810fc13a8319fcf0e2e…3ce671176343cfe8160c2279\\\"\" +\n    \"            }\" +\n    \"        }\" +\n    \"    }\" +\n    \"}\"\ndecryptedPayload := encryption.DecryptPayload(response, config)\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### 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 `interceptor` package will provide you with an interceptor you can use when configuring your API client.\nThis interceptor will take care of encrypting request and decrypting response payloads.\n\n#### OpenAPI Generator\nClient libraries can be generated using the following command:\n\n```openapi-generator-cli generate -i openapi-spec.yaml -g go -o out```\n\nSee also:\n* [OpenAPI Generator CLI Installation](https://openapi-generator.tech/docs/installation)\n* [Config Options for go](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/go.md)\n\n#### Usage\nThe interceptor package supports 2 types of encryption. \n1. Encryption with OAuth1.0a authentication\n2. Encryption without authentication\n\n#### Encryption with OAuth1.0a Authentication\nRequests can be encrypted, with OAuth authentication as follows:\n\n```go\nimport (\n    oauth \"github.com/mastercard/oauth1-signer-go\"\n    \"github.com/mastercard/client-encryption-go/interceptor\"\n)\n\ncb := jwe.NewJWEConfigBuilder()\njweConfig := cb.WithDecryptionKey(decryptionKey).\n    WithCertificate(encryptionCertificate).\n    WithEncryptionPath(\"$\", \"$\").\n\t// …\n\tBuild()\n\nconfiguration := openapi.NewConfiguration()\n\n// Signer from the oauth-signer-go library used for OAuth1.0a\nsigner := oauth.Signer{ConsumerKey: \"\u003cconsumer-key\u003e\", SigningKey: \"\u003csigner-key\u003e\"}\nencryptionClient, _ := interceptor.GetHttpClient(*jweConfig, signer.Sign)\nconfiguration.HTTPClient = encryptionClient\napiClient := openapi.NewAPIClient(configuration)\n\nserviceApi := apiClient.ServiceApi\n// …\n```\n\nSee also:\n* [Mastercard OAuth Signer Library](https://github.com/Mastercard/oauth1-signer-go)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fclient-encryption-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fclient-encryption-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fclient-encryption-go/lists"}