docs(data-masking): add docs for data masking utility

README.md

@@ -30,6 +30,7 @@ Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverles
 * **[Event source data classes](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_classes/)** - Data classes describing the schema of common Lambda event triggers
 * **[Parser](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/)** - Data parsing and deep validation using Pydantic
 * **[Idempotency](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/)** - Convert your Lambda functions into idempotent operations which are safe to retry
+* **[Data Masking](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_masking/)** -  Protect confidential data with easy removal or encryption
 * **[Feature Flags](https://docs.powertools.aws.dev/lambda/python/latest/utilities/feature_flags/)** - A simple rule engine to evaluate when one or multiple features should be enabled depending on the input
 * **[Streaming](https://docs.powertools.aws.dev/lambda/python/latest/utilities/streaming/)** - Streams datasets larger than the available memory as streaming data.
 

docs/index.md

@@ -701,6 +701,7 @@ Core utilities such as Tracing, Logging, Metrics, and Event Handler will be avai
 | [**Event source data classes**](./utilities/data_classes.md){target="_blank"}                                                                       | Data classes describing the schema of common Lambda event triggers                                                                                        |
 | [**Parser**](./utilities/parser.md){target="_blank"}                                                                                                | Data parsing and deep validation using Pydantic                                                                                                           |
 | [**Idempotency**](./utilities/idempotency.md){target="_blank"}                                                                                      | Idempotent Lambda handler                                                                                                                                 |
+| [**Data Masking**](./utilities/data_masking.md){target="_blank"}                                                                                      | Protect confidential data with easy removal or encryption                                                                                                                                 |
 | [**Feature Flags**](./utilities/feature_flags.md){target="_blank"}                                                                                  | A simple rule engine to evaluate when one or multiple features should be enabled depending on the input                                                   |
 | [**Streaming**](./utilities/streaming.md){target="_blank"}                                                                                          | Streams datasets larger than the available memory as streaming data.                                                                                      |
 

docs/utilities/data_masking.md

@@ -128,20 +128,19 @@ To encrypt, you will need an [encryption provider](#providers). Here, we will us
 Under the hood, we delegate a [number of operations](#encrypt-operation-with-encryption-sdk-kms) to AWS Encryption SDK to authenticate, create a portable encryption message, and actual data encryption.
 
 === "getting_started_encrypt_data.py"
-
     ```python hl_lines="6-8 14-15 26"
     --8<-- "examples/data_masking/src/getting_started_encrypt_data.py"
     ```
 
     1. You can use more than one KMS Key for higher availability but increased latency. </br></br>Encryption SDK will ensure the data key is encrypted with both keys.
 
 === "generic_data_input.json"
-    ```json hl_lines="7-9 14"
+    ```json
     --8<-- "examples/data_masking/src/generic_data_input.json"
     ```
 
 === "encrypt_data_output.json"
-    ```json hl_lines="5-7 12"
+    ```json
     --8<-- "examples/data_masking/src/encrypt_data_output.json"
     ```
 
@@ -165,21 +164,23 @@ Under the hood, we delegate a [number of operations](#decrypt-operation-with-enc
     1. Note that KMS key alias or key ID won't work.
     2. You can use more than one KMS Key for higher availability but increased latency. </br></br>Encryption SDK will call `Decrypt` API with all master keys when trying to decrypt the data key.
 
-=== "encrypt_data_output.json"
+=== "getting_started_decrypt_data_input.json"
 
-    ```json hl_lines="5-7 12"
-    --8<-- "examples/data_masking/src/encrypt_data_output.json"
+    ```json
+    --8<-- "examples/data_masking/src/getting_started_decrypt_data_input.json"
     ```
 
 === "getting_started_decrypt_data_output.json"
 
-    ```json hl_lines="5-7 12-17"
+    ```json
     --8<-- "examples/data_masking/src/getting_started_decrypt_data_output.json"
     ```
 
 ### Encryption context for integrity and authenticity
 
-For a stronger security posture, you can add metadata to each encryption operation, and verify them during decryption. This is known as additional authenticated data (AAD). These are non-sensitive data that can help protect authenticity and integrity of your encrypted data, and even help to prevent a [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) situation.
+<!-- markdownlint-disable MD013 -->
+For a stronger security posture, you can add metadata to each encryption operation, and verify them during decryption. This is known as additional authenticated data (AAD). These are non-sensitive data that can help protect authenticity and integrity of your encrypted data, and even help to prevent a [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html){target="_blank"} situation.
+<!-- markdownlint-enable MD013 -->
 
 ???+ danger "Important considerations you should know"
     1. **Exact match verification on decrypt**. Be careful using random data like `timestamps` as encryption context if you can't provide them on decrypt.
@@ -204,24 +205,23 @@ For a stronger security posture, you can add metadata to each encryption operati
 
 ### Choosing parts of your data
 
-!!! note "We support `JSON` data types only - see [data serialization for more details](#data-serialization-and-preservation)."
-
 ???+ note "Current limitations"
-    1. The `fields` parameter is currently only available to use with the `erase` method, with the potential for it to be added to the `encrypt` and `decrypt` methods in the future.
+    1. The `fields` parameter is currently exclusive to the `erase` method, with potential future inclusion into `encrypt` and `decrypt`.
+    2. We support `JSON` data types only - see [data serialization for more details](#data-serialization)."
 
-You can use the `fields` parameter with dot notation `.` to choose one or more parts of your data to `erase`. This is useful when you want to keep data structure intact except the confidential fields.
+You can use the `fields` parameter with the dot notation `.` to choose one or more parts of your data to `erase`. This is useful when you want to keep data structure intact except the confidential fields.
 
 When `fields` is present, `erase` behaves differently:
 
-| Operation | Behavior                                                    | Example                 | Obfuscated                      |
+| Operation | Behavior                                                    | Example                 | Result                      |
 | --------- | ----------------------------------------------------------- | ----------------------- | ------------------------------- |
 | `erase`    | Replace data while keeping collections type intact.         | `{"cards": ["a", "b"]}` | `{"cards": ["*****", "*****"]}` |
 
 Here are common scenarios to best visualize how to use `fields`.
 
 === "Top keys only"
 
-    You want to obfuscate data in the `card_number` field.
+    You want to erase data in the `card_number` field.
 
     === "Data"
 
@@ -239,7 +239,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "Nested key"
 
-    You want to obfuscate data in the `postcode` field.
+    You want to erase data in the `postcode` field.
 
     === "Data"
 
@@ -257,7 +257,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "Multiple keys"
 
-    You want to obfuscate data in both `postcode` and `street` fields.
+    You want to erase data in both `postcode` and `street` fields.
 
     === "Data"
 
@@ -275,7 +275,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "All key items"
 
-    You want to obfuscate data under `address` field.
+    You want to erase data under `address` field.
 
     === "Data"
 
@@ -293,7 +293,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "Complex nested key"
 
-    You want to obfuscate data under `name` field.
+    You want to erase data under `name` field.
 
     === "Data"
 
@@ -311,7 +311,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "All fields in a list"
 
-    You want to obfuscate data under `street` field located at the any index of the address list.
+    You want to erase data under `street` field located at the any index of the address list.
 
     === "Data"
 
@@ -329,7 +329,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "Slicing a list"
 
-    You want to obfuscate data by slicing a list.
+    You want to erase data by slicing a list.
 
     === "Data"
 
@@ -347,7 +347,7 @@ Here are common scenarios to best visualize how to use `fields`.
 
 === "Complex expressions"
 
-    You want to obfuscate data by finding for a field with conditional expression.
+    You want to erase data by finding for a field with conditional expression.
 
     === "Data"
 
@@ -368,6 +368,7 @@ Here are common scenarios to best visualize how to use `fields`.
         ```json hl_lines="8 12"
         --8<-- "examples/data_masking/src/choosing_payload_complex_search_output.json"
         ```
+
 For comprehensive guidance on using JSONPath syntax, please refer to the official documentation available at [jsonpath-ng](https://github.com/h2non/jsonpath-ng#jsonpath-syntax){target="_blank" rel="nofollow"}
 
 #### JSON
@@ -408,9 +409,9 @@ For compatibility or performance, you can optionally pass your own JSON serializ
 
 === "advanced_custom_serializer.py"
 
-    ```python hl_lines="17-18"
-    --8<-- "examples/data_masking/src/advanced_custom_serializer.py"
-    ```
+```python hl_lines="17-18"
+--8<-- "examples/data_masking/src/advanced_custom_serializer.py"
+```
 
 ### Providers
 
@@ -425,15 +426,35 @@ You can modify the following values when initializing the `AWSEncryptionSDKProvi
 | **max_messages_encrypted** | `4294967296`          | The maximum number of messages that may be encrypted under a cache entry                      |
 | **max_bytes_encrypted**    | `9223372036854775807` | The maximum number of bytes that may be encrypted under a cache entry                         |
 
-**Changing the default algorithm**
+If required, you have the option to customize the default values when initializing the `AWSEncryptionSDKProvider` class.
+
+=== "aws_encryption_provider_example.py"
+
+```python hl_lines="14-19"
+--8<-- "examples/data_masking/src/aws_encryption_provider_example.py"
+```
 
-The AWS Encryption SDK defaults to using the `AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384` algorithm for encrypting your Data Key. If you want, you have the flexibility to customize and choose a different encryption algorithm.
+**Passing additional SDK arguments**
+
+You can pass additional arguments to the `AWSEncryptionSDKProvider` via the `provider_options` parameter. To learn more about the different arguments you can give to the SDK, see the [EncryptionSDKClient's documentation](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.html#aws_encryption_sdk.EncryptionSDKClient.encrypt){target="_blank"}.
+
+For example, the AWS Encryption SDK defaults to using the `AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384` algorithm for encrypting your Data Key. If you want, you have the flexibility to customize and choose a different encryption algorithm.
 
 === "changing_default_algorithm.py"
 
-    ```python hl_lines="5 26"
-    --8<-- "examples/data_masking/src/changing_default_algorithm.py"
-    ```
+```python hl_lines="5 26 30"
+--8<-- "examples/data_masking/src/changing_default_algorithm.py"
+```
+
+**Using multiple keys**
+
+The `AWSEncryptionSDKProvider` allows you to instantiate it with several KMS keys by passing them all in a `list` to the `keys` parameter. This could be beneficial if you own keys in different regions, enabling you to perform cross-regional encryption and decryption.
+
+=== "using_multiple_keys.py"
+
+```python hl_lines="15"
+--8<-- "examples/data_masking/src/using_multiple_keys.py"
+```
 
 ### Data masking request flow
 
@@ -577,11 +598,13 @@ sequenceDiagram
 Testing your code with a simple erase operation
 
 === "test_lambda_mask.py"
-    ```python hl_lines="22"
-    --8<-- "examples/data_masking/tests/test_lambda_mask.py"
-    ```
+
+```python hl_lines="22"
+--8<-- "examples/data_masking/tests/test_lambda_mask.py"
+```
 
 === "lambda_mask.py"
-    ```python hl_lines="3 12"
-    --8<-- "examples/data_masking/tests/lambda_mask.py"
-    ```
+
+```python hl_lines="3 12"
+--8<-- "examples/data_masking/tests/lambda_mask.py"
+```

examples/data_masking/src/aws_encryption_provider_example.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.data_masking import DataMasking
+from aws_lambda_powertools.utilities.data_masking.provider.kms.aws_encryption_sdk import (
+    AWSEncryptionSDKProvider,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+KMS_KEY_ARN = os.getenv("KMS_KEY_ARN", "")
+
+encryption_provider = AWSEncryptionSDKProvider(
+    keys=[KMS_KEY_ARN],
+    local_cache_capacity=200,
+    max_cache_age_seconds=400,
+    max_messages_encrypted=200,
+    max_bytes_encrypted=2000)
+
+data_masker = DataMasking(provider=encryption_provider)
+
+logger = Logger()
+
+
+@logger.inject_lambda_context
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    data: dict = event.get("body", {})
+
+    logger.info("Encrypting the whole object")
+
+    encrypted = data_masker.encrypt(data)
+
+    return {"body": encrypted}

examples/data_masking/src/changing_default_algorithm.py

@@ -25,9 +25,9 @@ def lambda_handler(event: dict, context: LambdaContext) -> str:
 
     provider_options = {"algorithm": Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY}
 
-    decrypted = data_masker.encrypt(
+    encrypted = data_masker.encrypt(
         data,
         provider_options=provider_options,
     )
 
-    return decrypted
+    return encrypted

examples/data_masking/src/getting_started_decrypt_data_input.json

@@ -0,0 +1,3 @@
+{
+    "body": "AgV4uF5K2YMtNhYrtviTwKNrUHhqQr73l/jNfukkh+qLOC8AXwABABVhd3MtY3J5cHRvLXB1YmxpYy1rZXkAREEvcjEyaFZHY1R5cjJuTDNKbTJ3UFA3R3ZjaytIdi9hekZqbXVUb25Ya3J5SzFBOUlJZDZxZXpSR1NTVnZDUUxoZz09AAEAB2F3cy1rbXMAS2Fybjphd3M6a21zOnVzLWVhc3QtMToyMDA5ODQxMTIzODY6a2V5LzZkODJiMzRlLTM2NjAtNDRlMi04YWJiLTdmMzA1OGJlYTIxMgC4AQIBAHjxYXAO7wQGd+7qxoyvXAajwqboF5FL/9lgYUNJTB8VtAHBP2hwVgw+zypp7GoMNTPAAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMx/B25MTgWwpL7CmuAgEQgDtan3orAOKFUfyNm3v6rFcglb+BVVVDV71fj4aRljhpg1ixsYFaKsoej8NcwRktIiWE+mw9XmTEVb6xFQIAABAA9DeLzlRaRQgTcXMJG0iBu/YTyyDKiROD+bU1Y09X9RBz5LA1nWIENJKq2seAhNSB/////wAAAAEAAAAAAAAAAAAAAAEAAAEBExLJ9wI4n7t+wyPEEP4kjYFBdkmNuLLsVC2Yt8mv9Y1iH2G+/g9SaIcdK57pkoW0ECpBxZVOxCuhmK2s74AJCUdem9McjS1waUKyzYTi9vv2ySNBsABIDwT990rE7jZJ3tEZAqcWZg/eWlxvnksFR/akBWZKsKzFz6lF57+cTgdISCEJRV0E7fcUeCuaMaQGK1Qw2OCmIeHEG5j5iztBkZG2IB2CVND/AbxmDUFHwgjsrJPTzaDYSufcGMoZW1A9X1sLVfqNVKvnOFP5tNY7kPF5eAI9FhGBw8SjTqODXz4k6zuqzy9no8HtXowP265U8NZ5VbVTd/zuVEbZyK5KBqzP1sExW4RhnlpXMoOs9WSuAGcwZQIxANTeEwb9V7CacV2Urt/oCqysUzhoV2AcT2ZjryFqY79Tsg+FRpIx7cBizL4ieRzbhQIwcRasNncO5OZOcmVr0MqHv+gCVznndMgjXJmWwUa7h6skJKmhhMPlN0CsugxtVWnD"
+}

examples/data_masking/src/using_multiple_keys.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.data_masking import DataMasking
+from aws_lambda_powertools.utilities.data_masking.provider.kms.aws_encryption_sdk import (
+    AWSEncryptionSDKProvider,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+KMS_KEY_ARN_1 = os.getenv("KMS_KEY_ARN_1", "")
+KMS_KEY_ARN_2 = os.getenv("KMS_KEY_ARN_2", "")
+
+encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN_1, KMS_KEY_ARN_2])
+data_masker = DataMasking(provider=encryption_provider)
+
+logger = Logger()
+
+
+@logger.inject_lambda_context
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    data: dict = event.get("body", {})
+
+    logger.info("Encrypting the whole object")
+
+    encrypted = data_masker.encrypt(data)
+
+    return {"body": encrypted}