README
¶
client-encryption-go
Table of Contents
Overview
Library for Mastercard API compliant JWE payload encryption/decryption.
Compatibility
Go 1.15+
References
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/Duong2903/client-encryption-go
Loading the Encryption Certificate
A Certificate can be created by calling the utils.LoadSigningKey function:
import "github.com/Duong2903/client-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/Duong2903/client-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/Duong2903/client-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.
encryptPayloadusage:
import "github.com/Duong2903/client-encryption-go/encryption"
// …
encryptedPayload := encryption.EncryptPayload(payload, *config)
decryptPayloadusage:
import "github.com/Duong2903/client-encryption-go/encryption"
// …
decryptedPayload := encryption.DecryptPayload(payload, *config)
• Configuring the JWE Encryption
Use the JWEConfigBuilder to create JWEConfig instances. Example:
import "github.com/Duong2903/client-encryption-go/jwe"
// …
cb := jwe.NewJWEConfigBuilder()
config := cb.WithDecryptionKey(decryptionKey).
WithCertificate(encryptionCertificate).
WithEncryptionPath("path.to.foo", "path.to.encryptedFoo").
WithDecryptionPath("path.to.encryptedFoo", "path.to.foo").
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)
//…
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(payload, config)
Output:
{
"path": {
"to": {
"foo": {
"sensitiveField1": "sensitiveValue1",
"sensitiveField2": "sensitiveValue2"
}
}
}
}
• Encrypting Entire Payloads
Entire payloads can be encrypted using the "$" operator as encryption path:
import "github.com/Duong2903/client-encryption-go/jwe"
// …
cb := jwe.NewJWEConfigBuilder()
config := cb.WithCertificate(encryptionCertificate).
WithEncryptionPath("$", "$").
// …
Build()
Example:
payload := "{" +
" \"sensitiveField1\": \"sensitiveValue1\"," +
" \"sensitiveField2\": \"sensitiveValue2\"" +
"}"
encryptedPayload := encryption.EncryptPayload(payload, config)
Output:
{
"encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
}
• Decrypting Entire Payloads
Entire payloads can be decrypted using the "$" operator as decryption path:
import "github.com/Duong2903/client-encryption-go/jwe"
// …
cb := jwe.NewJWEConfigBuilder()
config := cb.WithDecryptionKey(decryptionKey).
WithDecryptionPath("$", "$").
// …
Build()
Example:
encryptedPayload := "{" +
" \"encryptedData\": \"eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw\"" +
"}"
payload = encryption.decryptPayload(encryptedPayload, config)
Output:
{
"sensitiveField1": "sensitiveValue1",
"sensitiveField2": "sensitiveValue2"
}
Integrating with OpenAPI Generator API Client Libraries
OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.
The interceptor package will provide you with an interceptor you can use when configuring your API client.
This interceptor will take care of encrypting request and decrypting response payloads.
OpenAPI Generator
Client libraries can be generated using the following command:
openapi-generator-cli generate -i openapi-spec.yaml -g go -o out
See also:
Usage
The interceptor package supports 2 types of encryption.
- Encryption with OAuth1.0a authentication
- Encryption without authentication
Encryption with OAuth1.0a Authentication
Requests can be encrypted, with OAuth authentication as follows:
import (
oauth "github.com/mastercard/oauth1-signer-go"
"github.com/Duong2903/client-encryption-go/interceptor"
)
cb := jwe.NewJWEConfigBuilder()
jweConfig := cb.WithDecryptionKey(decryptionKey).
WithCertificate(encryptionCertificate).
WithEncryptionPath("$", "$").
// …
Build()
configuration := openapi.NewConfiguration()
// Signer from the oauth-signer-go library used for OAuth1.0a
signer := oauth.Signer{ConsumerKey: "<consumer-key>", SigningKey: "<signer-key>"}
encryptionClient, _ := interceptor.GetHttpClient(*jweConfig, signer.Sign)
configuration.HTTPClient = encryptionClient
apiClient := openapi.NewAPIClient(configuration)
serviceApi := apiClient.ServiceApi
// …
See also:
Encryption without Authentication
Requests can be encrypted, without authentication as follows:
import (
"github.com/Duong2903/client-encryption-go/interceptor"
)
cb := jwe.NewJWEConfigBuilder()
jweConfig := cb.WithDecryptionKey(decryptionKey).
WithCertificate(encryptionCertificate).
WithEncryptionPath("$", "$").
// …
Build()
configuration := openapi.NewConfiguration()
encryptionClient, _ := interceptor.GetHttpClient(*jweConfig, nil)
configuration.HTTPClient = encryptionClient
apiClient := openapi.NewAPIClient(configuration)
serviceApi := apiClient.ServiceApi
// …
Directories
¶
| Path | Synopsis |
|---|---|
|
Package interceptor handles oauth signing of every http request before sending.
|
Package interceptor handles oauth signing of every http request before sending. |