client-encryption-nodejs

Overview

NodeJS library for Mastercard API compliant payload encryption/decryption.

Compatibility

NodeJS 6.12.3+
NodeJS 16.x (JWE features)

There shouldn't be any Node compatibility issues with this package, but it's a good idea to keep your Node versions up-to-date. It is recommended that you use one of the LTS Node.js releases, or one of the more general recent releases. A Node version manager such as nvm (Mac and Linux) or nvm-windows is a good way to stay on top of this.

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)

Installation

If you want to use mastercard-client-encryption with Node.js, it is available through npm:

https://npmjs.org/package/mastercard-client-encryption

Adding the library to your project:

npm install mastercard-client-encryption

You can then use it as a regular module:

const clientEncryption = require("mastercard-client-encryption");

Performing Field Level Encryption and Decryption

Introduction
Configuring the Field Level Encryption
Performing Encryption
Performing Decryption

Introduction

The core methods responsible for payload encryption and decryption are encryptData and decryptData in the FieldLevelEncryption class.

encrypt() usage:

const fle = new clientEncryption.FieldLevelEncryption(config);
// …
let encryptedRequestPayload = fle.encrypt(endpoint, header, body);

decrypt() usage:

const fle = new clientEncryption.FieldLevelEncryption(config);
// …
let responsePayload = fle.decrypt(encryptedResponsePayload);

Configuring the Field Level Encryption

FieldLevelEncryption needs a config object to instruct how to decrypt/decrypt the payloads. Example:

const config = {
  paths: [
    {
      path: "/resource",
      toEncrypt: [
        {
          /* path to element to be encrypted in request json body */
          element: "path.to.foo",
          /* path to object where to store encryption fields in request json body */
          obj: "path.to.encryptedFoo",
        },
      ],
      toDecrypt: [
        {
          /* path to element where to store decrypted fields in response object */
          element: "path.to.encryptedFoo",
          /* path to object with encryption fields */
          obj: "path.to.foo",
        },
      ],
    },
  ],
  ivFieldName: "iv",
  encryptedKeyFieldName: "encryptedKey",
  encryptedValueFieldName: "encryptedData",
  dataEncoding: "hex",
  encryptionCertificate: "./path/to/public.cert",
  privateKey: "./path/to/your/private.key",
  oaepPaddingDigestAlgorithm: "SHA-256",
};

Performing Encryption

Call FieldLevelEncryption.encrypt() with a JSON request payload, and optional header object.

Example using the configuration above:

const payload = {
  path: {
    to: {
      foo: {
        sensitive: "this is a secret!",
        sensitive2: "this is a super-secret!",
      },
    },
  },
};
const fle = new (require("mastercard-client-encryption").FieldLevelEncryption)(
  config
);
// …
let responsePayload = fle.encrypt("/resource1", header, payload);

Output:

{
  "path": {
    "to": {
      "encryptedFoo": {
        "iv": "7f1105fb0c684864a189fb3709ce3d28",
        "encryptedKey": "67f467d1b653d98411a0c6d3c…ffd4c09dd42f713a51bff2b48f937c8",
        "encryptedData": "b73aabd267517fc09ed72455c2…dffb5fa04bf6e6ce9ade1ff514ed6141",
        "publicKeyFingerprint": "80810fc13a8319fcf0e2e…82cc3ce671176343cfe8160c2279",
        "oaepHashingAlgorithm": "SHA256"
      }
    }
  }
}

Performing Decryption

Call FieldLevelEncryption.decrypt() with an (encrypted) response object with the following fields:

body: json payload
request.url: requesting url
header: optional, header object

Example using the configuration above:

const response = {};
response.request = { url: "/resource1" };
response.body = {
  path: {
    to: {
      encryptedFoo: {
        iv: "e5d313c056c411170bf07ac82ede78c9",
        encryptedKey:
          "e3a56746c0f9109d18b3a2652b76…f16d8afeff36b2479652f5c24ae7bd",
        encryptedData:
          "809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f",
        oaepHashingAlgorithm: "SHA256",
        publicKeyFingerprint: "80810fc13a8319fcf0e2e…3ce671176343cfe8160c2279",
      },
    },
  },
};
const fle = new (require("mastercard-client-encryption").FieldLevelEncryption)(
  config
);
let responsePayload = fle.decrypt(response);

Output:

{
  "path": {
    "to": {
      "foo": {
        "sensitive": "this is a secret",
        "sensitive2": "this is a super secret!"
      }
    }
  }
}

