Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@joseph-neeraj
joseph-neeraj committed Nov 8, 2024
1 parent bf50668 commit afb5361
Show file tree
Hide file tree
Showing 2 changed files with 277 additions and 2 deletions.
13 changes: 11 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down Expand Up @@ -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>

Expand Down
266 changes: 266 additions & 0 deletions docs/configuration-examples.md
View file
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
```

0 comments on commit afb5361

Please sign in to comment.