doc(examples): Add example README

Author: MatthewBennington

README.md

@@ -57,6 +57,12 @@ Run the test vector suite after [set up](testVector/README.md) with:
 dotnet test testVectors
 ```
 
+Run tests on examples, to ensure they are up to date:
+
+```
+dotnet test examples/dotnet
+```
+
 Please note that tests and test vectors require internet access and valid AWS credentials, since calls to KMS are made as part of the test workflow.
 
 ## License

examples/dotnet/README.md

@@ -0,0 +1,85 @@
+# AWS Encryption SDK for .NET Examples
+
+This section features examples that show you
+how to use the AWS Encryption SDK.
+We demonstrate how to use the encryption and decryption APIs
+and how to set up some common configuration patterns.
+
+## APIs
+
+The AWS Encryption SDK provides two high-level APIs:
+one-step APIs that process the entire operation in memory
+and streaming APIs.
+
+You can find examples that demonstrate these APIs
+in the [`examples/dotnet/`](./) directory.
+
+* [How to encrypt and decrypt](./) *TODO*
+* [How to change the algorithm suite](./) *TODO*
+* [How to encrypt and decrypt data streams in memory](./) *TODO*
+* [How to encrypt and decrypt data streamed between files](./) *TODO*
+
+## Configuration
+
+To use the encryption and decryption APIs,
+you need to describe how you want the library to protect your data keys.
+You can do this by configuring
+[keyrings](#keyrings) or [cryptographic materials managers](#cryptographic-materials-managers).
+These examples will show you how to use the configuration tools that we include for you
+and how to create some of your own.
+We start with AWS KMS examples, then show how to use other wrapping keys.
+
+* Using AWS Key Management Service (AWS KMS) Keyring
+    * [How to use one AWS KMS CMK](./) *TODO*
+    * [How to use multiple AWS KMS CMKs in different regions](./) *TODO*
+    * [How to decrypt when you don't know the CMK](./) *TODO*
+    * [How to decrypt within a region](./) *TODO*
+    * [How to decrypt with a preferred region but failover to others](./) *TODO*
+    * [How to reproduce the behavior of an AWS KMS master key provider](./) *TODO*
+* Using raw wrapping keys
+    * [How to use a raw AES wrapping key](./keyrings/RawRSAKeyring/RawAESKeyringExample.cs)
+    * [How to use a raw RSA wrapping key](./) *TODO*
+    * [How to use a raw RSA wrapping key when the key is PEM or DER encoded](./) *TODO*
+    * [How to encrypt with a raw RSA public key wrapping key without access to the private key](./) *TODO*
+* Combining wrapping keys
+    * [How to combine AWS KMS with an offline escrow key](./) *TODO*
+* How to reuse data keys across multiple messages
+    * [with the caching cryptographic materials manager](./) *TODO*
+* How to restrict algorithm suites
+    * [with a custom cryptographic materials manager](./) *TODO*
+* How to require encryption context fields
+    * [with a custom cryptographic materials manager](./) *TODO*
+
+### Keyrings
+
+Keyrings are the most common way for you to configure the AWS Encryption SDK.
+They determine how the AWS Encryption SDK protects your data.
+You can find these examples in [`examples/dotnet/keyrings`](./keyring).
+
+### Cryptographic Materials Managers
+
+Keyrings define how your data keys are protected,
+but there is more going on here than just protecting data keys.
+
+Cryptographic materials managers give you higher-level controls
+over how the AWS Encryption SDK protects your data.
+This can include things like
+enforcing the use of certain algorithm suites or encryption context settings,
+reusing data keys across messages,
+or changing how you interact with keyrings.
+You can find these examples in
+[`examples/dotnet/CryptoMaterialsManager`](./CryptoMaterialsManager).
+
+# Writing Examples
+
+If you want to contribute a new example, that's awesome!
+To make sure that your example is tested in our CI,
+please make sure that it meets the following requirements:
+
+1. The example MUST be a distinct module in the [`examples/dotnet/`](./) directory.
+1. The example MAY be nested arbitrarily deeply.
+1. Each example file MUST contain exactly one example.
+1. Each example filename MUST be descriptive.
+1. Each example file MUST contain a public class matching the filename.
+1. Each example file MUST contain a method called `run` that runs the example.
+1. Each example MUST be exercised by a `[Fact]` test method within its class.

examples/dotnet/RawAESKeyring/RawAESKeyringExample.cs

@@ -0,0 +1,91 @@
+// This example 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 encrypt and decrypt APIs.
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+
+using AWSEncryptionSDK;
+using KeyringDefs;
+using RawAESKeyringDef;
+
+using Org.BouncyCastle.Security; // In this example, we use BouncyCastle to generate a wrapping key.
+
+using ExampleUtils;
+using Xunit;
+
+/// Demonstrate an encrypt/decrypt cycle using a raw AES keyring.
+public class RawAESKeyringExample {
+    static void Run(MemoryStream plaintext) {
+
+        // Create 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
+        IDictionary<string, string> encryptionContext = new Dictionary<string, string>() {
+            {"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"}
+        };
+
+        // Generate a 256-bit AES key to use with your keyring.
+        // Here we use BouncyCastle, but you don't have to.
+        //
+        // In practice, you should get this key from a secure key management system such as an HSM.
+        byte[] key = GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey();
+
+        // 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
+        byte[] keyName = Encoding.UTF8.GetBytes("My 256-bit AES wrapping key");
+        byte[] keyNamespace = Encoding.UTF8.GetBytes("Some managed raw keys");
+
+        // Create the keyring that determines how your data keys are protected.
+        RawAESKeyring keyring = AWSEncryptionSDK.Keyrings.MakeRawAESKeyring(
+                keyNamespace,
+                keyName,
+                key,
+                DafnyFFI.AESWrappingAlgorithm.AES_GCM_256
+                );
+
+        // Encrypt your plaintext data.
+        MemoryStream ciphertext = AWSEncryptionSDK.Client.Encrypt(new AWSEncryptionSDK.Client.EncryptRequest{
+                plaintext = plaintext,
+                keyring = keyring,
+                encryptionContext = encryptionContext
+                });
+
+        // Demonstrate that the ciphertext and plaintext are different.
+        Assert.NotEqual(ciphertext.ToArray(), plaintext.ToArray());
+
+        // 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.
+        MemoryStream decrypted = AWSEncryptionSDK.Client.Decrypt(new AWSEncryptionSDK.Client.DecryptRequest{
+                message = ciphertext,
+                keyring = keyring
+                });
+
+        // Demonstrate that the decrypted plaintext is identical to the original plaintext.
+        Assert.Equal(decrypted.ToArray(), plaintext.ToArray());
+        // 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.
+        // TODO: Add logic that checks the encryption context.
+    }
+
+    // We test examples to ensure they remain up-to-date.
+    [Fact]
+    public void TestRawAESKeyringExample() {
+        Run(ExampleUtils.ExampleUtils.GetPlaintextStream());
+    }
+}