Merge pull request #22 from rfeelin/feature/jwe-encryption

Adding JWE support

Author: rfeelin

.gitignore

@@ -2,4 +2,6 @@
 vendor
 tests.xml
 coverage.xml
-.scannerwork
+.scannerwork
+.phpunit.result.cache
+composer.lock

README.md

@@ -17,6 +17,7 @@
   * [Loading the Encryption Certificate](#loading-the-encryption-certificate) 
   * [Loading the Decryption Key](#loading-the-decryption-key)
   * [Performing Field Level Encryption and Decryption](#performing-field-level-encryption-and-decryption)
+  * [Performing JWE Encryption and Decryption](#performing-JWE-encryption-and-decryption)
   * [Integrating with OpenAPI Generator API Client Libraries](#integrating-with-openapi-generator-api-client-libraries)
 
 ## Overview <a name="overview"></a>
@@ -387,6 +388,191 @@ Output:
 }
 ```
 
+### Performing JWE Encryption and Decryption <a name="performing-JWE-encryption-and-decryption"></a>
+
++ [Introduction](#introduction-jwe)
++ [Configuring the JWE Encryption](#configuring-the-JWE-encryption)
++ [Performing Encryption](#performing-encryption-jwe)
++ [Performing Decryption](#performing-decryption-jwe)
++ [Encrypting Entire Payloads](#encrypting-entire-payloads-jwe)
++ [Decrypting Entire Payloads](#decrypting-entire-payloads-jwe)
+
+#### Introduction <a name="introduction-jwe"></a>
+
+The core methods responsible for payload encryption and decryption are `encryptPayload` and `decryptPayload` in the `JWEEncryption` class.
+
+* `encryptPayload` usage:
+```php
+use Mastercard\Developer\Encryption;
+// …
+$encryptedRequestPayload = JWEEncryption::encryptPayload($requestPayload, $config);
+```
+
+* `decryptPayload` usage:
+```php
+use Mastercard\Developer\Encryption;
+// …
+$responsePayload = JWEEncryption::decryptPayload($encryptedResponsePayload, $config);
+```
+
+#### Configuring the JWE Encryption <a name="configuring-the-JWE-encryption"></a>
+Use the `JWEEncryptionConfigBuilder` to create `JWEEncryptionConfig` instances. Example:
+```php
+use Mastercard\Developer\Encryption;
+// …
+$config = FieldLevelEncryptionConfigBuilder::aFieldLevelEncryptionConfig()
+    ->withEncryptionCertificate($encryptionCertificate)
+    ->withDecryptionKey($decryptionKey)
+    ->withEncryptionPath('$.path.to.foo', '$.path.to.encryptedFoo')
+    ->withDecryptionPath('$.path.to.encryptedFoo', '$.path.to.foo')
+    ->withEncryptedValueFieldName('encryptedValue')
+    ->build();
+```
+Note: If `withEncryptedValueFieldName` is left blank, the value will default to `encryptedData`
+
+See also:
+* [JWEEncryptionConfig.php](https://github.com/Mastercard/client-encryption-php/blob/master/src/Developer/Encryption/JWEEncryptionConfig.php) for all config options
+* [Service Configurations for Client Encryption PHP](https://github.com/Mastercard/client-encryption-php/wiki/Service-Configurations-for-Client-Encryption-PHP)
+
+#### Performing Encryption <a name="performing-encryption-jwe"></a>
+
+Call `JWEEncryption::encryptPayload` with a JSON request payload and a `JWEEncryptionConfig` instance.
+
+Example using the configuration [above](#configuring-the-JWE-encryption):
+```php
+use Mastercard\Developer\Encryption;
+// …
+$payload = '{
+    "path": {
+        "to": {
+            "foo": {
+                "sensitiveField1": "sensitiveValue1",
+                "sensitiveField2": "sensitiveValue2"
+            }
+        }
+    }
+}';
+$encryptedPayload = JWEEncryption::encryptPayload($payload, $config);
+echo (json_encode(json_decode($encryptedPayload), JSON_PRETTY_PRINT));
+```
+
+Output:
+
+```json
+{
+  "path": {
+    "to": {
+      "encryptedFoo": "809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f"
+    }
+  }
+}
+```
+
+#### Performing Decryption <a name="performing-decryption-jwe"></a>
+
+Call `JWEEncryption::decryptPayload` with a JSON response payload and a `JWEEncryptionConfig` instance.
+
+Example using the configuration [above](#configuring-the-JWE-encryption):
+```php
+use Mastercard\Developer\Encryption;
+// …
+$encryptedPayload = '{
+    "path": {
+        "to": {
+            "encryptedFoo": {
+                "encryptedValue": "809a09d78257af5379df0c454dcdf…353ed59fe72fd4a7735c69da4080e74f"
+            }
+        }
+    }
+}';
+$payload = JWEEncryption::decryptPayload($encryptedPayload, $config);
+echo (json_encode(json_decode($payload), JSON_PRETTY_PRINT));
+```
+
+Output:
+```json
+{
+    "path": {
+        "to": {
+            "foo": {
+                "sensitiveField1": "sensitiveValue1",
+                "sensitiveField2": "sensitiveValue2"
+            }
+        }
+    }
+}
+```
+
+#### Encrypting Entire Payloads <a name="encrypting-entire-payloads-jwe"></a>
+
+Entire payloads can be encrypted using the '$' operator as encryption path:
+
+```php
+use Mastercard\Developer\Encryption;
+// …
+$config = JWEConfigBuilder::aFieldLevelEncryptionConfig()
+    ->withEncryptionCertificate(encryptionCertificate)
+    ->withEncryptionPath('$', '$')
+    ->withEncryptedValueFieldName("encryptedValue")
+    // …
+    ->build();
+```
+
+Example:
+```php
+use Mastercard\Developer\Encryption;
+// …
+$payload = '{
+    "sensitiveField1": "sensitiveValue1",
+    "sensitiveField2": "sensitiveValue2"
+}';
+$encryptedPayload = JWEEncryption::encryptPayload($payload, $config);
+echo (json_encode(json_decode($encryptedPayload), JSON_PRETTY_PRINT));
+```
+
+Output:
+```json
+{
+    "encryptedValue": "e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515"
+}
+```
+
+#### Decrypting Entire Payloads <a name="decrypting-entire-payloads-jwe"></a>
+
+Entire payloads can be decrypted using the '$' operator as decryption path:
+
+```php
+use Mastercard\Developer\Encryption;
+// …
+$config = JWEEncryptionConfigBuilder::aFieldLevelEncryptionConfig()
+    ->withDecryptionKey(decryptionKey)
+    ->withDecryptionPath('$', '$')
+    ->withEncryptedValueFieldName("encryptedValue")
+    // …
+    ->build();
+```
+
+Example:
+```php
+use Mastercard\Developer\Encryption;
+// …
+$encryptedPayload = '{
+    "encryptedValue": "e5e9340f4d2618d27f8955828c86…379b13901a3b1e2efed616b6750a90fd379515"
+}';
+$payload = FieldLevelEncryption::decryptPayload($encryptedPayload, $config);
+echo (json_encode(json_decode($payload), JSON_PRETTY_PRINT));
+```
+
+Output:
+```json
+{
+    "sensitiveField1": "sensitiveValue1",
+    "sensitiveField2": "sensitiveValue2"
+}
+```
+
+
+
 ### Integrating with OpenAPI Generator API Client Libraries <a name="integrating-with-openapi-generator-api-client-libraries"></a>
 
 [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification). 
@@ -410,7 +596,7 @@ See also:
 * [OpenAPI Generator CLI Installation](https://openapi-generator.tech/docs/installation/)
 * [CONFIG OPTIONS for php](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/php.md)
 
-##### Usage of the `PsrHttpMessageEncryptionInterceptor`
+##### Usage of the `PsrHttpMessageEncryptionInterceptor` for Field Level Encryption
 
 ```php
 use GuzzleHttp;
