From ed58a00ffbc14bf9470387bbb3e65c1a289efdd4 Mon Sep 17 00:00:00 2001 From: Boquan Fang Date: Mon, 18 Nov 2024 21:28:53 -0800 Subject: [PATCH] doc: add information about s2n-tls software architecture (#4868) --- docs/usage-guide/topics/ch01-api.md | 2 ++ docs/usage-guide/topics/ch04-connection.md | 4 +++- docs/usage-guide/topics/ch05-config.md | 2 +- docs/usage-guide/topics/ch11-resumption.md | 2 +- 4 files changed, 7 insertions(+), 3 deletions(-) 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/ch04-connection.md b/docs/usage-guide/topics/ch04-connection.md index e9896c5a43e..72950caad08 100644 --- a/docs/usage-guide/topics/ch04-connection.md +++ b/docs/usage-guide/topics/ch04-connection.md @@ -1,6 +1,8 @@ # 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 general, s2n-tls works by operating on `s2n_connection` structs. A user should first create a connection by calling `s2n_connection_new()`. Then a [TLS handshake can be performed](./ch07-io.md#performing-the-tls-handshake) on the connection. Finally, the connection can be used to [send and receive encrypted data](./ch07-io.md#application-data). An `s2n_config` struct can be associated with a connection to [configure additional options](./ch05-config.md). + +Call `s2n_connection_free()` to free the memory allocated for connection 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 6ffaa23c68c..fb6a8fd065d 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. 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. +`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 set on 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)). diff --git a/docs/usage-guide/topics/ch11-resumption.md b/docs/usage-guide/topics/ch11-resumption.md index 756f0823d92..57bcabb0697 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. +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()`. 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. See [RFC5077](https://www.rfc-editor.org/rfc/rfc5077#section-5.5) for guidelines on securely generating keys. 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()`.