From 86fb37df00ebc8edab13847991389138d21c2b6d Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Fri, 1 Nov 2024 21:30:17 +0000 Subject: [PATCH 1/7] doc: add information about s2n-tls software architecture * add software architecture md file * insert the file before connection doc --- docs/usage-guide/topics/SUMMARY.md | 25 ++++++++++--------- .../topics/ch04-software-architecture.md | 21 ++++++++++++++++ ...{ch04-connection.md => ch05-connection.md} | 0 .../topics/{ch05-config.md => ch06-config.md} | 0 ...-policies.md => ch07-security-policies.md} | 0 .../topics/{ch07-io.md => ch08-io.md} | 0 ...8-record-sizes.md => ch09-record-sizes.md} | 0 ...9-certificates.md => ch10-certificates.md} | 0 ...0-client-hello.md => ch11-client-hello.md} | 0 ...{ch11-resumption.md => ch12-resumption.md} | 0 ...ate-key-ops.md => ch13-private-key-ops.md} | 0 ...eshared-keys.md => ch14-preshared-keys.md} | 0 ...{ch14-early-data.md => ch15-early-data.md} | 0 ...5-post-quantum.md => ch16-post-quantum.md} | 0 14 files changed, 34 insertions(+), 12 deletions(-) create mode 100644 docs/usage-guide/topics/ch04-software-architecture.md rename docs/usage-guide/topics/{ch04-connection.md => ch05-connection.md} (100%) rename docs/usage-guide/topics/{ch05-config.md => ch06-config.md} (100%) rename docs/usage-guide/topics/{ch06-security-policies.md => ch07-security-policies.md} (100%) rename docs/usage-guide/topics/{ch07-io.md => ch08-io.md} (100%) rename docs/usage-guide/topics/{ch08-record-sizes.md => ch09-record-sizes.md} (100%) rename docs/usage-guide/topics/{ch09-certificates.md => ch10-certificates.md} (100%) rename docs/usage-guide/topics/{ch10-client-hello.md => ch11-client-hello.md} (100%) rename docs/usage-guide/topics/{ch11-resumption.md => ch12-resumption.md} (100%) rename docs/usage-guide/topics/{ch12-private-key-ops.md => ch13-private-key-ops.md} (100%) rename docs/usage-guide/topics/{ch13-preshared-keys.md => ch14-preshared-keys.md} (100%) rename docs/usage-guide/topics/{ch14-early-data.md => ch15-early-data.md} (100%) rename docs/usage-guide/topics/{ch15-post-quantum.md => ch16-post-quantum.md} (100%) diff --git a/docs/usage-guide/topics/SUMMARY.md b/docs/usage-guide/topics/SUMMARY.md index 308864e4cec..1631ef44b2e 100644 --- a/docs/usage-guide/topics/SUMMARY.md +++ b/docs/usage-guide/topics/SUMMARY.md @@ -4,15 +4,16 @@ - [s2n-tls API](./ch01-api.md) - [Initialization and Teardown](./ch02-initialization.md) - [Error Handling](./ch03-error-handling.md) -- [TLS Connections](./ch04-connection.md) -- [Configuring the Connection](./ch05-config.md) -- [Security Policies](./ch06-security-policies.md) -- [IO](./ch07-io.md) -- [TLS Record Sizes](./ch08-record-sizes.md) -- [Certificates and Authentication](./ch09-certificates.md) -- [Examining the Client Hello](./ch10-client-hello.md) -- [Session Resumption](./ch11-resumption.md) -- [Offloading Private Key Operations](./ch12-private-key-ops.md) -- [Pre-shared Keys](./ch13-preshared-keys.md) -- [Early Data](./ch14-early-data.md) -- [Post Quantum Support](./ch15-post-quantum.md) +- [Software Architecture](./ch04-software-architecture.md) +- [TLS Connections](./ch05-connection.md) +- [Configuring the Connection](./ch06-config.md) +- [Security Policies](./ch07-security-policies.md) +- [IO](./ch08-io.md) +- [TLS Record Sizes](./ch09-record-sizes.md) +- [Certificates and Authentication](./ch10-certificates.md) +- [Examining the Client Hello](./ch11-client-hello.md) +- [Session Resumption](./ch12-resumption.md) +- [Offloading Private Key Operations](./ch13-private-key-ops.md) +- [Pre-shared Keys](./ch14-preshared-keys.md) +- [Early Data](./ch15-early-data.md) +- [Post Quantum Support](./ch16-post-quantum.md) diff --git a/docs/usage-guide/topics/ch04-software-architecture.md b/docs/usage-guide/topics/ch04-software-architecture.md new file mode 100644 index 00000000000..8b66374f216 --- /dev/null +++ b/docs/usage-guide/topics/ch04-software-architecture.md @@ -0,0 +1,21 @@ +# Software Architecture + +User interaction with s2n-tls happens primarily through the `s2n_connection` and `s2n_config` structures. + +## Primary Structures + +Users start by building a config. In the general case, there will be one config per server. This involves loading the certificate, configuring session resumption, etc. Users should configure an `s2n_config` before associating any `s2n_connection` objects with it. + +Users must then configure a connection, and associate it with a config. `s2n_connection` is responsible for managing the actual state of a TLS connection. In a TLS server, there will be one `s2n_connection` for each TCP stream. For each `s2n_config`, there may be many `s2n_connection` structs associated with it. + +## Mutability + +`s2n_config` MUST NOT be mutated after it is associated with a connection, with the exception of `s2n_config_add_ticket_crypto_key`. + +## Thread Safety + +In general, s2n-tls APIs are not thread safe unless explicitly specified otherwise. Neither `s2n_config` nor `s2n_connection` can be configured from multiple threads. + +After being configured, `s2n_config`s MUST be treated as immutable, and therefore can be safely referenced from multiple threads. It is safe for multiple `s2n_connections` on different threads to share the same s2n_config. + +`s2n_connection`s are not immutable, and it is generally unsafe to mutate them from multiple threads. One exception is that `s2n_send` and `s2n_recv` can be called simultaneously from different threads. However it is not valid to call `s2n_send` or `s2n_recv` from multiple threads. E.g. It is invalid for two threads to simultaneously call `s2n_send`. diff --git a/docs/usage-guide/topics/ch04-connection.md b/docs/usage-guide/topics/ch05-connection.md similarity index 100% rename from docs/usage-guide/topics/ch04-connection.md rename to docs/usage-guide/topics/ch05-connection.md diff --git a/docs/usage-guide/topics/ch05-config.md b/docs/usage-guide/topics/ch06-config.md similarity index 100% rename from docs/usage-guide/topics/ch05-config.md rename to docs/usage-guide/topics/ch06-config.md diff --git a/docs/usage-guide/topics/ch06-security-policies.md b/docs/usage-guide/topics/ch07-security-policies.md similarity index 100% rename from docs/usage-guide/topics/ch06-security-policies.md rename to docs/usage-guide/topics/ch07-security-policies.md diff --git a/docs/usage-guide/topics/ch07-io.md b/docs/usage-guide/topics/ch08-io.md similarity index 100% rename from docs/usage-guide/topics/ch07-io.md rename to docs/usage-guide/topics/ch08-io.md diff --git a/docs/usage-guide/topics/ch08-record-sizes.md b/docs/usage-guide/topics/ch09-record-sizes.md similarity index 100% rename from docs/usage-guide/topics/ch08-record-sizes.md rename to docs/usage-guide/topics/ch09-record-sizes.md diff --git a/docs/usage-guide/topics/ch09-certificates.md b/docs/usage-guide/topics/ch10-certificates.md similarity index 100% rename from docs/usage-guide/topics/ch09-certificates.md rename to docs/usage-guide/topics/ch10-certificates.md diff --git a/docs/usage-guide/topics/ch10-client-hello.md b/docs/usage-guide/topics/ch11-client-hello.md similarity index 100% rename from docs/usage-guide/topics/ch10-client-hello.md rename to docs/usage-guide/topics/ch11-client-hello.md diff --git a/docs/usage-guide/topics/ch11-resumption.md b/docs/usage-guide/topics/ch12-resumption.md similarity index 100% rename from docs/usage-guide/topics/ch11-resumption.md rename to docs/usage-guide/topics/ch12-resumption.md diff --git a/docs/usage-guide/topics/ch12-private-key-ops.md b/docs/usage-guide/topics/ch13-private-key-ops.md similarity index 100% rename from docs/usage-guide/topics/ch12-private-key-ops.md rename to docs/usage-guide/topics/ch13-private-key-ops.md diff --git a/docs/usage-guide/topics/ch13-preshared-keys.md b/docs/usage-guide/topics/ch14-preshared-keys.md similarity index 100% rename from docs/usage-guide/topics/ch13-preshared-keys.md rename to docs/usage-guide/topics/ch14-preshared-keys.md diff --git a/docs/usage-guide/topics/ch14-early-data.md b/docs/usage-guide/topics/ch15-early-data.md similarity index 100% rename from docs/usage-guide/topics/ch14-early-data.md rename to docs/usage-guide/topics/ch15-early-data.md diff --git a/docs/usage-guide/topics/ch15-post-quantum.md b/docs/usage-guide/topics/ch16-post-quantum.md similarity index 100% rename from docs/usage-guide/topics/ch15-post-quantum.md rename to docs/usage-guide/topics/ch16-post-quantum.md From 55a0ff890cca51421b0ab66aaf5c3d710e0c049c Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Tue, 5 Nov 2024 20:40:33 +0000 Subject: [PATCH 2/7] address PR comments: * move those general docs to config and connection chapters * move config chapter in front of the connection chapter --- docs/usage-guide/topics/SUMMARY.md | 23 +++++++++---------- docs/usage-guide/topics/ch01-api.md | 2 ++ .../topics/{ch06-config.md => ch04-config.md} | 2 ++ .../topics/ch04-software-architecture.md | 21 ----------------- docs/usage-guide/topics/ch05-connection.md | 2 ++ ...-policies.md => ch06-security-policies.md} | 0 .../topics/{ch08-io.md => ch07-io.md} | 0 ...9-record-sizes.md => ch08-record-sizes.md} | 0 ...0-certificates.md => ch09-certificates.md} | 0 ...1-client-hello.md => ch10-client-hello.md} | 0 ...{ch12-resumption.md => ch11-resumption.md} | 2 +- ...ate-key-ops.md => ch12-private-key-ops.md} | 0 ...eshared-keys.md => ch13-preshared-keys.md} | 0 ...{ch15-early-data.md => ch14-early-data.md} | 0 ...6-post-quantum.md => ch15-post-quantum.md} | 0 15 files changed, 18 insertions(+), 34 deletions(-) rename docs/usage-guide/topics/{ch06-config.md => ch04-config.md} (86%) delete mode 100644 docs/usage-guide/topics/ch04-software-architecture.md rename docs/usage-guide/topics/{ch07-security-policies.md => ch06-security-policies.md} (100%) rename docs/usage-guide/topics/{ch08-io.md => ch07-io.md} (100%) rename docs/usage-guide/topics/{ch09-record-sizes.md => ch08-record-sizes.md} (100%) rename docs/usage-guide/topics/{ch10-certificates.md => ch09-certificates.md} (100%) rename docs/usage-guide/topics/{ch11-client-hello.md => ch10-client-hello.md} (100%) rename docs/usage-guide/topics/{ch12-resumption.md => ch11-resumption.md} (97%) rename docs/usage-guide/topics/{ch13-private-key-ops.md => ch12-private-key-ops.md} (100%) rename docs/usage-guide/topics/{ch14-preshared-keys.md => ch13-preshared-keys.md} (100%) rename docs/usage-guide/topics/{ch15-early-data.md => ch14-early-data.md} (100%) rename docs/usage-guide/topics/{ch16-post-quantum.md => ch15-post-quantum.md} (100%) diff --git a/docs/usage-guide/topics/SUMMARY.md b/docs/usage-guide/topics/SUMMARY.md index 1631ef44b2e..b4d00db474f 100644 --- a/docs/usage-guide/topics/SUMMARY.md +++ b/docs/usage-guide/topics/SUMMARY.md @@ -4,16 +4,15 @@ - [s2n-tls API](./ch01-api.md) - [Initialization and Teardown](./ch02-initialization.md) - [Error Handling](./ch03-error-handling.md) -- [Software Architecture](./ch04-software-architecture.md) +- [Configuring the Connection](./ch04-config.md) - [TLS Connections](./ch05-connection.md) -- [Configuring the Connection](./ch06-config.md) -- [Security Policies](./ch07-security-policies.md) -- [IO](./ch08-io.md) -- [TLS Record Sizes](./ch09-record-sizes.md) -- [Certificates and Authentication](./ch10-certificates.md) -- [Examining the Client Hello](./ch11-client-hello.md) -- [Session Resumption](./ch12-resumption.md) -- [Offloading Private Key Operations](./ch13-private-key-ops.md) -- [Pre-shared Keys](./ch14-preshared-keys.md) -- [Early Data](./ch15-early-data.md) -- [Post Quantum Support](./ch16-post-quantum.md) +- [Security Policies](./ch06-security-policies.md) +- [IO](./ch07-io.md) +- [TLS Record Sizes](./ch08-record-sizes.md) +- [Certificates and Authentication](./ch09-certificates.md) +- [Examining the Client Hello](./ch10-client-hello.md) +- [Session Resumption](./ch11-resumption.md) +- [Offloading Private Key Operations](./ch12-private-key-ops.md) +- [Pre-shared Keys](./ch13-preshared-keys.md) +- [Early Data](./ch14-early-data.md) +- [Post Quantum Support](./ch15-post-quantum.md) diff --git a/docs/usage-guide/topics/ch01-api.md b/docs/usage-guide/topics/ch01-api.md index 3f5bd55b9c8..0635a03595a 100644 --- a/docs/usage-guide/topics/ch01-api.md +++ b/docs/usage-guide/topics/ch01-api.md @@ -6,6 +6,8 @@ are intended to be stable (API and ABI) within major version numbers of s2n-tls and structures used in s2n-tls internally can not be considered stable and their parameters, names, and sizes may change. +In general, s2n-tls APIs are not thread safe unless explicitly specified otherwise. + Read [Error Handling](./ch03-error-handling.md) for information on processing API return values safely. The [VERSIONING.rst](https://github.com/aws/s2n-tls/blob/main/VERSIONING.rst) document contains more details about s2n's approach to versions and API changes. diff --git a/docs/usage-guide/topics/ch06-config.md b/docs/usage-guide/topics/ch04-config.md similarity index 86% rename from docs/usage-guide/topics/ch06-config.md rename to docs/usage-guide/topics/ch04-config.md index 6ffaa23c68c..086587df143 100644 --- a/docs/usage-guide/topics/ch06-config.md +++ b/docs/usage-guide/topics/ch04-config.md @@ -1,5 +1,7 @@ # Configuring the Connection +Users start by building a config. In the general case, there will be one config per server. This involves loading the certificate, configuring session resumption, etc. Users should configure an `s2n_config` before associating any `s2n_connection` objects with it. + `s2n_config` objects are used to change the default settings of a s2n-tls connection. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. A config should not be altered once it is associated with a connection as this will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. Calling `s2n_config_new()` can have a performance cost during config creation due to loading diff --git a/docs/usage-guide/topics/ch04-software-architecture.md b/docs/usage-guide/topics/ch04-software-architecture.md deleted file mode 100644 index 8b66374f216..00000000000 --- a/docs/usage-guide/topics/ch04-software-architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Software Architecture - -User interaction with s2n-tls happens primarily through the `s2n_connection` and `s2n_config` structures. - -## Primary Structures - -Users start by building a config. In the general case, there will be one config per server. This involves loading the certificate, configuring session resumption, etc. Users should configure an `s2n_config` before associating any `s2n_connection` objects with it. - -Users must then configure a connection, and associate it with a config. `s2n_connection` is responsible for managing the actual state of a TLS connection. In a TLS server, there will be one `s2n_connection` for each TCP stream. For each `s2n_config`, there may be many `s2n_connection` structs associated with it. - -## Mutability - -`s2n_config` MUST NOT be mutated after it is associated with a connection, with the exception of `s2n_config_add_ticket_crypto_key`. - -## Thread Safety - -In general, s2n-tls APIs are not thread safe unless explicitly specified otherwise. Neither `s2n_config` nor `s2n_connection` can be configured from multiple threads. - -After being configured, `s2n_config`s MUST be treated as immutable, and therefore can be safely referenced from multiple threads. It is safe for multiple `s2n_connections` on different threads to share the same s2n_config. - -`s2n_connection`s are not immutable, and it is generally unsafe to mutate them from multiple threads. One exception is that `s2n_send` and `s2n_recv` can be called simultaneously from different threads. However it is not valid to call `s2n_send` or `s2n_recv` from multiple threads. E.g. It is invalid for two threads to simultaneously call `s2n_send`. diff --git a/docs/usage-guide/topics/ch05-connection.md b/docs/usage-guide/topics/ch05-connection.md index e9896c5a43e..3698d7cf095 100644 --- a/docs/usage-guide/topics/ch05-connection.md +++ b/docs/usage-guide/topics/ch05-connection.md @@ -1,5 +1,7 @@ # TLS Connections +Users must configure a connection, and associate it with a config. `s2n_connection` is responsible for managing the actual state of a TLS connection. In a TLS server, there will be one `s2n_connection` for each TCP stream. For each `s2n_config`, there may be many `s2n_connection` structs associated with it. + Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. ## Connection Memory diff --git a/docs/usage-guide/topics/ch07-security-policies.md b/docs/usage-guide/topics/ch06-security-policies.md similarity index 100% rename from docs/usage-guide/topics/ch07-security-policies.md rename to docs/usage-guide/topics/ch06-security-policies.md diff --git a/docs/usage-guide/topics/ch08-io.md b/docs/usage-guide/topics/ch07-io.md similarity index 100% rename from docs/usage-guide/topics/ch08-io.md rename to docs/usage-guide/topics/ch07-io.md diff --git a/docs/usage-guide/topics/ch09-record-sizes.md b/docs/usage-guide/topics/ch08-record-sizes.md similarity index 100% rename from docs/usage-guide/topics/ch09-record-sizes.md rename to docs/usage-guide/topics/ch08-record-sizes.md diff --git a/docs/usage-guide/topics/ch10-certificates.md b/docs/usage-guide/topics/ch09-certificates.md similarity index 100% rename from docs/usage-guide/topics/ch10-certificates.md rename to docs/usage-guide/topics/ch09-certificates.md diff --git a/docs/usage-guide/topics/ch11-client-hello.md b/docs/usage-guide/topics/ch10-client-hello.md similarity index 100% rename from docs/usage-guide/topics/ch11-client-hello.md rename to docs/usage-guide/topics/ch10-client-hello.md diff --git a/docs/usage-guide/topics/ch12-resumption.md b/docs/usage-guide/topics/ch11-resumption.md similarity index 97% rename from docs/usage-guide/topics/ch12-resumption.md rename to docs/usage-guide/topics/ch11-resumption.md index 756f0823d92..4d60c957021 100644 --- a/docs/usage-guide/topics/ch12-resumption.md +++ b/docs/usage-guide/topics/ch11-resumption.md @@ -3,7 +3,7 @@ TLS handshake sessions are CPU-heavy due to the calculations involved in authent ## Session Ticket Key -The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. +The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. Calling `s2n_config_add_ticket_crypto_key()` is an exception to the general immutability of the `s2n_config` object. Each key has two different expiration dates. The first expiration date signifies the time that the key can be used for both encryption and decryption. The second expiration date signifies the time that the key can be used only for decryption. This mechanism is to ensure that a session ticket can be successfully decrypted if it was encrypted by a key that was about to expire. The full lifetime of the key is therefore the encrypt-decrypt lifetime plus the decrypt-only lifetime. To alter the default key lifetime call `s2n_config_set_ticket_encrypt_decrypt_key_lifetime()` and `s2n_config_set_ticket_decrypt_key_lifetime()`. diff --git a/docs/usage-guide/topics/ch13-private-key-ops.md b/docs/usage-guide/topics/ch12-private-key-ops.md similarity index 100% rename from docs/usage-guide/topics/ch13-private-key-ops.md rename to docs/usage-guide/topics/ch12-private-key-ops.md diff --git a/docs/usage-guide/topics/ch14-preshared-keys.md b/docs/usage-guide/topics/ch13-preshared-keys.md similarity index 100% rename from docs/usage-guide/topics/ch14-preshared-keys.md rename to docs/usage-guide/topics/ch13-preshared-keys.md diff --git a/docs/usage-guide/topics/ch15-early-data.md b/docs/usage-guide/topics/ch14-early-data.md similarity index 100% rename from docs/usage-guide/topics/ch15-early-data.md rename to docs/usage-guide/topics/ch14-early-data.md diff --git a/docs/usage-guide/topics/ch16-post-quantum.md b/docs/usage-guide/topics/ch15-post-quantum.md similarity index 100% rename from docs/usage-guide/topics/ch16-post-quantum.md rename to docs/usage-guide/topics/ch15-post-quantum.md From 5ef6785a3a9a48455ea012605b27d34e1df735bf Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Tue, 5 Nov 2024 22:43:31 +0000 Subject: [PATCH 3/7] address PR comments: * remove some repeating sentences * rephrase some sentences to make them read more precise --- docs/usage-guide/topics/SUMMARY.md | 4 ++-- .../topics/{ch05-connection.md => ch04-connection.md} | 4 +--- docs/usage-guide/topics/{ch04-config.md => ch05-config.md} | 4 +--- 3 files changed, 4 insertions(+), 8 deletions(-) rename docs/usage-guide/topics/{ch05-connection.md => ch04-connection.md} (88%) rename docs/usage-guide/topics/{ch04-config.md => ch05-config.md} (58%) diff --git a/docs/usage-guide/topics/SUMMARY.md b/docs/usage-guide/topics/SUMMARY.md index b4d00db474f..308864e4cec 100644 --- a/docs/usage-guide/topics/SUMMARY.md +++ b/docs/usage-guide/topics/SUMMARY.md @@ -4,8 +4,8 @@ - [s2n-tls API](./ch01-api.md) - [Initialization and Teardown](./ch02-initialization.md) - [Error Handling](./ch03-error-handling.md) -- [Configuring the Connection](./ch04-config.md) -- [TLS Connections](./ch05-connection.md) +- [TLS Connections](./ch04-connection.md) +- [Configuring the Connection](./ch05-config.md) - [Security Policies](./ch06-security-policies.md) - [IO](./ch07-io.md) - [TLS Record Sizes](./ch08-record-sizes.md) diff --git a/docs/usage-guide/topics/ch05-connection.md b/docs/usage-guide/topics/ch04-connection.md similarity index 88% rename from docs/usage-guide/topics/ch05-connection.md rename to docs/usage-guide/topics/ch04-connection.md index 3698d7cf095..0c2e1b6609e 100644 --- a/docs/usage-guide/topics/ch05-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,8 +1,6 @@ # TLS Connections -Users must configure a connection, and associate it with a config. `s2n_connection` is responsible for managing the actual state of a TLS connection. In a TLS server, there will be one `s2n_connection` for each TCP stream. For each `s2n_config`, there may be many `s2n_connection` structs associated with it. - -Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. +Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. In a TLS server, there will be one `s2n_connection` for each TCP stream. ## Connection Memory diff --git a/docs/usage-guide/topics/ch04-config.md b/docs/usage-guide/topics/ch05-config.md similarity index 58% rename from docs/usage-guide/topics/ch04-config.md rename to docs/usage-guide/topics/ch05-config.md index 086587df143..c69f9d6f134 100644 --- a/docs/usage-guide/topics/ch04-config.md +++ b/docs/usage-guide/topics/ch05-config.md @@ -1,8 +1,6 @@ # Configuring the Connection -Users start by building a config. In the general case, there will be one config per server. This involves loading the certificate, configuring session resumption, etc. Users should configure an `s2n_config` before associating any `s2n_connection` objects with it. - -`s2n_config` objects are used to change the default settings of a s2n-tls connection. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. A config should not be altered once it is associated with a connection as this will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. +Users start by building a config. `s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configurations before establishing any connection, and the config should not be altered once it is associated with a connection as this will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. Calling `s2n_config_new()` can have a performance cost during config creation due to loading default system certificates into the trust store (see [Configuring the Trust Store](./ch09-certificates.md#configuring-the-trust-store)). From 0e84ec8523639107194b6fd03f85188be2a8f7d5 Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Wed, 6 Nov 2024 17:52:28 +0000 Subject: [PATCH 4/7] address PR comments: * make doc wording more precise based on comments --- docs/usage-guide/topics/ch04-connection.md | 2 +- docs/usage-guide/topics/ch05-config.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage-guide/topics/ch04-connection.md b/docs/usage-guide/topics/ch04-connection.md index 0c2e1b6609e..48a95f40ea0 100644 --- a/docs/usage-guide/topics/ch04-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,6 +1,6 @@ # TLS Connections -Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. In a TLS server, there will be one `s2n_connection` for each TCP stream. +Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. One `s2n_connection` must be created for each TCP stream. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. ## Connection Memory diff --git a/docs/usage-guide/topics/ch05-config.md b/docs/usage-guide/topics/ch05-config.md index c69f9d6f134..146778b559d 100644 --- a/docs/usage-guide/topics/ch05-config.md +++ b/docs/usage-guide/topics/ch05-config.md @@ -1,6 +1,6 @@ # Configuring the Connection -Users start by building a config. `s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configurations before establishing any connection, and the config should not be altered once it is associated with a connection as this will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. +`s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configurations before associating config with a connection. Mutating the config after association will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. Calling `s2n_config_new()` can have a performance cost during config creation due to loading default system certificates into the trust store (see [Configuring the Trust Store](./ch09-certificates.md#configuring-the-trust-store)). From 72e731dbe00c3133a7f7aa4b9d95000e31f61460 Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Wed, 6 Nov 2024 21:49:52 +0000 Subject: [PATCH 5/7] address PR comments: * add software architecture information on top of the connection chapter * resolve a nit --- docs/usage-guide/topics/ch04-connection.md | 2 ++ docs/usage-guide/topics/ch05-config.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/usage-guide/topics/ch04-connection.md b/docs/usage-guide/topics/ch04-connection.md index 48a95f40ea0..ab8f82b1322 100644 --- a/docs/usage-guide/topics/ch04-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,5 +1,7 @@ # TLS Connections +Users interact with s2n-tls primarily through the `s2n_connection` and `s2n_config` structures. Users should build a `s2n_config` object and `s2n_connection` objects, associate the config with those connections, and then calling `s2n_negotiate()` on those connections until the TLS handshakes are completed. Users should then call `s2n_send`/`s2n_recv` on those connections to send and receive application data. + Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. One `s2n_connection` must be created for each TCP stream. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. ## Connection Memory diff --git a/docs/usage-guide/topics/ch05-config.md b/docs/usage-guide/topics/ch05-config.md index 146778b559d..3d1cd8c44bb 100644 --- a/docs/usage-guide/topics/ch05-config.md +++ b/docs/usage-guide/topics/ch05-config.md @@ -1,6 +1,6 @@ # Configuring the Connection -`s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configurations before associating config with a connection. Mutating the config after association will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. +`s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configuration before associating config with a connection. Mutating the config after association will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. Calling `s2n_config_new()` can have a performance cost during config creation due to loading default system certificates into the trust store (see [Configuring the Trust Store](./ch09-certificates.md#configuring-the-trust-store)). From 4b2dc23238b988413402c8fc8149b8d8f7cbe18b Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Fri, 8 Nov 2024 20:07:46 +0000 Subject: [PATCH 6/7] address PR comments: * remove repetitive sentences, and make wording more precise. * link relevant sections to software architecture's overview. --- docs/usage-guide/topics/ch04-connection.md | 2 +- docs/usage-guide/topics/ch05-config.md | 2 +- docs/usage-guide/topics/ch11-resumption.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage-guide/topics/ch04-connection.md b/docs/usage-guide/topics/ch04-connection.md index ab8f82b1322..5a19c116e9f 100644 --- a/docs/usage-guide/topics/ch04-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,6 +1,6 @@ # TLS Connections -Users interact with s2n-tls primarily through the `s2n_connection` and `s2n_config` structures. Users should build a `s2n_config` object and `s2n_connection` objects, associate the config with those connections, and then calling `s2n_negotiate()` on those connections until the TLS handshakes are completed. Users should then call `s2n_send`/`s2n_recv` on those connections to send and receive application data. +Users interact with s2n-tls primarily through the `s2n_connection` and `s2n_config` structures. In general, users build a `s2n_config` object and `s2n_connection` objects, associate the config with those connections, and then calling `s2n_negotiate()` on those connections until the TLS handshakes are completed. Users should then call `s2n_send`/`s2n_recv` on those connections to send and receive application data. For more detailed information on TLS handshakes and the process of sending and receiving data, refer to the [Sending and Receiving](./ch07-io.md) chapter. Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. One `s2n_connection` must be created for each TCP stream. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. diff --git a/docs/usage-guide/topics/ch05-config.md b/docs/usage-guide/topics/ch05-config.md index 3d1cd8c44bb..009e587f16e 100644 --- a/docs/usage-guide/topics/ch05-config.md +++ b/docs/usage-guide/topics/ch05-config.md @@ -1,6 +1,6 @@ # Configuring the Connection -`s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading the certificate, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Users should complete all configuration before associating config with a connection. Mutating the config after association will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. +`s2n_config` objects are used to change the default settings of a s2n-tls connection, such as loading certificates, configuring session resumption, etc. Use `s2n_config_new()` to create a new config object. To associate a config with a connection call `s2n_connection_set_config()`. Modifying the config after association will produce undefined behavior. It is not necessary to create a config object per connection; one config object should be used for many connections. Call `s2n_config_free()` to free the object when no longer needed. _Only_ free the config object when all connections using it have been freed. Calling `s2n_config_new()` can have a performance cost during config creation due to loading default system certificates into the trust store (see [Configuring the Trust Store](./ch09-certificates.md#configuring-the-trust-store)). diff --git a/docs/usage-guide/topics/ch11-resumption.md b/docs/usage-guide/topics/ch11-resumption.md index 4d60c957021..93f3fd487cd 100644 --- a/docs/usage-guide/topics/ch11-resumption.md +++ b/docs/usage-guide/topics/ch11-resumption.md @@ -3,7 +3,7 @@ TLS handshake sessions are CPU-heavy due to the calculations involved in authent ## Session Ticket Key -The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. Calling `s2n_config_add_ticket_crypto_key()` is an exception to the general immutability of the `s2n_config` object. +The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. Unlike other methods that modify `s2n_config` objects, `s2n_config_add_ticket_crypto_key()` can be called after associating an `s2n_config` object with a connection. Each key has two different expiration dates. The first expiration date signifies the time that the key can be used for both encryption and decryption. The second expiration date signifies the time that the key can be used only for decryption. This mechanism is to ensure that a session ticket can be successfully decrypted if it was encrypted by a key that was about to expire. The full lifetime of the key is therefore the encrypt-decrypt lifetime plus the decrypt-only lifetime. To alter the default key lifetime call `s2n_config_set_ticket_encrypt_decrypt_key_lifetime()` and `s2n_config_set_ticket_decrypt_key_lifetime()`. From 604f9ab6f665aca7a9ac27c464dc3c65fa3b92ae Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Fri, 8 Nov 2024 22:47:04 +0000 Subject: [PATCH 7/7] address PR comments: * change wording * move software architecture section to proper position * give general introductions about connection and config --- docs/usage-guide/topics/ch04-connection.md | 2 +- docs/usage-guide/topics/ch11-resumption.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage-guide/topics/ch04-connection.md b/docs/usage-guide/topics/ch04-connection.md index 5a19c116e9f..24239d4d8c3 100644 --- a/docs/usage-guide/topics/ch04-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,6 +1,6 @@ # TLS Connections -Users interact with s2n-tls primarily through the `s2n_connection` and `s2n_config` structures. In general, users build a `s2n_config` object and `s2n_connection` objects, associate the config with those connections, and then calling `s2n_negotiate()` on those connections until the TLS handshakes are completed. Users should then call `s2n_send`/`s2n_recv` on those connections to send and receive application data. For more detailed information on TLS handshakes and the process of sending and receiving data, refer to the [Sending and Receiving](./ch07-io.md) chapter. +A TLS connection is a secure and encrypted channel established between two communicating peers. A TLS connection is used to send and receive data, perform TLS handshake negotiations, send alert messages, and etc. Read [TLS Connections](./ch04-connection.md) for information about connections, and [Sending and Receiving](./ch07-io.md) for io interactions. TLS connections are configured by TLS configs, which contains a collection of TLS settings. TLS configs apply rules on TLS connections by defining connection specs, such as supported certificate authorities. Read [Configuring the Connection](./ch05-config.md) for information about TLS connection and config interactions. Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. One `s2n_connection` must be created for each TCP stream. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. diff --git a/docs/usage-guide/topics/ch11-resumption.md b/docs/usage-guide/topics/ch11-resumption.md index 93f3fd487cd..0e2ac8ceec6 100644 --- a/docs/usage-guide/topics/ch11-resumption.md +++ b/docs/usage-guide/topics/ch11-resumption.md @@ -3,7 +3,7 @@ TLS handshake sessions are CPU-heavy due to the calculations involved in authent ## Session Ticket Key -The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. Unlike other methods that modify `s2n_config` objects, `s2n_config_add_ticket_crypto_key()` can be called after associating an `s2n_config` object with a connection. +The key that encrypts and decrypts the session state is not related to the keys negotiated as part of the TLS handshake and has to be set by the server by calling `s2n_config_add_ticket_crypto_key()`. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. Unlike other methods that modify `s2n_config` objects, `s2n_config_add_ticket_crypto_key()` can be called after setting an `s2n_config` object on a connection. Each key has two different expiration dates. The first expiration date signifies the time that the key can be used for both encryption and decryption. The second expiration date signifies the time that the key can be used only for decryption. This mechanism is to ensure that a session ticket can be successfully decrypted if it was encrypted by a key that was about to expire. The full lifetime of the key is therefore the encrypt-decrypt lifetime plus the decrypt-only lifetime. To alter the default key lifetime call `s2n_config_set_ticket_encrypt_decrypt_key_lifetime()` and `s2n_config_set_ticket_decrypt_key_lifetime()`.