From 38c5f0ed8fac1352b062b1a66ca5f3f59f463ad4 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 14:57:19 -0400 Subject: [PATCH 01/10] docs: typo fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ef06fbc3..9a816ab7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ It also contains demo C programs that use those bindings to run an HTTPS server, make an HTTPS request. Rustls is a modern TLS library written in Rust, meaning it is less likely to -have memory safety vulnerabilities that equivalent TLS libraries written in +have memory safety vulnerabilities than equivalent TLS libraries written in memory unsafe languages. If you are using rustls-ffi to replace OpenSSL, note that OpenSSL provides From 971b6fcb7408f70b1b1054087e8f6f23e17fe5c7 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 14:57:45 -0400 Subject: [PATCH 02/10] docs: fix duplicated text --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a816ab7..38a8067c 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ memory unsafe languages. If you are using rustls-ffi to replace OpenSSL, note that OpenSSL provides [cryptographic primitives](https://www.openssl.org/docs/man3.0/man7/crypto.html) in addition to a TLS library. Rustls-ffi only provides the TLS library. If you -use the cryptographic primitives from OpenSSL you may need to -need to find another library to provide the cryptographic primitives. +use the cryptographic primitives from OpenSSL you may need to find another library +to provide the cryptographic primitives. # Build From c2637764ccbe0ed0f99545c9c07497ac2718041c Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 14:58:10 -0400 Subject: [PATCH 03/10] docs: fix advertised MSRV --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 38a8067c..f0bbf5d6 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ to provide the cryptographic primitives. # Build -You'll need to [install the Rust toolchain](https://rustup.rs/) version 1.60 -or above and a C compiler (gcc and clang should both work). To build in optimized mode: +You'll need to [install the Rust toolchain](https://rustup.rs/) (version 1.61 +or above) and a C compiler (gcc and clang should both work). To build in optimized mode: make From 0110a1762eebe8e9216a1748c184a3dbdd045766 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 14:58:57 -0400 Subject: [PATCH 04/10] docs: use more backticks --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f0bbf5d6..011c3e92 100644 --- a/README.md +++ b/README.md @@ -20,11 +20,11 @@ to provide the cryptographic primitives. # Build You'll need to [install the Rust toolchain](https://rustup.rs/) (version 1.61 -or above) and a C compiler (gcc and clang should both work). To build in optimized mode: +or above) and a C compiler (`gcc` and `clang` should both work). To build in optimized mode: make -To install in /usr/local/: +To install in `/usr/local/`: sudo make install @@ -56,8 +56,8 @@ supports. # Conventions -This library defines an enum, rustls_result, to indicate success or failure of -a function call. All fallible functions return a rustls_result. If a function +This library defines an `enum`, `rustls_result`, to indicate success or failure of +a function call. All fallible functions return a `rustls_result`. If a function has other outputs, it provides them using output parameters (pointers to caller-provided objects). For instance: @@ -94,7 +94,7 @@ mutating. ## Input and Output Parameters Input parameters will always be either a const pointer or a primitive type -(int, size_t, etc). Output parameters will always be a non-const pointer. +(`int`, `size_t`, etc). Output parameters will always be a non-const pointer. The caller is responsible for ensuring that the memory pointed to be output parameters is not being concurrently accessed by other threads. For primitive @@ -116,7 +116,7 @@ operated on. Next will come some number of input parameters, then some number of output parameters. As a minor exception to the above: When an output parameter is a byte buffer -(*uint8_t), the next parameter will always be a size_t denoting the size of +(`*uint8_t`), the next parameter will always be a `size_t` denoting the size of the buffer. This is considered part of the output parameters even though it is not directly modified. @@ -133,31 +133,31 @@ pointed to by output arguments. Rustls supports various types of user customization via callbacks. All callbacks take a `void *userdata` parameter as their first parameter. Unless otherwise specified, this will receive a value that was associated with a -rustls_connection via `rustls_connection_set_userdata`. If no such value was -set, they will receive NULL. The read and write callbacks are a particular +`rustls_connection` via `rustls_connection_set_userdata`. If no such value was +set, they will receive `NULL`. The read and write callbacks are a particular exception to this rule - they receive a userdata value passed through from the -current call to rustls_connection_{read,write}_tls. +current call to `rustls_connection_{read,write}_tls`. ## NULL -The library checks all pointers in arguments for NULL and will return an error -rather than dereferencing a NULL pointer. For some methods that are infallible -except for the possibility of NULL (for instance +The library checks all pointers in arguments for `NULL` and will return an error +rather than dereferencing a `NULL` pointer. For some methods that are infallible +except for the possibility of `NULL` (for instance `rustls_connection_is_handshaking`), the library returns a convenient -type (e.g. `bool`) and uses a suitable fallback value if an input is NULL. +type (e.g. `bool`) and uses a suitable fallback value if an input is `NULL`. ## Panics In case of a bug (e.g. exceeding the bounds of an array), Rust code may emit a panic. Panics are treated like exceptions in C++, unwinding the stack. Unwinding past the FFI boundary is undefined behavior, so this library catches -all unwinds and turns them into RUSTLS_RESULT_PANIC (when the function is +all unwinds and turns them into `RUSTLS_RESULT_PANIC` (when the function is fallible). -Functions that are theoretically infallible don't return rustls_result, so we -can't return RUSTLS_RESULT_PANIC. In those cases, if there's a panic, we'll -return a default value suitable to the return type: NULL for pointer types, -false for bool types, and 0 for integer types. +Functions that are theoretically infallible don't return `rustls_result`, so we +can't return `RUSTLS_RESULT_PANIC`. In those cases, if there's a panic, we'll +return a default value suitable to the return type: `NULL` for pointer types, +`false` for bool types, and `0` for integer types. # Experimentals From 50cb6d036a1d1046251049898927b6239758fe45 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:03:31 -0400 Subject: [PATCH 05/10] docs: typo fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 011c3e92..2ac3dc40 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ mutating. Input parameters will always be either a const pointer or a primitive type (`int`, `size_t`, etc). Output parameters will always be a non-const pointer. -The caller is responsible for ensuring that the memory pointed to be output +The caller is responsible for ensuring that the memory pointed to by output parameters is not being concurrently accessed by other threads. For primitive types and pointers-to-pointers this is most commonly accomplished by passing the address of a local variable on the stack that has no references elsewhere. From 3e6c1ab4cd1616327a5024fe708e8ef10ec64c1c Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:04:08 -0400 Subject: [PATCH 06/10] docs: editorial fix for clarity --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2ac3dc40..67ad12e0 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ the caller will need to take additional steps to prevent concurrent access When an output parameter is a pointer to a pointer (e.g. `rustls_connection **conn_out`, the function will set its argument to point to an appropriate object on success. The caller is considered to take -ownership of that object and be responsible for the requirements above: +ownership of that object and must be responsible for the requirements above: preventing concurrent mutation, and freeing it exactly once. For a method, the first parameter will always be a pointer to the struct being From 94c971c4523758cf94ba23dcf3093f941be35255 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:09:44 -0400 Subject: [PATCH 07/10] docs: typo fix for mod_tls description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 67ad12e0..c04ce6f3 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ need further evaluation and will most likely change significantly in the future. The `rustls_server_config_builder_set_hello_callback` and its provided information in `rustls_client_hello` will change. The current design is a snapshot of the implementation efforts in [mod_tls](https://github.com/icing/mod_tls) to provide -`rustls` base TLS as module for the Apache webserver. +`rustls`-based TLS as module for the Apache webserver. For a webserver hosting multiple domains on the same endpoint, it is highly desirable to have individual TLS settings, depending on the domain the client wants to talk to. From 42ebd4a40592078166ef0a703aa8f1ddb15d9864 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:10:57 -0400 Subject: [PATCH 08/10] docs: typo fix for multi-setting callback --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c04ce6f3..1d5a7cad 100644 --- a/README.md +++ b/README.md @@ -198,7 +198,7 @@ create the one with the correct setting for the domain chosen. For this to work, your connection needs to buffer the initial data from the client, so these bytes can be replayed to the second connection you use. Do not -write any data back to the client while your are in the initial connection. The +write any data back to the client while you are in the initial connection. The client hellos are usually only a few hundred bytes. #### Verifying TLS certificates From 4bf1e0f0ab0fff18a8bd06921e7a559e9442606e Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:12:13 -0400 Subject: [PATCH 09/10] docs: clarify trust anchor notes in verifying section --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1d5a7cad..d631696b 100644 --- a/README.md +++ b/README.md @@ -203,9 +203,10 @@ client hellos are usually only a few hundred bytes. #### Verifying TLS certificates -By default, rustls does not load any TLS certificates, not even the system -store, which means that TLS certificate verification will fail by default. You -are responsible for loading certificates using one of the following methods: +By default, rustls does not load any trust anchors (root certificates), not even +the system trust anchor store, which means that TLS certificate verification will +fail by default. You are responsible for loading certificates using one of the +following methods: - `rustls_root_cert_store_add_pem`, which adds a single certificate to a root store From f197fc54b238ef1989f3b443ebfdaeaa3d08ca6e Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Mon, 16 Oct 2023 15:13:02 -0400 Subject: [PATCH 10/10] docs: missing period --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d631696b..a7c8527e 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ fail by default. You are responsible for loading certificates using one of the following methods: - `rustls_root_cert_store_add_pem`, which adds a single certificate to a root - store + store. - `rustls_client_config_builder_load_roots_from_file`, which loads certificates from a file.