doc: add information about s2n-tls software architecture

* add software architecture md file * insert the file before connection doc
aws · Nov 1, 2024 · 86fb37d · 86fb37d
1 parent 19859ef
commit 86fb37d
Show file tree

Hide file tree

Showing 14 changed files with 34 additions and 12 deletions.
diff --git 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
@@ -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 → docs/usage-guide/topics/ch05-connection.md b/docs/usage-guide/topics/ch04-connection.md → docs/usage-guide/topics/ch05-connection.md
diff --git a/docs/usage-guide/topics/ch05-config.md → docs/usage-guide/topics/ch06-config.md b/docs/usage-guide/topics/ch05-config.md → docs/usage-guide/topics/ch06-config.md
diff --git a/...ge-guide/topics/ch06-security-policies.md → ...ge-guide/topics/ch07-security-policies.md b/...ge-guide/topics/ch06-security-policies.md → ...ge-guide/topics/ch07-security-policies.md
diff --git a/docs/usage-guide/topics/ch07-io.md → docs/usage-guide/topics/ch08-io.md b/docs/usage-guide/topics/ch07-io.md → docs/usage-guide/topics/ch08-io.md
diff --git a/docs/usage-guide/topics/ch08-record-sizes.md → docs/usage-guide/topics/ch09-record-sizes.md b/docs/usage-guide/topics/ch08-record-sizes.md → docs/usage-guide/topics/ch09-record-sizes.md
diff --git a/docs/usage-guide/topics/ch09-certificates.md → docs/usage-guide/topics/ch10-certificates.md b/docs/usage-guide/topics/ch09-certificates.md → docs/usage-guide/topics/ch10-certificates.md
diff --git a/docs/usage-guide/topics/ch10-client-hello.md → docs/usage-guide/topics/ch11-client-hello.md b/docs/usage-guide/topics/ch10-client-hello.md → docs/usage-guide/topics/ch11-client-hello.md
diff --git a/docs/usage-guide/topics/ch11-resumption.md → docs/usage-guide/topics/ch12-resumption.md b/docs/usage-guide/topics/ch11-resumption.md → docs/usage-guide/topics/ch12-resumption.md
diff --git a/...sage-guide/topics/ch12-private-key-ops.md → ...sage-guide/topics/ch13-private-key-ops.md b/...sage-guide/topics/ch12-private-key-ops.md → ...sage-guide/topics/ch13-private-key-ops.md
diff --git a/...usage-guide/topics/ch13-preshared-keys.md → ...usage-guide/topics/ch14-preshared-keys.md b/...usage-guide/topics/ch13-preshared-keys.md → ...usage-guide/topics/ch14-preshared-keys.md
diff --git a/docs/usage-guide/topics/ch14-early-data.md → docs/usage-guide/topics/ch15-early-data.md b/docs/usage-guide/topics/ch14-early-data.md → docs/usage-guide/topics/ch15-early-data.md
diff --git a/docs/usage-guide/topics/ch15-post-quantum.md → docs/usage-guide/topics/ch16-post-quantum.md b/docs/usage-guide/topics/ch15-post-quantum.md → docs/usage-guide/topics/ch16-post-quantum.md