@@ -436,3 +622,29 @@ $config->setHost('https://sandbox.api.mastercard.com');
 $serviceApi = new ServiceApi($client, $config);
 // …
 ```
+##### Usage of the `PsrHttpMessageEncryptionInterceptor` for JWE Encryption
+
+```php
+use GuzzleHttp;
+use OpenAPI\Client\Api\ServiceApi;
+use OpenAPI\Client\Configuration
+use Mastercard\Developer\Signers\PsrHttpMessageSigner;
+use Mastercard\Developer\Interceptors\PsrHttpMessageEncryptionInterceptor;
+// …
+
+$stack = new GuzzleHttp\HandlerStack();
+$stack->setHandler(new GuzzleHttp\Handler\CurlHandler());
+$jweEncryptionConfig = JWEEncryptionConfigBuilder::aJWEEncryptionConfig()
+    // …
+    ->build();
+$jweEncryptionInterceptor = new PsrHttpMessageEncryptionInterceptor($jweEncryptionConfig);
+$stack->push(GuzzleHttp\Middleware::mapRequest([$jweEncryptionInterceptor, 'interceptRequest']));
+$stack->push(GuzzleHttp\Middleware::mapResponse([$jweEncryptionInterceptor, 'interceptResponse']));
+$stack->push(GuzzleHttp\Middleware::mapRequest([new PsrHttpMessageSigner($consumerKey, $signingKey), 'sign']));
+$options = ['handler' => $stack];
+$client = new GuzzleHttp\Client($options);
+$config = new Configuration();
+$config->setHost('https://sandbox.api.mastercard.com');
+$serviceApi = new ServiceApi($client, $config);
+// …
+```

composer.json

@@ -18,12 +18,14 @@
         }
     ],
     "require": {
-        "phpseclib/phpseclib": "^2.0",
-        "symfony/polyfill-php70": "^1.19"
+        "phpseclib/phpseclib": "~3.0",
+        "symfony/polyfill-php70": "^1.19",
+        "galbar/jsonpath": "^2.0"
     },
     "require-dev": {
         "guzzlehttp/guzzle": "^6.2",
-        "yoast/phpunit-polyfills": "^1.0"
+        "yoast/phpunit-polyfills": "^1.0",
+        "phake/phake": "*"
     },
     "suggest": {
         "psr/http-message": "Allow usage of the PsrHttpMessageEncryptionInterceptor class"

src/Developer/Encryption/AES/AESCBC.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Mastercard\Developer\Encryption\AES;
+
+use Mastercard\Developer\Encryption\EncryptionException;
+use phpseclib3\Crypt\AES;
+
+class AESCBC
+{
+    private function __construct(){
+        // This class can't be instantiated
+    }
+
+    /**
+     * @param string $iv
+     * @param string $key
+     * @param string $bytes
+     * @throws EncryptionException
+     * @return string
+     */
+    public static function encrypt($iv, $key, $bytes) {
+        $aes = new AES('cbc');
+        $aes->setKey($key);
+        $aes->setIV($iv);
+        $encryptedBytes = $aes->encrypt($bytes);
+        if (false === $encryptedBytes) {
+            throw new EncryptionException('Failed to encrypt bytes!');
+        }
+        return $encryptedBytes;
+    }
+
+    /**
+     * @param string $iv
+     * @param string $key
+     * @param string $encryptedBytes
+     * @throws EncryptionException
+     * @return string
+     */
+    public static function decrypt($iv, $key, $encryptedBytes) {
+        $aes = new AES('cbc');
+        $aes->setKey($key);
+        $aes->setIV($iv);
+        $bytes = $aes->decrypt($encryptedBytes);
+        if (false === $bytes) {
+            throw new EncryptionException('Failed to decrypt bytes with the provided key and IV!');
+        }
+        return $bytes;
+    }    
+}

src/Developer/Encryption/AES/AESEncryption.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Mastercard\Developer\Encryption\AES;
+
+class AESEncryption
+{
+    private function __construct()
+    {
+        // Nothing to do here
+    }
+
+
+    /**
+     * @param string            $cipher_algo
+     * @return string 
+     */    
+    public static function generateIv($cipher_algo = 'AES-128-CBC')
+    {
+        $ivLength = openssl_cipher_iv_length($cipher_algo);
+        $iv = openssl_random_pseudo_bytes($ivLength);
+
+        return $iv;
+    }
+
+    /**
+     * @param int            $bitLength
+     * @return string 
+     */    
+    public static function generateCek($bitLength)
+    {
+        return openssl_random_pseudo_bytes($bitLength / 8);
+    }
+}

src/Developer/Encryption/AES/AESGCM.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Mastercard\Developer\Encryption\AES;
+
+use phpseclib3\Crypt\AES;
+
+class AESGCM
+{
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param string $iv
+     * @param string $key
+     * @param string $authTag
+     * @param string $aad
+     * @param string $cipherText
+     * @return string
+     */
+    public static function decrypt($iv, $key, $authTag, $aad, $cipherText)
+    {
+        $cipher = new AES('gcm');
+        $cipher->setNonce($iv);
+        $cipher->setKey($key);
+        $cipher->disablePadding();
+        $cipher->setTag($authTag);
+        $cipher->setAAD($aad);
+        return $cipher->decrypt($cipherText);
+    }
+}