diff --git a/examples/extendable.md b/examples/extendable.md new file mode 100644 index 00000000..e8cbb01d --- /dev/null +++ b/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. diff --git a/examples/extendables/client-supplier/regional-role-client-supplier.md b/examples/extendables/client-supplier/regional-role-client-supplier.md new file mode 100644 index 00000000..19959875 --- /dev/null +++ b/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. +```