Performing JWE Encryption and Decryption

JWE Encryption and Decryption

Introduction
Configuring the JWE Encryption
Performing JWE Encryption
Performing JWE Decryption
Encrypting Entire Payloads
Decrypting Entire Payloads
First Level Field Encryption and Decryption

• Introduction

This library uses JWE compact serialization for the encryption of sensitive data. The core methods responsible for payload encryption and decryption are encryptData and decryptData in the JweEncryption class.

encryptPayload usage:

const jwe = new clientEncryption.JweEncryption(config);
// …
let encryptedRequestPayload = jwe.encrypt(endpoint, header, body);

decryptPayload usage:

const jwe = new clientEncryption.JweEncryption(config);
// …
let responsePayload = jwe.decrypt(encryptedResponsePayload);

• Configuring the JWE Encryption

JweEncryption needs a config object to instruct how to decrypt/decrypt the payloads. Example:

const config = {
  paths: [
    {
      path: "/resource1",
      toEncrypt: [
        {
          /* path to element to be encrypted in request json body */
          element: "path.to.foo",
          /* path to object where to store encryption fields in request json body */
          obj: "path.to.encryptedFoo",
        },
      ],
      toDecrypt: [
        {
          /* path to element where to store decrypted fields in response object */
          element: "path.to.encryptedFoo",
          /* path to object with encryption fields */
          obj: "path.to.foo",
        },
      ],
    },
  ],
  mode: "JWE",
  encryptedValueFieldName: "encryptedData",
  encryptionCertificate: "./path/to/public.cert",
  privateKey: "./path/to/your/private.key",
};

Mode must be set to JWE to use JWE encryption

• Performing JWE Encryption

Call JweEncryption.encrypt() with a JSON request payload, and optional header object.

Example using the configuration above:

const payload = {
  path: {
    to: {
      foo: {
        sensitive: "this is a secret!",
        sensitive2: "this is a super-secret!",
      },
    },
  },
};
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
// …
let responsePayload = jwe.encrypt("/resource1", header, payload);

Output:

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

• Performing JWE Decryption

Call JweEncryption.decrypt() with an (encrypted) response object with the following fields:

Example using the configuration above:

const response = {};
response.request = { url: "/resource1" };
response.body = JSON.parse(
  "{" +
  '    "path": {' +
  '        "to": {' +
  '            "encryptedFoo": {' +
  '                "encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"' +
  "            }" +
  "        }" +
  "    }" +
  "}");
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
let responsePayload = jwe.decrypt(response);

Output:

{
  "path": {
    "to": {
      "foo": {
        "sensitive": "this is a secret",
        "sensitive2": "this is a super secret!"
      }
    }
  }
}

• Encrypting Entire Payloads

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

const config = {
  paths: [
    {
      path: "/resource1",
      toEncrypt: [
        {
          /* path to element to be encrypted in request json body */
          element: "$",
          /* path to object where to store encryption fields in request json body */
          obj: "$",
        },
      ],
      toDecrypt: [],
    },
  ],
  mode: "JWE",
  encryptedValueFieldName: "encryptedData",
  encryptionCertificate: "./path/to/public.cert",
  privateKey: "./path/to/your/private.key",
};

Example:

const payload = JSON.parse(
  "{" +
  '    "sensitive": "this is a secret",' +
  '    "sensitive2": "this is a super secret!"' +
  "}");
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
// …
let responsePayload = jwe.encrypt("/resource1", header, payload);

Output:

{
  "encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
}

• Decrypting Entire Payloads

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

const config = {
  paths: [
    {
      path: "/resource1",
      toEncrypt: [],
      toDecrypt: [
        {
          /* path to element where to store decrypted fields in response object */
          element: "$",
          /* path to object with encryption fields */
          obj: "$",
        },
      ],
    },
  ],
  mode: "JWE",
  encryptedValueFieldName: "encryptedData",
  encryptionCertificate: "./path/to/public.cert",
  privateKey: "./path/to/your/private.key",
};

Example:

const encryptedPayload = JSON.parse(
  "{" +
  '  "encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"' +
  "}");
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
let responsePayload = jwe.decrypt(encryptedPayload);

Output:

{
  "sensitive": "this is a secret",
  "sensitive2": "this is a super secret!"
}

• First Level Field Encryption and Decryption

To have encrypted results in the first level field or to decrypt the first level field, specify encryptedValueFieldName to be the same as obj (for encryption) or element (for decryption):

Example of configuration:

