Update README

Mastercard · Nov 8, 2024 · 996777f · 996777f
1 parent bf50668
commit 996777f
Show file tree

Hide file tree

Showing 2 changed files with 275 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -116,7 +116,14 @@ From now on, an `Authorization` header will be automatically added to every requ
 
 ### Encryption <a name="encryption"></a>
 This plugin can take care of encrypting requests and/or decrypting response payloads. To enable encryption support, 
-you need to configure in the environment the `encryptionConfig` property:
+you need to configure in the environment the `encryptionConfig` property.  
+
+Both Mastercard encryption and JWE encryption are supported.   
+For more details on the two encryption type configurations, checkout these links:  
+ - [Mastercard Encryption](https://github.com/Mastercard/client-encryption-nodejs/blob/main/README.md#configuring-the-field-level-encryption)
+ - [JWE Encryption](https://github.com/Mastercard/client-encryption-nodejs/blob/main/README.md#configuring-the-jwe-encryption)  
+
+Here's a quick example for Mastercard Encryption:  
 
 ```jsonc
 {
@@ -176,7 +183,9 @@ As an alternative to providing the `privateKey` in the `encryptionConfig`, you c
   }
 }
 ```
-For further details on the configuration object and predefined service configurations, please checkout this [page](https://github.com/Mastercard/client-encryption-nodejs/wiki). 
+
+[See more examples](docs/encryption-examples.md)
+
 
 ## Further Reading <a name="further-reading"></a>
 

diff --git a/docs/configuration-examples.md b/docs/configuration-examples.md
@@ -0,0 +1,264 @@
+# Example Configurations
+
+- [Authentication](#authentication)  
+- [Mastercard Encryption](#mastercard-encryption)  
+  * [Real world example](#mastercard-encryption-real-world-example)
+- [JWE Encryption](#jwe-encryption)
+  * [Real world example](#jwe-encryption-real-world-example)
+- [Notes](#notes)
+
+## Authentication
+
+```json
+{
+  "mastercard": {
+    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
+    "keyAlias": "keyalias",
+    "keystoreP12Path": "/path/to/auth-keystore.p12",
+    "keystorePassword": "keystorepassword",
+
+    // domains to which this config should be applied to.
+    // defaults to ["mastercard.com","api.ethocaweb.com"]
+    "appliesTo": [
+      "mastercard.com",
+      "api.ethocaweb.com"
+    ]
+  }
+}
+```
+
+## Mastercard Encryption
+```json
+{
+  "mastercard": {
+    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
+    "keyAlias": "keyalias",
+    "keystoreP12Path": "/path/to/auth-keystore.p12",
+    "keystorePassword": "keystorepassword",
+
+    // domains to which this config should be applied to.
+    // defaults to ["mastercard.com","api.ethocaweb.com"]
+    "appliesTo": [
+      "mastercard.com",
+      "api.ethocaweb.com"
+    ],
+
+    "encryptionConfig": {
+      "paths": [
+        {
+          "path": "/*",
+          "toEncrypt": [
+            {
+              // path to the element to be encrypted in request JSON.
+              // use "$" for encrypting the whole request.
+              "element": "path.to.element.to.be.encrypted",
+              // path to object where encryption fields are to be stored in request JSON.
+              // use "$ for the root of the JSON object.
+              "obj": "path.to.encrypted.output.element"
+            }
+          ],
+          "toDecrypt": [
+            {
+              // path to object with encryption fields in response JSON.
+              // use "$ for the root of the JSON.
+              "element": "path.to.decryption.output.element", 
+
+              // path to element where decrypted fields are to be stored in the response JSON.
+              // use "$" for the root of the JSON object.
+              "obj": "path.to.encrypted.element"
+            }
+          ]
+        }
+      ],
+      "oaepPaddingDigestAlgorithm": "SHA-256",
+      "dataEncoding": "hex",  // "hex" or "base64"
+      "ivFieldName": "iv",
+      "encryptedKeyFieldName": "encryptedKey",
+      "encryptedValueFieldName": "encryptedValue",
+      "oaepHashingAlgorithmFieldName": "oaepHashingAlgorithm",
+      "publicKeyFingerprintFieldName": "publicKeyFingerprint",
+      "publicKeyFingerprintType": "certificate", // "certificate" or "publicKey"
+      "publicKeyFingerprint": "1bc1f515b1556df0066c91e24640b42e5cd16452f47f6812f6ef17c082841bcf",
+      "encryptionCertificate": "/path/to/encryption-certificate.pem",
+      "keyStore": "/path/to/decryption-keystore.p12",
+      "keyStoreAlias": "decryption-keyalias",
+      "keyStorePassword": "decryption-keystorepassword"
+    }
+  }
+}
+```
+### Mastercard Encryption Real world example  
+
+This is a real world configuration for the [Donations API](https://developer.mastercard.com/donations/documentation/service_config/), which uses Mastercard Encryption.
+See the [API documentation](https://developer.mastercard.com/donations/documentation/service_config/) for details.
+
+```json
+{
+  "mastercard": {
+    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
+    "keyAlias": "keyalias",
+    "keystoreP12Path": "/path/to/auth-keystore.p12",
+    "keystorePassword": "keystorepassword",
+    "encryptionConfig": {
+      "paths": [
+        {
+          "path": "$",
+          "toEncrypt": [
+            {
+              "element": "$",
+              "obj": "$"
+            }
+          ],
+          "toDecrypt": [
+            {
+              "element": "$",
+              "obj": "$"
+            }
+          ]
+        }
+      ],
+      "oaepPaddingDigestAlgorithm": "SHA-256",
+      "dataEncoding": "base64",
+      "ivFieldName": "iv",
+      "encryptedKeyFieldName": "encryptedKey",
+      "encryptedValueFieldName": "encryptedValue",
+      "oaepHashingAlgorithmFieldName": "oaepPaddingDigestAlgorithm",
+      "publicKeyFingerprintFieldName": "publicKeyFingerprint",
+      "publicKeyFingerprintType": "certificate",
+      "publicKeyFingerprint": "1bc1f515b1556df0066c91e24640b42e5cd16452f47f6812f6ef17c082841bcf",
+      "encryptionCertificate": "/path/to/encryption-certificate.pem",
+      "keyStore": "/path/to/decryption-keystore.p12",
+      "keyStoreAlias": "decryption-keyalias",
+      "keyStorePassword": "decryption-keystorepassword"
+    }
+  }
+}
+```
+
+## JWE Encryption
+```json
+{
+  "mastercard": {
+    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
+    "keyAlias": "keyalias",
+    "keystoreP12Path": "/path/to/auth-keystore.p12",
+    "keystorePassword": "keystorepassword",
+
+    // domains to which this config should be applied to.
+    // defaults to ["mastercard.com","api.ethocaweb.com"]
+    "appliesTo": [
+      "mastercard.com",
+      "api.ethocaweb.com"
+    ],
+
+    "encryptionConfig": {
+      "paths": [
+        {
+          "path": "/*",
+          "toEncrypt": [
+            {
+              // path to the element to be encrypted in request JSON.
+              // use "$" for encrypting the whole request.
+              "element": "path.to.element.to.be.encrypted",
+              // path to object where encryption fields are to be stored in request JSON.
+              // use "$ for the root of the JSON object.
+              "obj": "path.to.encrypted.output.element"
+            }
+          ],
+          "toDecrypt": [
+            {
+              // path to object with encryption fields in response JSON.
+              // use "$ for the root of the JSON.
+              "element": "path.to.decryption.output.element", 
+
+              // path to element where decrypted fields are to be stored in the response JSON.
+              // use "$" for the root of the JSON object.
+              "obj": "path.to.encrypted.element"
+            }
+          ]
+        }
+      ],
+      "mode": "JWE",
+      "encryptedValueFieldName": "encryptedData",
+      "encryptionCertificate": "/path/to/encryption-certificate.pem",
+      "keyStore": "/path/to/decryption-keystore.p12",
+      "keyStoreAlias": "decryption-keyalias",
+      "keyStorePassword": "decryption-keystorepassword"
+    }
+  }
+}
+```
+
+### JWE Encryption Real World Example
+This is a real world configuration for the [Mastercard Installments API](https://developer.mastercard.com/unified-installments/documentation/api-basics/#group-1), which uses Mastercard Encryption.
+See the [API documentation](https://developer.mastercard.com/unified-installments/documentation/api-basics/#group-1) for  details.
+```json
+{
+	"mastercard": {
+		"consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
+		"keyAlias": "keyalias",
+		"keystoreP12Path": "/path/to/auth-keystore.p12",
+		"keystorePassword": "keystorepassword",
+		"appliesTo": [
+			"mastercard.com",
+			"api.ethocaweb.com"
+		],
+		"encryptionConfig": {
+			"paths": [
+				{
+					"path": "/*",
+					"toEncrypt": [
+						{
+							"element": "sensitiveData",
+							"obj": "encryptedValue"
+						}
+					],
+					"toDecrypt": [
+						{
+							"element": "encryptedValue",
+							"obj": "sensitiveData"
+						}
+					]
+				}
+			],
+			"mode": "JWE",
+			"encryptedValueFieldName": "encryptedValue",
+			"encryptionCertificate": "/path/to/encryption-certificate.pem",
+			"keyStore": "/path/to/decryption-keystore.p12",
+			"keyStoreAlias": "keyalias",
+			"keyStorePassword": "keystorepassword"
+		}
+	}
+}
+```
+
+## Notes
+Instead of this:
+```json
+{
+  "mastercard": {
+    // ... //
+    "encryptionConfig": {
+      // ... //
+      "encryptionCertificate": "/path/to/encryption-certificate.pem",
+      "keyStore": "/path/to/decryption-keystore.p12",
+      "keyStoreAlias": "decryption-keyalias",
+      "keyStorePassword": "decryption-keystorepassword"
+    }
+  }
+}
+```
+you can also directly provide the private key from the decryption key store:
+```json
+{
+  "mastercard": {
+    // ... //
+    "encryptionConfig": {
+      // ... //
+      "encryptionCertificate": "/path/to/encryption-certificate.pem",
+      "privateKey": "/path/to/private/key"
+    }
+  }
+}
+```
+