Merge pull request #8 from Mastercard/feature/jwe-support

Adding JWE support

Author: danny-gallagher

README.md

@@ -17,7 +17,7 @@
 - [Usage](#usage)
   - [Prerequisites](#prerequisites)
   - [Adding the Library to Your Project](#adding-the-libraries-to-your-project)
-  - [Performing Field Level Encryption and Decryption](#performing-field-level-encryption-and-decryption)
+  - [Performing Field Level Encryption and Decryption](#performing-payload-encryption-and-decryption)
   - [Integrating with OpenAPI Generator API Client Libraries](#integrating-with-openapi-generator-api-client-libraries)
 
 ## Overview <a name="overview"></a>
@@ -30,8 +30,8 @@ Ruby library for Mastercard API compliant payload encryption/decryption.
 - Truffle Ruby 1.0.0+
 
 ### References <a name="references"></a>
-
-<img src="https://user-images.githubusercontent.com/3964455/55345820-c520a280-54a8-11e9-8235-407199fa1d97.png" alt="Encryption of sensitive data" width="75%" height="75%"/>
+* [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516)
+* [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)
 
 ## Usage <a name="usage"></a>
 
@@ -75,20 +75,171 @@ Import the library:
 ```ruby
 require 'mcapi/encryption/openapi_interceptor' # to add the interceptor
 # or
-require 'mcapi/encryption/field_level_encryption' # to perform ad-hoc encryption/decryption
+require 'mcapi/encryption/field_level_encryption' # to perform ad-hoc Mastercard encryption/decryption
+require 'mcapi/encryption/jwe_encryption' # to perform ad-hoc JWE encryption/decryption
 ```
 
 
 
-### Performing Field Level Encryption and Decryption <a name="performing-field-level-encryption-and-decryption"></a>
+### Performing Payload Encryption and Decryption <a name="performing-payload-encryption-and-decryption"></a>
 
 - [Introduction](#introduction)
-- [Configuring the Field Level Encryption](#configuring-the-field-level-encryption)
-- [Performing Encryption](#performing-encryption)
-- [Performing Decryption](#performing-decryption)
+- [JWE Encryption and Decryption](#jwe-encryption-and-decryption)
+- [Mastercard Encryption and Decryption](#mastercard-encryption-and-decryption)
 
 #### Introduction <a name="introduction"></a>
 
+This 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.
+
+#### JWE Encryption and Decryption <a name="jwe-encryption-and-decryption"></a>
+
++ [Introduction](#jwe-introduction)
++ [Configuring the JWE Encryption](#configuring-the-jwe-encryption)
++ [Performing JWE Encryption](#performing-jwe-encryption)
++ [Performing JWE Decryption](#performing-jwe-decryption)
+
+##### • Introduction <a name="jwe-introduction"></a>
+
+This library uses [JWE compact serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.1) for the encryption of sensitive data.
+The core methods responsible for payload encryption and decryption are `encrypt` and `decrypt` in the `JweEncryption` class.
+
+- `encrypt()` usage:
+
+```ruby
+jwe = McAPI::Encryption::JweEncryption.new(@config)
+encrypted_request_payload = jwe.encrypt(endpoint, body)
+```
+
+- `decrypt()` usage:
+
+```ruby
+jwe = McAPI::Encryption::JweEncryption.new(@config)
+decrypted_response_payload = jwe.decrypt(encrypted_response_payload)
+```
+
+#### Configuring the JWE Encryption <a name="configuring-the-jwe-encryption"></a>
+
+`JweEncryption` needs a config object to instruct how to decrypt/decrypt the payloads. Example:
+
+```json
+{
+  "paths": [
+    {
+      "path": "/resource",
+      "toEncrypt": [
+        {
+          "element": "path.to.foo",
+          "obj": "path.to.encryptedFoo"
+        }
+      ],
+      "toDecrypt": [
+        {
+          "element": "path.to.encryptedFoo",
+          "obj": "path.to.foo"
+        }
+      ]
+    }
+  ],
+  "encryptedValueFieldName": "encryptedData",
+  "encryptionCertificate": "./path/to/public.cert",
+  "privateKey": "./path/to/your/private.key",
+}
+```
+
+For all config options, please see:
+
+- [Configuration object](https://github.com/Mastercard/client-encryption-ruby/wiki/Configuration-Object) for all config options
+
+We have a predefined set of configurations to use with Mastercard services:
+
+- [Service configurations](https://github.com/Mastercard/client-encryption-ruby/wiki/Service-Configurations-for-Client-Encryption-Ruby)
+
+
+#### Performing JWE Encryption <a name="performing-jwe-encryption"></a>
+
+Call `JweEncryption.encrypt()` with a JSON request payload.
+
+Example using the configuration [above](#configuring-the-jwe-encryption):
+
+```ruby
+payload = JSON.generate({
+  path: {
+    to: {
+      foo: {
+        sensitiveField1: 'sensitiveValue1',
+        sensitiveField2: 'sensitiveValue2'
+      }
+    }
+  }
+})
+jwe = McAPI::Encryption::JweEncryption.new(@config)
+request_payload = jwe.encrypt("/resource", header, payload)
+```
+
+Output:
+
+```json
+{
+  "path": {
+    "to": {
+      "encryptedFoo": {
+        "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
+      }
+    }
+  }
+}
+```
+
+#### Performing JWE Decryption <a name="performing-jwe-decryption"></a>
+
+Call `JweEncryption.decrypt()` with an (encrypted) `response` object with the following fields:
+
+- `body`: json payload
+- `request.url`: requesting url
+
+Example using the configuration [above](#configuring-the-jwe-encryption):
+
+```ruby
+response = {}
+response[:request] = { url: '/resource1' }
+response[:body] = 
+{
+  "path": {
+    "to": {
+      "encryptedFoo": {
+        "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM….Y+oPYKZEMTKyYcSIVEgtQw"
+      }
+    }
+  }
+}
+jwe = McAPI::Encryption::JweEncryption.new(@config)
+response_payload = jwe.decrypt(response)
+```
+
+Output:
+
+```json
+{
+  "path": {
+    "to": {
+      "foo": {
+        "sensitiveField1": "sensitiveValue1",
+        "sensitiveField2": "sensitiveValue2"
+      }
+    }
+  }
+}
+```
+
+#### Mastercard Encryption and Decryption <a name="mastercard-encryption-and-decryption"></a>
+
+- [Introduction](#mastercard-introduction)
+- [Configuring the Mastercard Encryption](#configuring-the-mastercard-encryption)
+- [Performing Mastercard Encryption](#performing-mastercard-encryption)
+- [Performing Mastercard Decryption](#performing-mastercard-decryption)
+
+#### Introduction <a name="mastercard-introduction"></a>
+
 The core methods responsible for payload encryption and decryption are `encrypt` and `decrypt` in the `FieldLevelEncryption` class.
 
 - `encrypt()` usage:
@@ -105,7 +256,7 @@ fle = McAPI::Encryption::FieldLevelEncryption.new(@config)
 decrypted_response_payload = fle.decrypt(encrypted_response_payload)
 ```
 
-#### Configuring the Field Level Encryption <a name="configuring-the-field-level-encryption"></a>
+#### Configuring the Mastercard Encryption <a name="configuring-the-mastercard-encryption"></a>
 
 `FieldLevelEncryption` needs a config object to instruct how to decrypt/decrypt the payloads. Example:
 
@@ -148,11 +299,11 @@ We have a predefined set of configurations to use with Mastercard services:
 
 
 
-#### Performing Encryption <a name="performing-encryption"></a>
+#### Performing Mastercard Encryption <a name="performing-mastercard-encryption"></a>
 
 Call `FieldLevelEncryption.encrypt()` with a JSON request payload, and optional `header` object.
 
-Example using the configuration [above](#configuring-the-field-level-encryption):
+Example using the configuration [above](#configuring-the-mastercard-encryption):
 
 ```ruby
 payload = JSON.generate({
@@ -187,15 +338,15 @@ Output:
 }
 ```
 
-#### Performing Decryption <a name="performing-decryption"></a>
+#### Performing Mastercard Decryption <a name="performing-mastercard-decryption"></a>
 
 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](#configuring-the-field-level-encryption):
+Example using the configuration [above](#configuring-the-mastercard-encryption):
 
 ```ruby
 response = {}
@@ -240,9 +391,13 @@ It provides generators and library templates for supporting multiple languages a
 
 The **client-encryption-ruby** library provides a method you can use to integrate the OpenAPI generated client with this library:
 ```ruby
+# JWE Encryption
+McAPI::Encryption::OpenAPIInterceptor.install_jwe_encryption(open_api_client, config)
+
+# Mastercard Encryption
 McAPI::Encryption::OpenAPIInterceptor.install_field_level_encryption(open_api_client, config)
 ```
-This method will add the field level encryption in the generated OpenApi client, taking 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.
+The above methods will handle the encryption in the generated OpenApi client, taking 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 <a name="openapi-generator"></a>
 
@@ -271,15 +426,20 @@ To use it:
    require_relative './out/generated_open_apiclient' #import generated OpenAPI client
    ```
 
-3. Install the field level encryption in the generated client:
+3. Install the Mastercard/JWE encryption in the generated client:
 
    ```ruby
    # Read the service configuration obj
    @config = File.read('./config.json')   
    # Create a new instance of the generated client
    @api_client = client::ApiClient.new
-   # Enable field level encryption
+   
+   # Use 1 of the below 2 methods (depending on the encryption type) to enable encryption
+   # Enable Mastercard encryption
    McAPI::Encryption::OpenAPIInterceptor.install_field_level_encryption(@api_client, @config)
+   
+   # Enable JWE encryption
+   McAPI::Encryption::OpenAPIInterceptor.install_jwe_encryption(@api_client, @config)
    ```
 
 4. Use the `api_client` object with the Field Level Encryption enabled: