From 4615785c7fdcd873afa3b2a214ac77bbdee18359 Mon Sep 17 00:00:00 2001 From: 82marbag <69267416+82marbag@users.noreply.github.com> Date: Thu, 3 Aug 2023 21:27:21 +0100 Subject: [PATCH] Add TLS docs page (#2898) ## Motivation and Context The TLS connector page is missing ## Description Render the TLS connector documentation page ## Checklist - [ ] I have updated `CHANGELOG.next.toml` if I made changes to the smithy-rs codegen or runtime crates - [ ] I have updated `CHANGELOG.next.toml` if I made changes to the AWS SDK, generated SDK code, or SDK runtime crates ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._ --------- Signed-off-by: Daniele Ahmed Co-authored-by: david-perez --- design/src/SUMMARY.md | 1 + design/src/transport/connector.md | 44 +++---------------- examples/pokemon-service-tls/Cargo.toml | 3 +- .../pokemon-service-tls/tests/common/mod.rs | 30 +++++++++++++ .../tests/custom_connectors.rs | 29 ++++++++++++ examples/pokemon-service-tls/tests/http2.rs | 14 ------ 6 files changed, 68 insertions(+), 53 deletions(-) create mode 100644 examples/pokemon-service-tls/tests/custom_connectors.rs delete mode 100644 examples/pokemon-service-tls/tests/http2.rs diff --git a/design/src/SUMMARY.md b/design/src/SUMMARY.md index ea3bcb65c..34933fca1 100644 --- a/design/src/SUMMARY.md +++ b/design/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Transport](transport/overview.md) - [HTTP Operations](transport/operation.md) - [HTTP Middleware](transport/middleware.md) + - [TLS Connector](transport/connector.md) - [Smithy](./smithy/overview.md) - [Simple Shapes](./smithy/simple_shapes.md) diff --git a/design/src/transport/connector.md b/design/src/transport/connector.md index cadbcb6dd..edb50d441 100644 --- a/design/src/transport/connector.md +++ b/design/src/transport/connector.md @@ -1,39 +1,7 @@ -The Smithy client provides a default TLS connector, but a custom one can be plugged in. -`rustls` is enabled with the feature flag `rustls`. +The Smithy client provides a default TLS connector, but a custom one can be +plugged in. `rustls` is enabled with the feature flag `rustls`. -The client had previously supported `native-tls`. You can use your custom connector like this. - -Create your connector: - -```rust -/// A `hyper` connector that uses the `native-tls` crate for TLS. To use this in a smithy client, -/// wrap it in a [hyper_ext::Adapter](crate::hyper_ext::Adapter). -pub type NativeTls = hyper_tls::HttpsConnector; - -pub fn native_tls() -> NativeTls { - let mut tls = hyper_tls::native_tls::TlsConnector::builder(); - let tls = tls - .min_protocol_version(Some(hyper_tls::native_tls::Protocol::Tlsv12)) - .build() - .unwrap_or_else(|e| panic!("Error while creating TLS connector: {}", e)); - let mut http = hyper::client::HttpConnector::new(); - http.enforce_http(false); - hyper_tls::HttpsConnector::from((http, tls.into())) -} -``` - -Plug the connector in the client: -```rust -let mut builder = hyper::client::Builder::default(); -builder.pool_max_idle_per_host(70); -let connector = aws_smithy_client::erase::DynConnector::new( - aws_smithy_client::hyper_ext::Adapter::builder() - .hyper_builder(builder) - .connector_settings(std::default::Default::default()) - .build(native_tls()), -); -let raw_client = aws_smithy_client::builder::Builder::new() - .connector(connector) - .middleware_fn(...) - .build_dyn(); -``` +The client had previously (prior to version 0.56.0) supported `native-tls`. You +can continue to use a client whose TLS implementation is backed by `native-tls` +by passing in a custom connector. Check out the `custom_connectors.rs` tests in +the `pokemon-service-tls` example crate. diff --git a/examples/pokemon-service-tls/Cargo.toml b/examples/pokemon-service-tls/Cargo.toml index e1c3b3a08..9f11a904f 100644 --- a/examples/pokemon-service-tls/Cargo.toml +++ b/examples/pokemon-service-tls/Cargo.toml @@ -26,8 +26,9 @@ pokemon-service-common = { path = "../pokemon-service-common/" } assert_cmd = "2.0" serial_test = "1.0.0" -# This dependency is only required for testing the `pokemon-service-tls` program. +# These dependencies are only required for testing the `pokemon-service-tls` program. hyper-rustls = { version = "0.24", features = ["http2"] } +hyper-tls = { version = "0.5" } # Local paths aws-smithy-client = { path = "../../rust-runtime/aws-smithy-client/", features = ["rustls"] } diff --git a/examples/pokemon-service-tls/tests/common/mod.rs b/examples/pokemon-service-tls/tests/common/mod.rs index c56c5fe59..0d69407cf 100644 --- a/examples/pokemon-service-tls/tests/common/mod.rs +++ b/examples/pokemon-service-tls/tests/common/mod.rs @@ -49,3 +49,33 @@ pub fn client_http2_only() -> Client { .build(); Client::from_conf(config) } + +/// A `hyper` connector that uses the `native-tls` crate for TLS. To use this in a smithy client, +/// wrap it in a [aws_smithy_client::hyper_ext::Adapter]. +pub type NativeTlsConnector = hyper_tls::HttpsConnector; + +fn native_tls_connector() -> NativeTlsConnector { + let cert = hyper_tls::native_tls::Certificate::from_pem( + std::fs::read_to_string(DEFAULT_TEST_CERT) + .expect("could not open certificate") + .as_bytes(), + ) + .expect("could not parse certificate"); + + let tls_connector = hyper_tls::native_tls::TlsConnector::builder() + .min_protocol_version(Some(hyper_tls::native_tls::Protocol::Tlsv12)) + .add_root_certificate(cert) + .build() + .unwrap_or_else(|e| panic!("error while creating TLS connector: {}", e)); + let mut http_connector = hyper::client::HttpConnector::new(); + http_connector.enforce_http(false); + hyper_tls::HttpsConnector::from((http_connector, tls_connector.into())) +} + +pub fn native_tls_client() -> Client { + let config = Config::builder() + .http_connector(Adapter::builder().build(native_tls_connector())) + .endpoint_url(format!("https://{DEFAULT_DOMAIN}:{DEFAULT_PORT}")) + .build(); + Client::from_conf(config) +} diff --git a/examples/pokemon-service-tls/tests/custom_connectors.rs b/examples/pokemon-service-tls/tests/custom_connectors.rs new file mode 100644 index 000000000..12c82d55c --- /dev/null +++ b/examples/pokemon-service-tls/tests/custom_connectors.rs @@ -0,0 +1,29 @@ +/* + * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +pub mod common; + +use serial_test::serial; + +#[tokio::test] +#[serial] +// This test invokes an operation with a client that can only send HTTP2 requests and whose TLS +// implementation is backed by `rustls`. +async fn test_check_health_http2_rustls_connector() { + let _child = common::run_server().await; + let client = common::client_http2_only(); + + let _check_health = client.check_health().send().await.unwrap(); +} + +#[tokio::test] +#[serial] +// This test invokes an operation with a client whose TLS implementation is backed by `native_tls`. +async fn test_check_health_native_tls_connector() { + let _child = common::run_server().await; + let client = common::native_tls_client(); + + let _check_health = client.check_health().send().await.unwrap(); +} diff --git a/examples/pokemon-service-tls/tests/http2.rs b/examples/pokemon-service-tls/tests/http2.rs deleted file mode 100644 index 32c0fba08..000000000 --- a/examples/pokemon-service-tls/tests/http2.rs +++ /dev/null @@ -1,14 +0,0 @@ -/* - * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. - * SPDX-License-Identifier: Apache-2.0 - */ - -pub mod common; - -#[tokio::test] -async fn test_check_health_http2() { - let _child = common::run_server().await; - let client = common::client_http2_only(); - - let _check_health = client.check_health().send().await.unwrap(); -} -- GitLab