const config = {
  paths: [
    {
      path: "/resource1",
      toEncrypt: [
        {
          /* path to element to be encrypted in request json body */
          element: "sensitive",
          /* path to object where to store encryption fields in request json body */
          obj: "encryptedData",
        },
      ],
      toDecrypt: [
        {
          /* path to element where to store decrypted fields in response object */
          element: "encryptedData",
          /* path to object with encryption fields */
          obj: "sensitive",
        },
      ],
    },
  ],
  mode: "JWE",
  encryptedValueFieldName: "encryptedData",
  encryptionCertificate: "./path/to/public.cert",
  privateKey: "./path/to/your/private.key",
};

Example of encryption:

const payload = {
  sensitive: "this is a secret!",
  notSensitive: "not a secret",
};
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
// …
let responsePayload = jwe.encrypt("/resource1", header, payload);

Output:

{
  "encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw",
  "notSensitive": "not a secret"
}

Example of decryption:

const response = {};
response.request = { url: "/resource1" };
response.body = JSON.parse(
  "{" +
  '    "encryptedData": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw",' +
  '    "notSensitive": "not a secret"' +
  "}");
const jwe = new (require("mastercard-client-encryption").JweEncryption)(config);
let responsePayload = jwe.decrypt(response);

Output:

{
  "sensitive": "this is a secret",
  "notSensitive": "not a secret"
}

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 client-encryption-nodejs library provides the Service decorator object you can use with the OpenAPI generated client. This class will take care of encrypting request and decrypting response payloads, but also of updating HTTP headers when needed, automatically, without manually calling encrypt()/decrypt() functions for each API request or response.

OpenAPI Generator

OpenAPI client can be generated, starting from your OpenAPI Spec / Swagger using the following command:

openapi-generator-cli generate -i openapi-spec.yaml -l javascript -o out

Client library will be generated in the out folder.

Usage of the `mcapi-service`:

To use it:

Generate the OpenAPI client, as above

Import the mastercard-client-encryption library

const mcapi = require("mastercard-client-encryption");

Import the OpenAPI Client using the Service decorator object:

const openAPIClient = require("./path/to/generated/openapi/client");
const config = {
  /* service configuration object */
};

const service = new mcapi.Service(openAPIClient, config);

Use the service object as you are using the openAPIClient to make API requests.

Example:

let api = service.ServiceApi();
let merchant =
  /* … */
  api.createMerchants(merchant, (error, data, response) => {
    // requests and responses will be automatically encrypted and decrypted
    // accordingly with the configuration used to instantiate the mcapi.Service.
    /* use response/data object here */
  });

Name		Name	Last commit message	Last commit date
Latest commit History 265 Commits
.github		.github
dist		dist
lib/mcapi		lib/mcapi
test		test
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
sonar-project.properties		sonar-project.properties
webpack.config.js		webpack.config.js

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

client-encryption-nodejs

Table of Contents

Overview

Compatibility

References

Versioning and Deprecation Policy

Usage

Prerequisites

Installation

Performing Field Level Encryption and Decryption

Introduction

Configuring the Field Level Encryption

Performing Encryption

Performing Decryption

Performing JWE Encryption and Decryption

JWE Encryption and Decryption

• Introduction

• Configuring the JWE Encryption

• Performing JWE Encryption

• Performing JWE Decryption

• Encrypting Entire Payloads

• Decrypting Entire Payloads

• First Level Field Encryption and Decryption

Integrating with OpenAPI Generator API Client Libraries

OpenAPI Generator

Usage of the `mcapi-service`:

About

Releases 19

Packages

Contributors 12

Languages

License

Mastercard/client-encryption-nodejs

Folders and files

Latest commit

History

Repository files navigation

client-encryption-nodejs

Table of Contents

Overview

Compatibility

References

Versioning and Deprecation Policy

Usage

Prerequisites

Installation

Performing Field Level Encryption and Decryption

Introduction

Configuring the Field Level Encryption

Performing Encryption

Performing Decryption

Performing JWE Encryption and Decryption

JWE Encryption and Decryption

• Introduction

• Configuring the JWE Encryption

• Performing JWE Encryption

• Performing JWE Decryption

• Encrypting Entire Payloads

• Decrypting Entire Payloads

• First Level Field Encryption and Decryption

Integrating with OpenAPI Generator API Client Libraries

OpenAPI Generator

Usage of the mcapi-service:

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 19

Packages 0

Contributors 12

Languages

Usage of the `mcapi-service`:

Packages