Download the PHP package mastercard/client-encryption without Composer

client-encryption-php

Table of Contents

• Overview
  • Compatibility
  • References
  • Versioning and Deprecation Policy
• Usage
  • Prerequisites
  • Adding the Library to Your Project
  • Loading the Encryption Certificate
  • Loading the Decryption Key
  • Performing Field Level Encryption and Decryption
  • Performing JWE Encryption and Decryption
  • Integrating with OpenAPI Generator API Client Libraries

Overview

Library for Mastercard API compliant payload encryption/decryption.

Compatibility

PHP 7.0+

References

Versioning and Deprecation Policy

• Mastercard Versioning and Deprecation Policy

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)

Adding the Library to Your Project

Loading the Encryption Certificate

A certificate resource can be created from a file by calling EncryptionUtils::loadEncryptionCertificate:

Supported certificate formats: PEM, DER.

Loading the Decryption Key

From a PKCS#12 Key Store

A private key resource can be created from a PKCS#12 key store by calling EncryptionUtils::loadDecryptionKey the following way:

From an Unencrypted Key File

A private key resource can be created from an unencrypted key file by calling EncryptionUtils::loadDecryptionKey the following way:

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 Field Level Encryption and Decryption

• Introduction
• Configuring the Field Level Encryption
• Performing Encryption
• Performing Decryption
• Encrypting Entire Payloads
• Decrypting Entire Payloads
• Using HTTP Headers for Encryption Params

Introduction

The core methods responsible for payload encryption and decryption are encryptPayload and decryptPayload in the FieldLevelEncryption class.

• encryptPayload usage:

• decryptPayload usage:

Configuring the Field Level Encryption

Use the FieldLevelEncryptionConfigBuilder to create FieldLevelEncryptionConfig instances. Example:

See also:

• FieldLevelEncryptionConfig.php for all config options
• Service Configurations for Client Encryption PHP

Performing Encryption

Call FieldLevelEncryption::encryptPayload with a JSON request payload and a FieldLevelEncryptionConfig instance.

Example using the configuration above:

Output:

Performing Decryption

Call FieldLevelEncryption::decryptPayload with a JSON response payload and a FieldLevelEncryptionConfig instance.

Example using the configuration above:

Output:

Encrypting Entire Payloads

Entire payloads can be encrypted using the '$' operator as encryption path:

Example:

Output:

Decrypting Entire Payloads

Entire payloads can be decrypted using the '$' operator as decryption path:

Example:

Output:

Using HTTP Headers for Encryption Params

In the sections above, encryption parameters (initialization vector, encrypted symmetric key, etc.) are part of the HTTP payloads.

Here is how to configure the library for using HTTP headers instead.

Configuration for Using HTTP Headers

Call with{Param}HeaderName instead of with{Param}FieldName when building a FieldLevelEncryptionConfig instance. Example:

See also:

• FieldLevelEncryptionConfig.php for all config options
• Service Configurations for Client Encryption PHP

Encrypting Using HTTP Headers

Encryption can be performed using the following steps:

1. Generate parameters by calling FieldLevelEncryptionParams::generate:

2. Update the request headers:

3. Call encryptPayload with params:

Example using the configuration above:

Output:

Decrypting Using HTTP Headers

Decryption can be performed using the following steps:

1. Read the response headers:

2. Create a FieldLevelEncryptionParams instance:

3. Call decryptPayload with params:

Example using the configuration above:

Output:

Performing JWE Encryption and Decryption

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

Introduction

The core methods responsible for payload encryption and decryption are encryptPayload and decryptPayload in the JweEncryption class.

• encryptPayload usage:

• decryptPayload usage:

Configuring the JWE Encryption

Use the JweEncryptionConfigBuilder to create JweEncryptionConfig instances. Example:

Note: If withEncryptedValueFieldName is left blank, the value will default to encryptedData

See also:

• JweConfig.php for all config options
• Service Configurations for Client Encryption PHP

Performing Encryption

Call JweEncryption::encryptPayload with a JSON request payload and a JweEncryptionConfig instance.

Example using the configuration above:

Output:

Performing Decryption

Call JweEncryption::decryptPayload with a JSON response payload and a JweEncryptionConfig instance.

Example using the configuration above:

Output:

Encrypting Entire Payloads

Entire payloads can be encrypted using the '$' operator as encryption path:

Example:

Output:

Decrypting Entire Payloads

Entire payloads can be decrypted using the '$' operator as decryption path:

Example:

Output:

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.

This project provides you with some interceptor classes you can use when configuring your API client. These classes will take care of encrypting request and decrypting response payloads, but also of updating HTTP headers when needed.

Generators currently supported:

• php

php

OpenAPI Generator

Client libraries can be generated using the following command:

See also:

• OpenAPI Generator CLI Installation
• CONFIG OPTIONS for php

Usage of the PsrHttpMessageEncryptionInterceptor for Field Level Encryption

Usage of the PsrHttpMessageEncryptionInterceptor for JWE Encryption