mastercard-encryption-go

README

client-encryption-go

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Adding the Libraries to Your Project
  • Loading the Encryption Certificate
  • Loading the Decryption Key
  • Performing Payload Encryption and Decryption

Overview

Library for Mastercard API compliant JWE payload encryption/decryption.

Compatibility

Go 1.15+

References

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

Usage

Prerequisites

Before using this library, you will need to set up a project in the Mastercard Developers Portal.

As part of this set up, you'll receive:

• A public request encryption certificate (aka Client Encryption Keys)
• A private response decryption key (aka Mastercard Encryption Keys)

Installation

import github.com/ldmtam/mastercard-encryption-go

Loading the Encryption Certificate

A Certificate can be created by calling the utils.LoadSigningKey function:

import "github.com/ldmtam/mastercard-encryption-go/utils"

//…
encryptionCertificate, err := utils.LoadEncryptionCertificate("<insert certificate file path>")
//…

Supported certificate formats: PEM, DER.

Loading the Decryption Key

From a PKCS#12 Key Store

A PrivateKey can be created from a PKCS#12 key store by calling utils.LoadDecryptionKey the following way:

import "github.com/ldmtam/mastercard-encryption-go/utils"

//…
decryptionKey, err := utils.LoadDecryptionKey(
	"<insert PKCS#12 key file path>",
    "<insert key password>")
//…

From an Unencrypted Key File

A PrivateKey can be created from an unencrypted key file by calling utils.LoadUnencryptedDecryptionKey the following way:

import "github.com/ldmtam/mastercard-encryption-go/utils"

//…
decryptionKey, err := utils.LoadUnencryptedDecryptionKey("<insert key file path>")
//…

Supported RSA key formats:

• PKCS#1 PEM (starts with "-----BEGIN RSA PRIVATE KEY-----")
• PKCS#8 PEM (starts with "-----BEGIN PRIVATE KEY-----")
• Binary DER-encoded PKCS#8

Performing Payload Encryption and Decryption

• Introduction
• Configuring the JWE Encryption
• Performing JWE Encryption
• Performing JWE Decryption
• Encrypting Entire Payloads
• Decrypting Entire Payloads

• Introduction

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 encryption package.

• encryptPayload usage:

import "github.com/ldmtam/mastercard-encryption-go/encryption"
// …

encryptedPayload := encryption.EncryptPayload(payload, *config)

• decryptPayload usage:

import "github.com/ldmtam/mastercard-encryption-go/encryption"
// …

decryptedPayload := encryption.DecryptPayload(payload, *config)

• Configuring the JWE Encryption

Use the JWEConfigBuilder to create JWEConfig instances. Example:

import "github.com/ldmtam/mastercard-encryption-go/jwe"
// …

cb := jwe.NewJWEConfigBuilder()
config := cb.WithDecryptionKey(decryptionKey).
    WithCertificate(encryptionCertificate).
    WithEncryptedValueFieldName("encryptedData").
    Build()

• Performing JWE Encryption

Call encryption.EncryptPayload with a JSON request payload and a JWEConfig instance.

Example using the configuration above:

//…
payload := "{" +
    "    \"path\": {" +
    "        \"to\": {" +
    "            \"foo\": {" +
    "                \"sensitiveField1\": \"sensitiveValue1\"," +
    "                \"sensitiveField2\": \"sensitiveValue2\"" +
    "            }" +
    "        }" +
    "    }" +
    "}"
encryptedPayload := encryption.EncryptPayload(
    payload,
    config,
    []string{"path", "to", "foo"}, // in path
    []string{"path", "to", "encryptedFoo"}, // out path
)
//…

Output:

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

• Performing JWE Decryption

Call encryption.decryptPayload with a JSON response payload and a JWEConfig instance.

Example using the configuration above:

encryptedPayload := "{" +
    "    \"path\": {" +
    "        \"to\": {" +
    "            \"encryptedFoo\": {" +
    "                \"encryptedData\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"" +
    "            }" +
    "        }" +
    "    }" +
    "}"
decryptedPayload := encryption.DecryptPayload(
    encryptedPayload,
    config,
    []string{"path", "to", "encryptedFoo"}, // in path
    []string{"path", "to", "foo"}, // out path
)

Output:

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