From dbbb9af4e4d289d6a4495d45b7bb5eda6c243d8d Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 6 Nov 2024 01:49:35 +0000 Subject: [PATCH 1/9] document generating bindings with prebuilt libs2n --- bindings/rust/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index f85fd22ad70..49ab62a9280 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,6 +20,20 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` +Alternatively, rust bindings can be generated using pre-built libs2n by first compiling libs2n, and then running the `generate.sh` script: +``` +cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off +cmake --build build -- -j $(nproc) + +export S2N_TLS_LIB_DIR=`pwd`/build/lib +export S2N_TLS_INCLUDE_DIR=`pwd`/api +export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH + +cd bindings/rust/ +./generate.sh +``` +This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. + ## Minimum Supported Rust Version (MSRV) `s2n-tls` will maintain a rolling MSRV (minimum supported rust version) policy of at least 6 months. The current s2n-quic version is not guaranteed to build on Rust versions earlier than the MSRV. From 2ccf18e1dae2cfbef9fda98246ef8464249c9c23 Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 6 Nov 2024 23:25:36 +0000 Subject: [PATCH 2/9] address PR feedback - document from the perspective of crates consumer - add the same information on crates' readme --- bindings/rust/README.md | 23 ++++++++++++++++++----- bindings/rust/s2n-tls-sys/README.md | 29 ++++++++++++++++++++++++++++- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index 49ab62a9280..0f175f6a6ef 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,18 +20,31 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` -Alternatively, rust bindings can be generated using pre-built libs2n by first compiling libs2n, and then running the `generate.sh` script: +Our Rust bindings support using pre-built libs2n by using the [s2n-tls-sys crate](https://crates.io/crates/s2n-tls-sys) and following the next steps below: + +1. Compile your preferred configuration of s2n-tls. + +You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto) ``` cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off cmake --build build -- -j $(nproc) +``` -export S2N_TLS_LIB_DIR=`pwd`/build/lib -export S2N_TLS_INCLUDE_DIR=`pwd`/api +2. CD into your rust project and set environment variables to libs2n library sources. + +This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys +``` +export S2N_TLS_LIB_DIR=/build/lib +export S2N_TLS_INCLUDE_DIR=/api export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH +``` + +3. Build your project. This triggers the build script for s2n-tls-sys -cd bindings/rust/ -./generate.sh ``` +cargo build +``` + This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. ## Minimum Supported Rust Version (MSRV) diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index e9931479489..111296bef67 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -1,3 +1,30 @@ This crates provides low level rust bindings for [s2n-tls](https://github.com/aws/s2n-tls) which are autogenerated with [bindgen](https://github.com/rust-lang/rust-bindgen) -This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. \ No newline at end of file +This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. + +This crate supports using pre-built libs2n following the next steps below: + +1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. + +You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto) +``` +cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off +cmake --build build -- -j $(nproc) +``` + +2. CD into your rust project and set environment variables to libs2n library sources. + +This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys +``` +export S2N_TLS_LIB_DIR=/build/lib +export S2N_TLS_INCLUDE_DIR=/api +export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH +``` + +3. Build your project. This triggers the build script for s2n-tls-sys + +``` +cargo build +``` + +This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. From ffc506da1667834f7e0d9f9846ae15de83c1c63f Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 6 Nov 2024 23:27:41 +0000 Subject: [PATCH 3/9] use lowercase for accuracy --- bindings/rust/README.md | 2 +- bindings/rust/s2n-tls-sys/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index 0f175f6a6ef..c43357b240e 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -30,7 +30,7 @@ cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off cmake --build build -- -j $(nproc) ``` -2. CD into your rust project and set environment variables to libs2n library sources. +2. cd into your rust project and set environment variables to libs2n library sources. This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys ``` diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index 111296bef67..c2384a2d08e 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -12,7 +12,7 @@ cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off cmake --build build -- -j $(nproc) ``` -2. CD into your rust project and set environment variables to libs2n library sources. +2. cd into your rust project and set environment variables to libs2n library sources. This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys ``` From 0ac27e01ac5f86df18c50ebcb32731b6cdb4892e Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Thu, 7 Nov 2024 23:52:07 +0000 Subject: [PATCH 4/9] address PR feedback - add new header - raw definitions for export vars - mention default built steps --- bindings/rust/README.md | 21 +++++++++++++++++---- bindings/rust/s2n-tls-sys/README.md | 21 +++++++++++++++++---- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index c43357b240e..4327a444ef4 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,17 +20,26 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` -Our Rust bindings support using pre-built libs2n by using the [s2n-tls-sys crate](https://crates.io/crates/s2n-tls-sys) and following the next steps below: +## Bring Your Own libs2n with `s2n-tls-sys` crate -1. Compile your preferred configuration of s2n-tls. +The `s2n-tls-sys` crate contains the raw C code of `s2n-tls`. By default, it follows this build process: -You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto) +1. Uses the system C compiler to build `libs2n.a` +2. Links the built `libs2n.a` to the Rust bindings +3. Links against `aws-lc` through the `aws-lc-rs` crate + +However, you can customize this process to use your own pre-built libs2n library using [s2n-tls-sys crate](https://crates.io/crates/s2n-tls-sys). Here's how you can do that: + +1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. + +You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). +Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. ``` cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off cmake --build build -- -j $(nproc) ``` -2. cd into your rust project and set environment variables to libs2n library sources. +2. `cd` into your rust project and set environment variables to your libs2n library sources. This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys ``` @@ -39,6 +48,10 @@ export S2N_TLS_INCLUDE_DIR=/api export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH ``` +`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. +`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`lins2n.so` artifact. +`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`lins2n.so` artifact for dynamic linker's search path. + 3. Build your project. This triggers the build script for s2n-tls-sys ``` diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index c2384a2d08e..f2d35f71c48 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -2,17 +2,26 @@ This crates provides low level rust bindings for [s2n-tls](https://github.com/aw This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. -This crate supports using pre-built libs2n following the next steps below: +# Bring Your Own libs2n -1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. +The `s2n-tls-sys` crate contains the raw C code of `s2n-tls`. By default, it follows this build process: -You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto) +1. Uses the system C compiler to build `libs2n.a` +2. Links the built `libs2n.a` to the Rust bindings +3. Links against `aws-lc` through the `aws-lc-rs` crate + +However, you can customize this process to use your own pre-built libs2n library. Here's how you can do that: + +1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. + +You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). +Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. ``` cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off cmake --build build -- -j $(nproc) ``` -2. cd into your rust project and set environment variables to libs2n library sources. +2. `cd` into your rust project and set environment variables to your libs2n library sources. This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys ``` @@ -21,6 +30,10 @@ export S2N_TLS_INCLUDE_DIR=/api export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH ``` +`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. +`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`lins2n.so` artifact. +`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`lins2n.so` artifact for dynamic linker's search path. + 3. Build your project. This triggers the build script for s2n-tls-sys ``` From 206b570f6d944099f4faabac01a28f73033f33d6 Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Mon, 11 Nov 2024 20:44:04 +0000 Subject: [PATCH 5/9] address PR feedbacks - typo fix - move build process info up a section --- bindings/rust/README.md | 6 +++--- bindings/rust/s2n-tls-sys/README.md | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index 4327a444ef4..a7c5f23a164 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -48,9 +48,9 @@ export S2N_TLS_INCLUDE_DIR=/api export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH ``` -`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. -`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`lins2n.so` artifact. -`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`lins2n.so` artifact for dynamic linker's search path. +`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. +`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`libs2n.so` artifact. +`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`libs2n.so` artifact for dynamic linker's search path. 3. Build your project. This triggers the build script for s2n-tls-sys diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index f2d35f71c48..22724ba89c0 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -2,15 +2,15 @@ This crates provides low level rust bindings for [s2n-tls](https://github.com/aw This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. -# Bring Your Own libs2n - The `s2n-tls-sys` crate contains the raw C code of `s2n-tls`. By default, it follows this build process: 1. Uses the system C compiler to build `libs2n.a` 2. Links the built `libs2n.a` to the Rust bindings 3. Links against `aws-lc` through the `aws-lc-rs` crate -However, you can customize this process to use your own pre-built libs2n library. Here's how you can do that: +# Bring Your Own libs2n + +You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: 1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. @@ -30,9 +30,9 @@ export S2N_TLS_INCLUDE_DIR=/api export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH ``` -`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. -`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`lins2n.so` artifact. -`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`lins2n.so` artifact for dynamic linker's search path. +`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. +`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`libs2n.so` artifact. +`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`libs2n.so` artifact for dynamic linker's search path. 3. Build your project. This triggers the build script for s2n-tls-sys From ef35761b87d5088279469bc058cf7eb6f9979f70 Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Mon, 18 Nov 2024 18:27:09 +0000 Subject: [PATCH 6/9] address PR feedbacks - use more imprerative tone - link sys crate binding to the main bindings readme --- bindings/rust/README.md | 10 ++++---- bindings/rust/s2n-tls-sys/README.md | 40 +---------------------------- 2 files changed, 6 insertions(+), 44 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index a7c5f23a164..d6acd46a536 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,15 +20,15 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` -## Bring Your Own libs2n with `s2n-tls-sys` crate - -The `s2n-tls-sys` crate contains the raw C code of `s2n-tls`. By default, it follows this build process: +The `s2n-tls-sys` bindings crate contains the raw C code of `s2n-tls`. By default, it follows this build process: -1. Uses the system C compiler to build `libs2n.a` +1. Links the system C compiler to build `libs2n.a` 2. Links the built `libs2n.a` to the Rust bindings 3. Links against `aws-lc` through the `aws-lc-rs` crate -However, you can customize this process to use your own pre-built libs2n library using [s2n-tls-sys crate](https://crates.io/crates/s2n-tls-sys). Here's how you can do that: +## Bring Your Own libs2n with `s2n-tls-sys` crate + +You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: 1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index 22724ba89c0..c37d23d5ff4 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -2,42 +2,4 @@ This crates provides low level rust bindings for [s2n-tls](https://github.com/aw This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. -The `s2n-tls-sys` crate contains the raw C code of `s2n-tls`. By default, it follows this build process: - -1. Uses the system C compiler to build `libs2n.a` -2. Links the built `libs2n.a` to the Rust bindings -3. Links against `aws-lc` through the `aws-lc-rs` crate - -# Bring Your Own libs2n - -You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: - -1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. - -You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). -Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. -``` -cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off -cmake --build build -- -j $(nproc) -``` - -2. `cd` into your rust project and set environment variables to your libs2n library sources. - -This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys -``` -export S2N_TLS_LIB_DIR=/build/lib -export S2N_TLS_INCLUDE_DIR=/api -export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH -``` - -`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. -`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`libs2n.so` artifact. -`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`libs2n.so` artifact for dynamic linker's search path. - -3. Build your project. This triggers the build script for s2n-tls-sys - -``` -cargo build -``` - -This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. +For more information on s2n-tls Rust bindings and s2n-tls-sys crate, see [s2n-tls Rust Bindings](https://github.com/aws/s2n-tls/blob/main/bindings/rust/README.md) From 40f01e8971698921bbecc466a044e921ccaf7108 Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 20 Nov 2024 18:34:54 +0000 Subject: [PATCH 7/9] swap readmes --- bindings/rust/README.md | 41 ++--------------------------- bindings/rust/s2n-tls-sys/README.md | 40 +++++++++++++++++++++++++++- 2 files changed, 41 insertions(+), 40 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index d6acd46a536..71300c43489 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,45 +20,8 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` -The `s2n-tls-sys` bindings crate contains the raw C code of `s2n-tls`. By default, it follows this build process: - -1. Links the system C compiler to build `libs2n.a` -2. Links the built `libs2n.a` to the Rust bindings -3. Links against `aws-lc` through the `aws-lc-rs` crate - -## Bring Your Own libs2n with `s2n-tls-sys` crate - -You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: - -1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. - -You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). -Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. -``` -cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off -cmake --build build -- -j $(nproc) -``` - -2. `cd` into your rust project and set environment variables to your libs2n library sources. - -This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys -``` -export S2N_TLS_LIB_DIR=/build/lib -export S2N_TLS_INCLUDE_DIR=/api -export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH -``` - -`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. -`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`libs2n.so` artifact. -`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`libs2n.so` artifact for dynamic linker's search path. - -3. Build your project. This triggers the build script for s2n-tls-sys - -``` -cargo build -``` - -This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. +This script generates the low-level bindings crate `s2n-tls-sys`, which other bindings crates depend on. +See [s2n-tls Rust Bindings](https://github.com/aws/s2n-tls/blob/main/bindings/rust/s2n-tls-sys/README.md) for more information on `s2n-tls-sys` crate. ## Minimum Supported Rust Version (MSRV) diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index c37d23d5ff4..4796f365a04 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -2,4 +2,42 @@ This crates provides low level rust bindings for [s2n-tls](https://github.com/aw This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. -For more information on s2n-tls Rust bindings and s2n-tls-sys crate, see [s2n-tls Rust Bindings](https://github.com/aws/s2n-tls/blob/main/bindings/rust/README.md) +The `s2n-tls-sys` bindings crate contains the raw C code of `s2n-tls`. By default, it follows this build process: + +1. Links the system C compiler to build `libs2n.a` +2. Links the built `libs2n.a` to the Rust bindings +3. Links against `aws-lc` through the `aws-lc-rs` crate + +## Bring Your Own libs2n with `s2n-tls-sys` crate + +You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: + +1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. + +You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). +Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. +``` +cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off +cmake --build build -- -j $(nproc) +``` + +2. `cd` into your rust project and set environment variables to your libs2n library sources. + +This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys +``` +export S2N_TLS_LIB_DIR=/build/lib +export S2N_TLS_INCLUDE_DIR=/api +export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH +``` + +`S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. +`S2N_TLS_INCLUDE_DIR` points to the folder containing header files for `libs2n.a`/`libs2n.so` artifact. +`LD_LIBRARY_PATH` adds the path to `libs2n.a`/`libs2n.so` artifact for dynamic linker's search path. + +3. Build your project. This triggers the build script for s2n-tls-sys + +``` +cargo build +``` + +This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. From 0630834cea5acd02e29a1f6b416f99acda24a26b Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 20 Nov 2024 18:41:34 +0000 Subject: [PATCH 8/9] fix link --- bindings/rust/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index 71300c43489..e6d042c938a 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -21,7 +21,7 @@ $ ./bindings/rust/generate.sh ``` This script generates the low-level bindings crate `s2n-tls-sys`, which other bindings crates depend on. -See [s2n-tls Rust Bindings](https://github.com/aws/s2n-tls/blob/main/bindings/rust/s2n-tls-sys/README.md) for more information on `s2n-tls-sys` crate. +See [s2n-tls-sys](https://github.com/aws/s2n-tls/blob/main/bindings/rust/s2n-tls-sys/README.md) for more information on `s2n-tls-sys` crate. ## Minimum Supported Rust Version (MSRV) From 522fe12f52181bad238ca42822347be99ebb58a5 Mon Sep 17 00:00:00 2001 From: Jou Ho Date: Wed, 20 Nov 2024 22:05:10 +0000 Subject: [PATCH 9/9] address PR feedbacks - fix wrong verb - remove unnecessary intstruction - fix nits --- bindings/rust/README.md | 2 +- bindings/rust/s2n-tls-sys/README.md | 22 ++++++++-------------- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/bindings/rust/README.md b/bindings/rust/README.md index e6d042c938a..37ff3ff51ed 100644 --- a/bindings/rust/README.md +++ b/bindings/rust/README.md @@ -20,7 +20,7 @@ Generating rust bindings can be accomplished by running the `generate.sh` script $ ./bindings/rust/generate.sh ``` -This script generates the low-level bindings crate `s2n-tls-sys`, which other bindings crates depend on. +This script generates the low-level bindings in the crate `s2n-tls-sys`, which is used by the `s2n-tls` crate to provide higher-level bindings. See [s2n-tls-sys](https://github.com/aws/s2n-tls/blob/main/bindings/rust/s2n-tls-sys/README.md) for more information on `s2n-tls-sys` crate. ## Minimum Supported Rust Version (MSRV) diff --git a/bindings/rust/s2n-tls-sys/README.md b/bindings/rust/s2n-tls-sys/README.md index 4796f365a04..aeb3e340b62 100644 --- a/bindings/rust/s2n-tls-sys/README.md +++ b/bindings/rust/s2n-tls-sys/README.md @@ -1,27 +1,23 @@ -This crates provides low level rust bindings for [s2n-tls](https://github.com/aws/s2n-tls) which are autogenerated with [bindgen](https://github.com/rust-lang/rust-bindgen) +This crate provides low level rust bindings for [s2n-tls](https://github.com/aws/s2n-tls) which are autogenerated with [bindgen](https://github.com/rust-lang/rust-bindgen) -This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. +This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate. The `s2n-tls-sys` bindings crate contains the raw C code of `s2n-tls`. By default, it follows this build process: -1. Links the system C compiler to build `libs2n.a` -2. Links the built `libs2n.a` to the Rust bindings -3. Links against `aws-lc` through the `aws-lc-rs` crate +1. Use the system C compiler to build `libs2n.a` +2. Link the built `libs2n.a` to the Rust bindings +3. Link against `aws-lc` through the `aws-lc-rs` crate -## Bring Your Own libs2n with `s2n-tls-sys` crate +## Bring your own libs2n with `s2n-tls-sys` crate -You can customize above build process to use your own pre-built libs2n library. Here's how you can do that: +You can customize above build process to use your own pre-built libs2n. This is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`. Here's how you can do that: 1. Clone [s2n-tls](https://github.com/aws/s2n-tls) and compile your preferred configuration of s2n-tls. You may choose to link against a specific libcrypto at this step. For more information, see [Building with a specific libcrypto](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto). Also see [Building s2n-tls](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls) for further guidance on configuring s2n-tls for your own use case. -``` -cmake . -Bbuild -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off -cmake --build build -- -j $(nproc) -``` -2. `cd` into your rust project and set environment variables to your libs2n library sources. +2. `cd` into your rust project and set environment variables to your libs2n artifacts. This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys ``` @@ -39,5 +35,3 @@ export LD_LIBRARY_PATH=$S2N_TLS_LIB_DIR:$LD_LIBRARY_PATH ``` cargo build ``` - -This method is useful if you want the bindings to be built with a non-default libcrypto. Currently, the default libcrypto when generating rust bindings is `aws-lc`.