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..24239d4d8c3 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. +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. ## Connection Memory diff --git a/docs/usage-guide/topics/ch05-config.md b/docs/usage-guide/topics/ch05-config.md index 6ffaa23c68c..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. 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, 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 756f0823d92..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. +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()`.