chore(rust-release): add Rust release directory (#709)

AwsEncryptionSDK/runtimes/rust/RELEASE.md

@@ -0,0 +1,17 @@
+To publish a new version of the aws-esdk for version N.N.N
+
+1. Acquire the appropriate permissions
+1. Ensure git checkout of main is fresh and clean
+1. ./start_release.sh N.N.N
+1. `cd ../../../releases/rust/esdk`
+1. Create a PR with all changed or added files
+1. Within the PR, make sure you also:
+   1. Update the `CHANGELOG.md` inside AwsEncryptionSDK/runtimes/rust/ with the changes
+   1. If this is a major version bump, update the `SUPPORT_POLICY.rst` for Rust
+   1. Get the PR reviewed by a teammate
+   1. Before merging the PR, publish the new version of the `aws-esdk` crate and test the published crate (documented in next steps)
+1. Run `cargo publish`
+1. `cd ../../../AwsEncryptionSDK/runtimes/rust/` # i.e. return here
+1. ./test_published.sh N.N.N
+1. Ignore/stash the changes in `AwsEncryptionSDK/runtimes/rust/test_examples/Cargo.toml` which adds the `aws-esdk` crate
+1. Merge the release PR

AwsEncryptionSDK/runtimes/rust/start_release.sh

@@ -0,0 +1,54 @@
+#!/bin/bash -eu
+
+# Check if exactly one argument is provided
+if [ "$#" -ne 1 ]; then
+    echo 1>&2 "USAGE: start_release.sh N.N.N"
+    exit 1
+fi
+
+# Go to the directory of this script
+cd $( dirname ${BASH_SOURCE[0]} )
+
+# Check if the provided argument matches the version pattern
+REGEX_VERSION='^\d+\.\d+\.\d+$'
+MATCHES=$(echo "$1" | egrep $REGEX_VERSION | wc -l)
+if [ $MATCHES -eq 0 ]; then
+   echo 1>&2 "Version \"$1\" must be N.N.N"
+   exit 1
+fi
+
+# Update the version in Cargo.toml
+perl -pe "s/^version = .*$/version = \"$1\"/" < Cargo.toml > new_Cargo.toml
+mv new_Cargo.toml Cargo.toml
+
+# Remove all files and directories in src except for specified files
+find src -depth 1 | egrep -v '(lib.rs)' | xargs rm -rf
+
+# Change to the parent directory and run make polymorph and transpile commands
+cd ../..
+make polymorph_rust transpile_rust test_rust
+
+# Remove target directory
+cd runtimes/rust
+rm -rf target
+
+# Remove existing release directory and copy current directory to releases
+rm -rf ../../../releases/rust/esdk
+cp -r . ../../../releases/rust/esdk
+
+# Go to the release directory
+cd ../../../releases/rust/esdk
+
+# Remove unnecessary files and directories
+rm -rf *~ copy_externs.sh start_release.sh test_published.sh test_examples *.pem RELEASE.md CHANGELOG.md
+
+# Create .gitignore file with specified entries
+echo Cargo.lock > .gitignore
+echo target >> .gitignore
+
+# Run cargo test and example tests
+cargo test
+cargo test --release --examples
+
+# Remove Cargo.lock and .pem files after testing the examples
+rm -f Cargo.lock *.pem

AwsEncryptionSDK/runtimes/rust/test_examples/.gitignore

@@ -0,0 +1,3 @@
+*~
+*.pem
+src

AwsEncryptionSDK/runtimes/rust/test_examples/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "aws-esdk-examples"
+edition = "2021"
+rust-version = "1.80.0"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+aws-config = "1.5.10"
+aws-lc-rs = "1.11.1"
+aws-lc-sys = "0.23.1"
+aws-sdk-dynamodb = "1.55.0"
+aws-sdk-kms = "1.51.0"
+aws-smithy-runtime-api = {version = "1.7.3", features = ["client"] }
+aws-smithy-types = "1.2.9"
+chrono = "0.4.38"
+dafny-runtime = "0.1.1"
+dashmap = "6.1.0"
+pem = "3.0.4"
+rand = "0.8.5"
+tokio = {version = "1.42.0", features = ["full"] }
+uuid = { version = "1.11.0", features = ["v4"] }

AwsEncryptionSDK/runtimes/rust/test_published.sh

@@ -0,0 +1,39 @@
+#!/bin/bash -eu
+
+# Check if exactly one argument is provided
+if [ "$#" -ne 1 ]; then
+    echo 1>&2 "USAGE: test_published.sh N.N.N"
+    exit 1
+fi
+
+# Go to the directory of this script
+cd $( dirname ${BASH_SOURCE[0]} )
+
+# Check if the provided argument matches the version pattern
+REGEX_VERSION='^\d+\.\d+\.\d+$'
+echo "$1" | egrep -q $REGEX_VERSION
+if [ $? -ne 0 ]; then
+   echo 1>&2 "Version \"$1\" must be N.N.N"
+   exit 1
+fi
+
+VERSION=$1
+
+# Update examples in test_examples directory
+rm -rf test_examples/src
+cp -r examples test_examples/src/
+cd test_examples
+
+# Add aws-esdk
+cargo add aws-esdk
+
+# Check if the added version matches the provided version
+MATCH=$(fgrep "aws-esdk = \"$VERSION\"" Cargo.toml | wc -l)
+if [ $MATCH -eq "0" ]; then
+    echo Version $VERSION of aws-esdk not the most recent
+    egrep '^aws-esdk' Cargo.toml
+    exit 1
+fi
+
+# Run the cargo project
+cargo test --release

releases/rust/esdk/.gitignore

@@ -0,0 +1,2 @@
+Cargo.lock
+target

releases/rust/esdk/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "aws-esdk"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.80.0"
+keywords = ["cryptography", "security", "dynamodb", "encryption", "client-side"]
+license = "ISC AND (Apache-2.0 OR ISC)"
+description = "aws-esdk is a library for implementing client side encryption."
+homepage = "https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html"
+repository = "https://github.com/aws/aws-encryption-sdk-dafny/releases/rust/esdk/"
+authors = ["AWS-CryptoTools"]
+documentation = "https://docs.rs/crate/aws-esdk"
+autoexamples = false
+readme = "README.md"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+aws-config = "1.5.10"
+aws-lc-rs = "1.11.1"
+aws-lc-sys = "0.23.1"
+aws-sdk-dynamodb = "1.55.0"
+aws-sdk-kms = "1.51.0"
+aws-smithy-runtime-api = {version = "1.7.3", features = ["client"] }
+aws-smithy-types = "1.2.9"
+chrono = "0.4.38"
+dafny-runtime = "0.1.1"
+dashmap = "6.1.0"
+pem = "3.0.4"
+rand = "0.8.5"
+tokio = {version = "1.42.0", features = ["full"] }
+uuid = { version = "1.11.0", features = ["v4"] }
+
+[[example]]
+name = "main"

releases/rust/esdk/README.md

@@ -0,0 +1,64 @@
+# AWS Encryption SDK for Rust
+
+AWS Encryption SDK for Rust
+
+## Using the AWS Encryption SDK for Rust
+
+The AWS Encryption SDK is available on [Crates.io](https://www.crates.io/).
+
+For more details about the design and architecture of the AWS Encryption SDK, see the [AWS Encryption SDK Developer Guide](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html).
+
+## Building the AWS Encryption SDK for Rust
+
+To build, the AWS Encryption SDK requires the most up to date version of [Dafny](https://github.com/dafny-lang/dafny) on your PATH.
+
+You will also need to ensure that you fetch all submodules using either `git clone --recursive ...` when cloning the repository or `git submodule update --init` on an existing clone.
+
+To setup your project to use the AWS Encryption SDK in Rust, run:
+
+```
+cd AwsEncryptionSDK
+# Polymorph smithy to Rust
+make polymorph_rust
+# Transpile Dafny to Rust
+make transpile_rust
+```
+
+### (Optional) Set up the AWS Encryption SDK to work with AWS KMS
+
+If you set up the AWS Encryption SDK to use the AWS KMS Keyring,
+the AWS Encryption SDK will make calls to AWS KMS on your behalf,
+using the appropriate AWS SDK.
+
+However, you must first set up AWS credentials for use with the AWS SDK.
+
+## Testing the AWS Encryption SDK for Rust
+
+### Configure AWS credentials
+
+To run the test suite you must first set up AWS credentials for use with the AWS SDK.
+This is required in order to run the integration tests, which use a KMS Keyring against a publicly accessible KMS CMK.
+
+### Run the tests
+
+Run the test suite with:
+
+```
+cd AwsEncryptionSDK
+make test_rust
+```
+
+Run tests on examples, to ensure they are up to date:
+
+```
+cd AwsEncryptionSDK/runtimes/rust/
+cargo test --examples
+```
+
+Please look at the Examples on how to use the Encryption SDK in Rust [here](examples).
+
+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
+
+This library is licensed under the Apache 2.0 License.

releases/rust/esdk/examples/README.md

@@ -0,0 +1,90 @@
+# AWS Encryption SDK for Rust 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/`](./) directory.
+
+* [How to encrypt and decrypt](./keyring/aws_kms_keyring_example.rs)
+* [How to change the algorithm suite](./set_encryption_algorithm_suite_example.rs)
+* [How to set the commitment policy](./set_commitment_policy_example.rs)
+* [How to limit the number of encrypted data keys (EDKs)](./limit_encrypted_data_keys_example.rs)
+
+## 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)
+    * [How to use one AWS KMS key](./keyring/aws_kms_keyring_example.rs)
+    * [How to use multiple AWS KMS keys in different regions](./keyring/aws_kms_mrk_discovery_multi_keyring_example.rs)
+    * [How to decrypt when you don't know the AWS KMS key](./keyring/aws_kms_discovery_keyring_example.rs)
+    * [How to limit decryption to a single region](./keyring/aws_kms_mrk_discovery_keyring_example.rs)
+    * [How to decrypt with a preferred region but failover to others](./keyring/aws_kms_mrk_discovery_multi_keyring_example.rs)
+    * [How to reproduce the behavior of an AWS KMS master key provider](./keyring/aws_kms_multi_keyring_example.rs)
+* Using raw wrapping keys
+    * [How to use a raw AES wrapping key](./keyring/raw_aes_keyring_example.rs)
+    * [How to use a raw RSA wrapping key](./keyring/raw_rsa_keyring_example.rs)
+* Combining wrapping keys
+    * [How to combine AWS KMS with an offline escrow key](./keyring/multi_keyring_example.rs)
+* How to restrict algorithm suites
+    * [with a custom cryptographic materials manager](./cryptographic_materials_manager/restrict_algorithm_suite/signing_suite_only_cmm.rs)
+
+### 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/keyring`](./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/cryptographic_materials_manager`](./cryptographic_materials_manager).
+
+### Client Supplier
+
+The AWS Encryption SDK creates AWS KMS clients when interacting with AWS KMS.
+In case the default AWS KMS client configuration doesn't suit your needs,
+you can configure clients by defining a custom Client Supplier.
+For example, your Client Supplier could tune
+the retry and timeout settings on the client, or use different credentials
+based on which region is being called. In our
+[regional_role_client_supplier](./client_supplier/regional_role_client_supplier.rs)
+example, we show how you can build a custom Client Supplier which
+creates clients by assuming different IAM roles for different regions.
+
+# 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 subdirectory or file in the [`examples/`](./) directory.
+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;`.
+1. Each example file MUST contain exactly one example.
+1. Each example filename MUST be descriptive.
+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).
+1. Each example MUST also be called inside the `main` function of [main.rs](./main.rs).