From 8448e152f2615fd2ee58481fdfee258aa828be50 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 20 Jul 2020 12:10:32 -0700 Subject: [PATCH 1/3] docs: add example templates requirements to examples overview --- examples/examples.md | 53 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/examples/examples.md b/examples/examples.md index 0f75bee4..bbdc3c3d 100644 --- a/examples/examples.md +++ b/examples/examples.md @@ -5,10 +5,14 @@ ## Version -0.1.0 +0.2.0 ### Changelog +- 0.2.0 + + - Add [Example Templates](#example-templates) section + - 0.1.0 - [Require examples](../changes/2020-06-16_required-examples/change.md) @@ -50,3 +54,50 @@ in this document are to be interpreted as described in - ex: Raw keyring examples generate wrapping keys as part of the example. These examples MUST contain guidance that in production those keys SHOULD be managed by an HSM. + +### Example Templates + +Each example is defined by a [template](./templates). +Templates MUST include sufficient code to clearly demonstrate +how to implement an example. +This code MAY be in any language. + +Each template MUST contain the following sections: + +1. Header : + This is a detailed description + that independently describes the purpose of the example + and what it describes. + It includes any links to supporting documentation. + + - Implementations MUST include this text verbatim + at the top of the file, + adjusted appropriately for language comment syntax. + +1. Summary : + One-sentence summary of the header. + + - Implementations MUST include this text verbatim + in the documentation for the example entry point + function/method/etc, + adjusted appropriately for language comment syntax. + +1. Inputs : + List of inputs that the example entry point MUST accept, + with an accompanying description. + + - Implementations MUST provide all of these inputs in CI + as part of their testing framework. + - Implementations MUST name their inputs to match the naming of + the input in the template. + - Implementations MUST use the description text verbatim, + adjusted appropriately for language comment syntax. + +1. Steps : + List of steps that define the example. + +- Implementations MUST include every step. +- Implementations MUST include any comments verbatim, + adjusted appropriately for language comment syntax. +- Implementations MAY alter the order of steps + if another order is more appropriate for that language. From 0f1aa6074b9639c2934cea80ffe1471d5b54686b Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 20 Jul 2020 12:14:00 -0700 Subject: [PATCH 2/3] docs: add raw AES keyring example template --- .../raw-keyrings/raw-aes-keyring.md | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 examples/templates/configuration/raw-keyrings/raw-aes-keyring.md diff --git a/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md b/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md new file mode 100644 index 00000000..1d47b015 --- /dev/null +++ b/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md @@ -0,0 +1,132 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Raw AES keyring example + +Implementations of this example MUST follow the rules defined in +[Example Templates](../../../examples.md#example-templates). + +## Implementations + +- [Python (DEV)](https://github.com/aws/aws-encryption-sdk-python/blob/keyring/examples/src/keyring/raw_aes/raw_aes.py) +- [Python Master Key Provider (DEV)](https://github.com/aws/aws-encryption-sdk-python/blob/keyring/examples/src/master_key_provider/raw_aes/raw_aes.py) +- [Java (DEV)](https://github.com/aws/aws-encryption-sdk-java/blob/keyring/src/examples/java/com/amazonaws/crypto/examples/keyring/rawaes/RawAes.java) +- [Java Master Key Provider (DEV)](https://github.com/aws/aws-encryption-sdk-java/blob/keyring/src/examples/java/com/amazonaws/crypto/examples/masterkeyprovider/rawaes/RawAes.java) + +## Definitions + +### Conventions used in this document + +The key words +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119). + +## Header + +```python +# This examples shows how to configure and use a raw AES keyring. +# +# https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html#use-raw-aes-keyring +# +# In this example, we use the one-step encrypt and decrypt APIs. +``` + +## Summary + +```python +# Demonstrate an encrypt/decrypt cycle using a raw AES keyring. +``` + +## Inputs + +- **source plaintext** : + Plaintext to encrypt + +## Steps + +1. Define encryption context. + + ```python + # Prepare your encryption context. + # Remember that your encryption context is NOT SECRET. + # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context + encryption_context = { + "encryption": "context", + "is not": "secret", + "but adds": "useful metadata", + "that can help you": "be confident that", + "the data you are handling": "is what you think it is", + } + ``` + +1. Generate the wrapping key. + + ```python + # Generate a 256-bit (32 byte) AES key to use with your keyring. + # + # In practice, you should get this key from a secure key management system such as an HSM. + key = os.urandom(32) + ``` + +1. Create keyring. + + ```python + # Create the keyring that determines how your data keys are protected. + keyring = RawAESKeyring( + # The key namespace and key name are defined by you + # and are used by the raw AES keyring + # to determine whether it should attempt to decrypt + # an encrypted data key. + # + # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html#use-raw-aes-keyring + key_namespace="some managed raw keys", + key_name="my AES wrapping key", + wrapping_key=key, + ) + ``` + +1. Encrypt plaintext data. + + ```python + # Encrypt your plaintext data. + ciphertext, _encrypt_header = aws_encryption_sdk.encrypt( + source=source_plaintext, encryption_context=encryption_context, keyring=keyring + ) + ``` + +1. Compare ciphertext to plaintext. + + ```python + # Demonstrate that the ciphertext and plaintext are different. + assert ciphertext != source_plaintext + ``` + +1. Decrypt encrypted data. + + ```python + # Decrypt your encrypted data using the same keyring you used on encrypt. + # + # You do not need to specify the encryption context on decrypt + # because the header of the encrypted message includes the encryption context. + decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring) + ``` + +1. Compare the decrypted plaintext and original plaintext. + + ```python + # Demonstrate that the decrypted plaintext is identical to the original plaintext. + assert decrypted == source_plaintext + ``` + +1. Verify the encryption context. + + ```python + # Verify that the encryption context used in the decrypt operation includes + # the encryption context that you specified when encrypting. + # The AWS Encryption SDK can add pairs, so don't require an exact match. + # + # In production, always use a meaningful encryption context. + assert set(encryption_context.items()) <= set(decrypt_header.encryption_context.items()) + ``` From 6f12febcf665d81b2910a646321dce5391f7a039 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 20 Jul 2020 12:35:02 -0700 Subject: [PATCH 3/3] docs: standardize markdown ordered list indent --- .../raw-keyrings/raw-aes-keyring.md | 168 +++++++++--------- 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md b/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md index 1d47b015..914aaee2 100644 --- a/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md +++ b/examples/templates/configuration/raw-keyrings/raw-aes-keyring.md @@ -46,87 +46,87 @@ in this document are to be interpreted as described in ## Steps -1. Define encryption context. - - ```python - # Prepare your encryption context. - # Remember that your encryption context is NOT SECRET. - # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context - encryption_context = { - "encryption": "context", - "is not": "secret", - "but adds": "useful metadata", - "that can help you": "be confident that", - "the data you are handling": "is what you think it is", - } - ``` - -1. Generate the wrapping key. - - ```python - # Generate a 256-bit (32 byte) AES key to use with your keyring. - # - # In practice, you should get this key from a secure key management system such as an HSM. - key = os.urandom(32) - ``` - -1. Create keyring. - - ```python - # Create the keyring that determines how your data keys are protected. - keyring = RawAESKeyring( - # The key namespace and key name are defined by you - # and are used by the raw AES keyring - # to determine whether it should attempt to decrypt - # an encrypted data key. - # - # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html#use-raw-aes-keyring - key_namespace="some managed raw keys", - key_name="my AES wrapping key", - wrapping_key=key, - ) - ``` - -1. Encrypt plaintext data. - - ```python - # Encrypt your plaintext data. - ciphertext, _encrypt_header = aws_encryption_sdk.encrypt( - source=source_plaintext, encryption_context=encryption_context, keyring=keyring - ) - ``` - -1. Compare ciphertext to plaintext. - - ```python - # Demonstrate that the ciphertext and plaintext are different. - assert ciphertext != source_plaintext - ``` - -1. Decrypt encrypted data. - - ```python - # Decrypt your encrypted data using the same keyring you used on encrypt. - # - # You do not need to specify the encryption context on decrypt - # because the header of the encrypted message includes the encryption context. - decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring) - ``` - -1. Compare the decrypted plaintext and original plaintext. - - ```python - # Demonstrate that the decrypted plaintext is identical to the original plaintext. - assert decrypted == source_plaintext - ``` - -1. Verify the encryption context. - - ```python - # Verify that the encryption context used in the decrypt operation includes - # the encryption context that you specified when encrypting. - # The AWS Encryption SDK can add pairs, so don't require an exact match. - # - # In production, always use a meaningful encryption context. - assert set(encryption_context.items()) <= set(decrypt_header.encryption_context.items()) - ``` +1. Define encryption context. + + ```python + # Prepare your encryption context. + # Remember that your encryption context is NOT SECRET. + # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context + encryption_context = { + "encryption": "context", + "is not": "secret", + "but adds": "useful metadata", + "that can help you": "be confident that", + "the data you are handling": "is what you think it is", + } + ``` + +1. Generate the wrapping key. + + ```python + # Generate a 256-bit (32 byte) AES key to use with your keyring. + # + # In practice, you should get this key from a secure key management system such as an HSM. + key = os.urandom(32) + ``` + +1. Create keyring. + + ```python + # Create the keyring that determines how your data keys are protected. + keyring = RawAESKeyring( + # The key namespace and key name are defined by you + # and are used by the raw AES keyring + # to determine whether it should attempt to decrypt + # an encrypted data key. + # + # https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html#use-raw-aes-keyring + key_namespace="some managed raw keys", + key_name="my AES wrapping key", + wrapping_key=key, + ) + ``` + +1. Encrypt plaintext data. + + ```python + # Encrypt your plaintext data. + ciphertext, _encrypt_header = aws_encryption_sdk.encrypt( + source=source_plaintext, encryption_context=encryption_context, keyring=keyring + ) + ``` + +1. Compare ciphertext to plaintext. + + ```python + # Demonstrate that the ciphertext and plaintext are different. + assert ciphertext != source_plaintext + ``` + +1. Decrypt encrypted data. + + ```python + # Decrypt your encrypted data using the same keyring you used on encrypt. + # + # You do not need to specify the encryption context on decrypt + # because the header of the encrypted message includes the encryption context. + decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring) + ``` + +1. Compare the decrypted plaintext and original plaintext. + + ```python + # Demonstrate that the decrypted plaintext is identical to the original plaintext. + assert decrypted == source_plaintext + ``` + +1. Verify the encryption context. + + ```python + # Verify that the encryption context used in the decrypt operation includes + # the encryption context that you specified when encrypting. + # The AWS Encryption SDK can add pairs, so don't require an exact match. + # + # In production, always use a meaningful encryption context. + assert set(encryption_context.items()) <= set(decrypt_header.encryption_context.items()) + ```