Revise Examples

[ttjsu-aws]

The AWS Encryption SDK Examples in Python is not intuitive/simple to understand. The API usage is not immediately apparent and is buried in a lot of details.

It would be useful to have examples that are a combination of the commonly used APIs, algorithm suites and the type of data (string/stream) to be encrypted/decrypted.

A. Commonly used APIs :

1. Encrypt/Decrypt using one KMS CMK
2. Encrypt/Decrypt using multiple KMS CMKs in Multiple Regions
3. Decrypt using KMS CMK with the client provider
4. Decrypt using KMS Discovery with region limits/filters
5. Decrypt using KMS generic discovery
6. Encrypt/Decrypt using Multi-KR/Multi-MKP
7. Caching 1:1 local cache: caching cmm
8. Caching 1:n local cache: caching cmm

Once we have the Keyring Implementation: #146

9. Encrypt/ Decrypt using Raw AES Keyring
10. Encrypt using Raw RSA Keyring (public-key)
11. Decrypt using Raw RSA Keyring (public and private)
12. Encrypt/Decrypt using KMS Keyring
13. Encrypt/Decrypt using Multi-Keyring

B. Types of data for encryption/decryption:

1. One shot/ string
2. Streaming data

C. Commonly used Algorithm Suite:

1. Default Algorithm Suite AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 with P-384 and SHA-384
2. Default w/o signing AES256_GCM_IV12_TAG16_HKDF_SHA256

Examples:

• A1.B1.C1 docs: add master key provider examples #236
• A1.B2.C1 docs: add master key provider examples #236
• A1.B1.C2 docs: add master key provider examples #236
• A2.B1.C1 Example for using multiple keys in multiple regions #177
• A3.B1.C1 docs: add master key provider examples #236
• A4.B1.C1 docs: add master key provider examples #236
• A5.B1.C1 docs: add master key provider examples #236
• A6.B1.C1 docs: add master key provider examples #236
• A7.B1.C1 docs: add CMM examples #239
• A8.B1.C1 docs: add CMM examples #239
• A9.B1.C1 docs: add keyring examples #221
• A10.B1.C1 docs: add keyring examples #221
• A11.B1.C1 docs: add keyring examples #221
• A12.B1.C1 docs: add keyring examples #221
• A13.B1.C1 docs: add keyring examples #221

Also, be sure to include/update the README to help navigate through the examples.

[mattsb42-aws]

I think we can safely stick with one B/C path for all but one A path.

ie:

• A1.B1.C1
• A1.B2.C1
• A1.B1.C2
• A2.B1.C1
• A3.B1.C1
• A4.B1.C1
• A5.B1.C1
• A6.B1.C1
• A7.B1.C1
• A8.B1.C1
• A9.B1.C1
• A10.B1.C1
• A11.B1.C1
• A12.B1.C1
• A13.B1.C1

That lets us show the full set of paths without duplicating effort too much.

[ttjsu-aws]

Thanks @mattsb42-aws , updated the description.

[juneb]

Related to customer feedback on the example in the Encryption SDK Developer Guide.
https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/python-example-code.html

The assert in the Encrypting and Decrypting Strings example doesn't work because the decrypted plaintext is not a string.

[caitlin-tibbetts]

Related to customer feedback on the example in the Encryption SDK Developer Guide.
https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/python-example-code.html

The assert in the Encrypting and Decrypting Strings example doesn't work because the decrypted plaintext is not a string.

@juneb Yeah, definitely, that example should probably be called "Encrypting and Decrypting Bytes" because the source_plaintext is supposed to be bytes according to the docstring, so it would definitely fail if one were to input a str.

[mattsb42-aws]

encrypt actually happily accepts either bytes or str; the issue is that if you always get back bytes.

This is perhaps a case of us being too lenient on our inputs, but that is the decision we made at the time.