From afb5361dbd06bde468f68ccf4088f6676aeefe5d Mon Sep 17 00:00:00 2001 From: Neeraj Joseph Koilparambil Date: Thu, 7 Nov 2024 11:50:21 +0000 Subject: [PATCH] Update README --- README.md | 13 +- docs/configuration-examples.md | 266 +++++++++++++++++++++++++++++++++ 2 files changed, 277 insertions(+), 2 deletions(-) create mode 100644 docs/configuration-examples.md diff --git a/README.md b/README.md index 0467739..f7e90ac 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,14 @@ From now on, an `Authorization` header will be automatically added to every requ ### Encryption 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 diff --git a/docs/configuration-examples.md b/docs/configuration-examples.md new file mode 100644 index 0000000..ecd76b5 --- /dev/null +++ b/docs/configuration-examples.md @@ -0,0 +1,266 @@ +# Example Configurations + +Example configurations for Insomnia. Make sure to remove the comments before using. + +- [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 providing the `keyStore`, `keyStoreAlias` and `keyStorePassword`, +```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 `privateKey` from the decryption key store: +```json +{ + "mastercard": { + // ... // + "encryptionConfig": { + // ... // + "encryptionCertificate": "/path/to/encryption-certificate.pem", + "privateKey": "/path/to/private/key" + } + } +} +``` +