|
1 | | -# TODO: Update for Rust |
| 1 | +# AWS Encryption SDK for Rust Examples |
| 2 | + |
| 3 | +This section features examples that show you |
| 4 | +how to use the AWS Encryption SDK. |
| 5 | +We demonstrate how to use the encryption and decryption APIs |
| 6 | +and how to set up some common configuration patterns. |
| 7 | + |
| 8 | +## APIs |
| 9 | + |
| 10 | +The AWS Encryption SDK provides two high-level APIs: |
| 11 | +one-step APIs that process the entire operation in memory |
| 12 | +and streaming APIs. |
| 13 | + |
| 14 | +You can find examples that demonstrate these APIs |
| 15 | +in the [`examples/`](./) directory. |
| 16 | + |
| 17 | +* [How to encrypt and decrypt](./keyring/aws_kms_keyring_example.rs) |
| 18 | +* [How to change the algorithm suite](./set_encryption_algorithm_suite_example.rs) |
| 19 | +* [How to set the commitment policy](./set_commitment_policy_example.rs) |
| 20 | +* [How to limit the number of encrypted data keys (EDKs)](./limit_encrypted_data_keys_example.rs) |
| 21 | + |
| 22 | +## Configuration |
| 23 | + |
| 24 | +To use the encryption and decryption APIs, |
| 25 | +you need to describe how you want the library to protect your data keys. |
| 26 | +You can do this by configuring |
| 27 | +[keyrings](#keyrings) or [cryptographic materials managers](#cryptographic-materials-managers). |
| 28 | +These examples will show you how to use the configuration tools that we include for you |
| 29 | +and how to create some of your own. |
| 30 | +We start with AWS KMS examples, then show how to use other wrapping keys. |
| 31 | + |
| 32 | +* Using AWS Key Management Service (AWS KMS) |
| 33 | + * [How to use one AWS KMS key](./keyring/aws_kms_keyring_example.rs) |
| 34 | + * [How to use multiple AWS KMS keys in different regions](./keyring/aws_kms_mrk_discovery_multi_keyring_example.rs) |
| 35 | + * [How to decrypt when you don't know the AWS KMS key](./keyring/aws_kms_discovery_keyring_example.rs) |
| 36 | + * [How to limit decryption to a single region](./keyring/aws_kms_mrk_discovery_keyring_example.rs) |
| 37 | + * [How to decrypt with a preferred region but failover to others](./keyring/aws_kms_mrk_discovery_multi_keyring_example.rs) |
| 38 | + * [How to reproduce the behavior of an AWS KMS master key provider](./keyring/aws_kms_multi_keyring_example.rs) |
| 39 | +* Using raw wrapping keys |
| 40 | + * [How to use a raw AES wrapping key](./keyring/raw_aes_keyring_example.rs) |
| 41 | + * [How to use a raw RSA wrapping key](./keyring/raw_rsa_keyring_example.rs) |
| 42 | +* Combining wrapping keys |
| 43 | + * [How to combine AWS KMS with an offline escrow key](./keyring/multi_keyring_example.rs) |
| 44 | +* How to restrict algorithm suites |
| 45 | + * [with a custom cryptographic materials manager](./cryptographic_materials_manager/restrict_algorithm_suite/signing_suite_only_cmm.rs) |
| 46 | + |
| 47 | +### Keyrings |
| 48 | + |
| 49 | +Keyrings are the most common way for you to configure the AWS Encryption SDK. |
| 50 | +They determine how the AWS Encryption SDK protects your data. |
| 51 | +You can find these examples in [`examples/keyring`](./keyring). |
| 52 | + |
| 53 | +### Cryptographic Materials Managers |
| 54 | + |
| 55 | +Keyrings define how your data keys are protected, |
| 56 | +but there is more going on here than just protecting data keys. |
| 57 | + |
| 58 | +Cryptographic materials managers give you higher-level controls |
| 59 | +over how the AWS Encryption SDK protects your data. |
| 60 | +This can include things like |
| 61 | +enforcing the use of certain algorithm suites or encryption context settings, |
| 62 | +reusing data keys across messages, |
| 63 | +or changing how you interact with keyrings. |
| 64 | +You can find these examples in |
| 65 | +[`examples/cryptographic_materials_manager`](./cryptographic_materials_manager). |
| 66 | + |
| 67 | +### Client Supplier |
| 68 | + |
| 69 | +The AWS Encryption SDK creates AWS KMS clients when interacting with AWS KMS. |
| 70 | +In case the default AWS KMS client configuration doesn't suit your needs, |
| 71 | +you can configure clients by defining a custom Client Supplier. |
| 72 | +For example, your Client Supplier could tune |
| 73 | +the retry and timeout settings on the client, or use different credentials |
| 74 | +based on which region is being called. In our |
| 75 | +[regional_role_client_supplier](./client_supplier/regional_role_client_supplier.rs) |
| 76 | +example, we show how you can build a custom Client Supplier which |
| 77 | +creates clients by assuming different IAM roles for different regions. |
| 78 | + |
| 79 | +# Writing Examples |
| 80 | + |
| 81 | +If you want to contribute a new example, that's awesome! |
| 82 | +To make sure that your example is tested in our CI, |
| 83 | +please make sure that it meets the following requirements: |
| 84 | + |
| 85 | +1. The example MUST be a distinct subdirectory or file in the [`examples/`](./) directory. |
| 86 | +1. The example MAY be nested arbitrarily deeply. However, each example file MUST be added to the `mod.rs` files appropriately according to the directory structure. If the example is in the root directory [`examples/`](./), you MUST also add the module to the [`main.rs`](./main.rs) file. For instance, `pub mod set_commitment_policy_example;`. |
| 87 | +1. Each example file MUST contain exactly one example. |
| 88 | +1. Each example filename MUST be descriptive. |
| 89 | +1. Each example file MUST contain a testing function with the attribute `#[tokio::test(flavor = "multi_thread")]` just like the one at the end of the [KMS Keyring](./keyring/aws_kms_keyring_example.rs). |
| 90 | +1. Each example MUST also be called inside the `main` function of [main.rs](./main.rs). |
0 commit comments