Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: document generating bindings with prebuilt libs2n #4872

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

doc: document generating bindings with prebuilt libs2n #4872

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dbbb9af
document generating bindings with prebuilt libs2n
jouho Nov 6, 2024
419b833
Merge branch 'main' into document-rust-bindings-with-prebuilt-libs2n
jouho Nov 6, 2024
2ccf18e
address PR feedback
jouho Nov 6, 2024
ffc506d
use lowercase for accuracy
jouho Nov 6, 2024
0ac27e0
address PR feedback
jouho Nov 7, 2024
206b570
address PR feedbacks
jouho Nov 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions bindings/rust/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,46 @@ 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:

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 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=<PATH_TO_ROOT_OF_S2N_TLS>/build/lib
export S2N_TLS_INCLUDE_DIR=<PATH_TO_ROOT_OF_S2N_TLS>/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`.

## 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.
Expand Down
42 changes: 41 additions & 1 deletion bindings/rust/s2n-tls-sys/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,43 @@
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.
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.
jmayclin marked this conversation as resolved.
Show resolved Hide resolved

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
Comment on lines +5 to +9
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I'd move this above the bring your own libs2n heading, because it it generally useful information.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's include the raw definitions, because I think your example includes some assumptions which might not actually match customer environments.

E.g. call out that S2N_TLS_LIB_DIR points to the folder containing the libs2n.a artifact that you would like s2n-tls-sys to link against.

Also, maybe let's call out whether something is different with static vs dynamic libs?

Copy link
Contributor Author

@jouho jouho Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added explanation on what each vars are for.

maybe let's call out whether something is different with static vs dynamic libs?

I understand static lib bakes the code to executable at build time and dynamic lib requires the linked libraries to be available at runtime. Is there something else we want to call out within the context of this bindings generation?

This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys
```
export S2N_TLS_LIB_DIR=<PATH_TO_ROOT_OF_S2N_TLS>/build/lib
export S2N_TLS_INCLUDE_DIR=<PATH_TO_ROOT_OF_S2N_TLS>/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.

jmayclin marked this conversation as resolved.
Show resolved Hide resolved
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`.
Loading