feat(Examples): regional role client supplier

examples/extendable.md

@@ -0,0 +1,56 @@
+[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
+[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
+
+# Required Interface Demonstrations
+
+## Version
+
+0.1.0
+
+## Implementations
+
+- [Net](https://github.com/aws/aws-encryption-sdk-dafny/tree/develop/aws-encryption-sdk-net/Examples)
+  - [Regional Client Supplier](https://github.com/aws/aws-encryption-sdk-dafny/blob/develop/aws-encryption-sdk-net/Examples/ClientSupplier/RegionalRoleClientSupplier.cs)
+
+## Overview
+
+Every implementation MUST include an example implementation
+for every customer extendable class or interface in the Encryption SDK.
+
+See [example/extendables](./extendables) for specific implementations.
+
+## 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).
+
+## Requirements
+
+- Every example extendable MUST be tested
+  as part of the continous integration testing.
+- Everty example extendable MUST be independent and complete.
+- Every example extendable SHOULD follow this layout:
+
+  - In a directory named for the extendable interface/class,
+  - In a directory named for the example,
+  - two files should exsist:
+    - The implementation of the extendable interface/class,
+    - An example that utilizes it.
+
+- Every example extendable MUST only contain logic that is reasonable for production use.
+- If an example extendable MUST contain logic that is not reasonable for production use,
+  it MUST include clear comments identifying that logic as such
+  and instructing the reader what they SHOULD do instead.
+
+### Example Extendable Templates
+
+For each extendable, there MUST be directory under [example/extendables](./extendables).
+Each example extendable MUST be in the appropriate directory.
+Example extendables MUST include sufficent code to clearly demonstrate
+how to implement the interface and
+how to use the implemented interface.

examples/extendables/client-supplier/regional-role-client-supplier.md

@@ -0,0 +1,153 @@
+[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
+[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
+
+# Regional Role Client Supplier
+
+Implementations of this MUST follow the rules defined in
+[Example Extendables](../../../extendable.md).
+
+## Implementations
+
+- [Net](https://github.com/aws/aws-encryption-sdk-dafny/blob/develop/aws-encryption-sdk-net/Examples/ClientSupplier/RegionalRoleClientSupplier.cs)
+
+## 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).
+
+## Regional Role Client Supplier Class
+
+### Header
+
+```
+Demonstrates implementing a Custom Client Supplier.
+This Client Supplier will create KMS Clients with different IAM roles,
+depending on the Region passed.
+```
+
+### Class
+
+#### Properties/Fields
+
+- **RegionIAMRoleMap**:
+  Maps a Region to the Arn of the
+  IAM Role the client supplier will
+  use when supplying a client.
+- **STSClient**:
+  Amazon Security Token Service, or STS,
+  allows customers to fetch
+  temporary credentials.
+
+#### Methods
+
+##### GetClient
+
+```
+This is the meat of a Client Supplier.
+Whenever the AWS Encryption SDK needs to create a KMS client,
+it will call GetClient for the regions
+in which it needs to call KMS.
+In this example, we utilize a Dictionary
+to map regions to particular IAM Roles.
+We use Amazon Security Token Service to fetch temporary credentials,
+and then provision a Key Management Service (KMS) Client
+with those credentials and the input region.
+```
+
+### Custom Exceptions
+
+These exceptions MUST extend `AwsCryptographicMaterialProvidersBaseException`.
+
+#### Missing Region Exception
+
+```
+Custom Exceptions SHOULD extend from the Library's Base Exception.
+This is a quirk of using Dafny to generate the Encryption SDK.
+The Encryption SDK will handle dotnet's System.Exception,
+but the exception message will be altered.
+By extending from the Library's Base Exception,
+you can ensure the exception's message will be as intended.
+```
+
+#### Assume Role Exception
+
+```
+At this time, the Encryption SDK only retains exception messages,
+and not the entire stack trace.
+As such, it is helpful to manually log the exceptions
+(ideally, a logging framework would be used, instead of console).
+```
+
+## Client Supplier Example
+
+Implementations of this example MUST follow the rules defined in
+[Example Templates](../../../examples.md#example-templates).
+
+### Header
+
+```
+Demonstrates using a Custom Client Supplier.
+See RegionalRoleClientSupplier.cs for the details of implementing a
+custom client supplier.
+This example uses an AwsKmsMrkDiscoveryMultiKeyring, but all
+the AWS Multi Keyrings take Client Suppliers.
+```
+
+### Summary
+
+```
+Demonstrates using a Custom Client Supplier.
+```
+
+### Inputs
+
+- **plaintext** :
+  Plaintext to encrypt
+- **accountIds** :
+  List of trusted AWS Account Ids
+- **regions** :
+  List of AWS Regions trusted AWS Accounts operate in
+
+### Steps
+
+1. Generate or load a ciphertext encrypted by the KMS Key.
+
+```
+To focus on Client Suppliers, we will rely on a helper method
+to create the encrypted message (ciphertext).
+```
+
+2. Create a KMS Multi Keyring with the `RegionalRoleClientSupplier`
+
+```
+Now create a Discovery keyring to use for decryption.
+We are passing in our Custom Client Supplier.
+This is a Multi Keyring composed of MRK Discovery Keyrings.
+All the keyrings have the same Discovery Filter.
+Each keyring has its own KMS Client,
+which is provisioned by the Custom Client Supplier.
+```
+
+3. Decrypt the ciphertext with created KMS Multi Keyring
+
+4. Verify the encryption context (MAY be done with a helper method)
+
+5. Verify the decrypted plaintext is the same as the original (MAY be done with a helper method)
+
+6. Test the Missing Region Exception
+
+```c#
+// Demonstrate catching a custom exception.
+try {...}
+// Note that the exception returned is NOT a `MissingRegionException`
+catch (MissingRegionException) { throw; }
+// But is cast down to an `AwsCryptographicMaterialProvidersBaseException`.
+catch (AwsCryptographicMaterialProvidersBaseException exception)
+{...}
+// However, the message is as expected.
+```