doc: add information about s2n-tls software architecture

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)
-- [TLS Connections](./ch04-connection.md)
-- [Configuring the Connection](./ch05-config.md)
+- [Configuring the Connection](./ch04-config.md)
+- [TLS Connections](./ch05-connection.md)
 - [Security Policies](./ch06-security-policies.md)
 - [IO](./ch07-io.md)
 - [TLS Record Sizes](./ch08-record-sizes.md)

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.

docs/usage-guide/topics/ch05-config.md → 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

docs/usage-guide/topics/ch04-connection.md → 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

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()`.