(docs): Reordered and moved usage guide into an mdbook (#4300)

README.md

@@ -44,7 +44,7 @@ If you have any questions about submitting PRs, s2n-tls API usage, or something
 
 ## Documentation
 
-s2n-tls uses [Doxygen](https://doxygen.nl/index.html) to document its public API. The latest s2n-tls documentation can be found on [GitHub pages](https://aws.github.io/s2n-tls/doxygen/). The [Usage Guide](docs/USAGE-GUIDE.md) explains how different TLS features can be configured and used.
+s2n-tls uses [Doxygen](https://doxygen.nl/index.html) to document its public API. The latest s2n-tls documentation can be found on [GitHub pages](https://aws.github.io/s2n-tls/doxygen/). The [Usage Guide](docs/usage-guide/) explains how different TLS features can be configured and used.
 
 Documentation for older versions or branches of s2n-tls can be generated locally. To generate the documentation, install doxygen and run `doxygen docs/doxygen/Doxyfile`. The doxygen documentation can now be found at `docs/doxygen/output/html/index.html`.
 
@@ -77,7 +77,7 @@ int bytes_written;
 bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked);
 ```
 
-For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [usage guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md).
+For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [usage guide][Usage Guide](docs/usage-guide).
 
 ## s2n-tls features
 

api/s2n.h

@@ -142,7 +142,7 @@ S2N_API extern int *s2n_errno_location(void);
  * error. To retrieve the type for a given error use `s2n_error_get_type()`. Applications should
  * perform any error handling logic using these high level types.
  *
- * See the [Error Handling](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#error-handling) section for how the errors should be interpreted. 
+ * See the [Error Handling](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch03-error-handling.md) section for how the errors should be interpreted.
  */
 typedef enum {
     /** No error */
@@ -673,7 +673,7 @@ S2N_API extern int s2n_cert_chain_and_key_load_pem_bytes(struct s2n_cert_chain_a
 /**
  * Associates a public certificate chain with a `s2n_cert_chain_and_key` object. It does
  * NOT set a private key, so the connection will need to be configured to
- * [offload private key operations](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#offloading-asynchronous-private-key-operations).
+ * [offload private key operations](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch12-private-key-ops.md).
  *
  * @param chain_and_key The certificate chain and private key handle
  * @param chain_pem A byte array of a PEM encoded certificate chain.
@@ -1043,7 +1043,7 @@ S2N_API extern int s2n_config_add_dhparams(struct s2n_config *config, const char
  * Sets the security policy that includes the cipher/kem/signature/ecc preferences and
  * protocol version.
  *
- * See the [USAGE-GUIDE.md](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md) for how to use security policies.
+ * See the [USAGE-GUIDE.md](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide) for how to use security policies.
  */
 S2N_API extern int s2n_config_set_cipher_preferences(struct s2n_config *config, const char *version);
 
@@ -3295,7 +3295,7 @@ S2N_API int s2n_connection_get_max_early_data_size(struct s2n_connection *conn,
 /**
  * Called by the client to begin negotiation and send early data.
  *
- * See https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#using-early-data--0rtt
+ * See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md
  * for usage and examples. DO NOT USE unless you have considered the security issues and
  * implemented mitigation for anti-replay attacks.
  *
@@ -3312,7 +3312,7 @@ S2N_API int s2n_send_early_data(struct s2n_connection *conn, const uint8_t *data
 /**
  * Called by the server to begin negotiation and accept any early data the client sends.
  *
- * See https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#using-early-data--0rtt
+ * See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md
  * for usage and examples. DO NOT USE unless you have considered the security issues and
  * implemented mitigation for anti-replay attacks.
  *

bin/s2nc.c

@@ -61,7 +61,7 @@ void usage()
     fprintf(stderr, "    Sets the application protocols supported by this client, as a comma separated list.\n");
     fprintf(stderr, "  -c [version_string]\n");
     fprintf(stderr, "  --ciphers [version_string]\n");
-    fprintf(stderr, "    Set the cipher preference version string. Defaults to \"default\". See USAGE-GUIDE.md\n");
+    fprintf(stderr, "    Set the cipher preference version string. Defaults to \"default\" \n");
     fprintf(stderr, "  --enter-fips-mode\n");
     fprintf(stderr, "    Enter libcrypto's FIPS mode. The linked version of OpenSSL must be built with the FIPS module.\n");
     fprintf(stderr, "  -e,--echo\n");

bin/s2nd.c

@@ -145,7 +145,7 @@ void usage()
     fprintf(stderr, "    Sets a single application protocol supported by this server.\n");
     fprintf(stderr, "  -c [version_string]\n");
     fprintf(stderr, "  --ciphers [version_string]\n");
-    fprintf(stderr, "    Set the cipher preference version string. Defaults to \"default\". See USAGE-GUIDE.md\n");
+    fprintf(stderr, "    Set the cipher preference version string. Defaults to \"default\" \n");
     fprintf(stderr, "  --enter-fips-mode\n");
     fprintf(stderr, "    Enter libcrypto's FIPS mode. The linked version of OpenSSL must be built with the FIPS module.\n");
     fprintf(stderr, "  --cert\n");

docs/BUILD.md

@@ -68,7 +68,21 @@ cmake --install build
 
 Note that we currently do not support building on Windows. See https://github.com/aws/s2n-tls/issues/497 for more information.
 
-See the [s2n-tls usage guide](USAGE-GUIDE.md#consuming-s2n-tls-via-cmake) for instructions on how to include s2n-tls in your CMake project.
+## Consuming s2n-tls via CMake
+
+s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is:
+
+````bash
+find_package(s2n)
+
+....
+
+target_link_libraries(yourExecutableOrLibrary AWS::s2n)
+````
+
+And when invoking CMake for your project, do one of two things:
+ 1. Set the `CMAKE_INSTALL_PREFIX` variable with the path to your s2n-tls build.
+ 2. If you have globally installed s2n-tls, do nothing, it will automatically be found.
 
 ## Configuring the s2n-tls build
 

docs/DEVELOPMENT-GUIDE.md

@@ -2,7 +2,7 @@
 
 If you are curious about the internals of s2n-tls, or interested in contributing to
 s2n-tls, this document is for you. If instead you are interested in using s2n-tls in an application
-that you are developing, please see the accompanying [Usage Guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md).
+that you are developing, please see the accompanying [Usage Guide](usage-guide).
 
 ## s2n-tls's development principles
 

docs/FAQ.md

@@ -15,23 +15,23 @@ higher than "TLS1.2" for similar reasons.
 If the client does support TLS1.3, it will include that information in the ClientHello
 "supported_versions" extension instead of setting any of the legacy version fields.
 
-s2n-tls offers [methods](USAGE-GUIDE/#protocol-version) to retrieve accurate protocol versions.
+s2n-tls offers [methods](usage-guide/topics/ch04-connection.md) to retrieve accurate protocol versions.
 
 ### Why isn't my connection using TLS1.3?
 There are several possible reasons:
-* Are you using a security policy that supports TLS1.3? See [security policies](USAGE-GUIDE.md/#security-policies).
+* Are you using a security policy that supports TLS1.3? See [security policies](usage-guide/topics/ch06-security-policies.md).
 * Are you verifying the connection version correctly? See [the previous question](FAQ.md#why-is-my-connection-using-tls10).
 * Are you using a libcrypto library that supports TLS1.3? Modern libcrypto libraries support the algorithms needed for TLS1.3, but older libraries like Openssl 1.0.2 do not. If s2n-tls is built with Openssl 1.0.2, TLS1.3 is unlikely to be negotiated. 
 * Does your peer support TLS1.3? If your peer does not support TLS1.3, TLS1.3 will not be negotiated.
 
 ### Why is the TLS handshake failing on validating my peer's certificate?
-Have you already configure a trust store to be able to trust your peer's certificate? If so it may be necessary to implement `s2n_verify_host_fn` as the default behavior may not work for your use case. See the [certificates](USAGE-GUIDE.md/#certificates-and-authentication) section for detailed instructions on verifying a peer's certificate.
+Have you already configure a trust store to be able to trust your peer's certificate? If so it may be necessary to implement `s2n_verify_host_fn` as the default behavior may not work for your use case. See the [certificates](usage-guide/topics/ch09-certificates.md) section for detailed instructions on verifying a peer's certificate.
 
 ### Why is s2n hanging for so long before erroring?
-s2n-tls sleeps for a random period between 10 and 30 seconds after specific errors occur to avoid leaking any secret information via timing data. This technique is called blinding and it is utilized to prevent timing side-channel attacks. See [blinding](USAGE-GUIDE.md/#blinding).
+s2n-tls sleeps for a random period between 10 and 30 seconds after specific errors occur to avoid leaking any secret information via timing data. This technique is called blinding and it is utilized to prevent timing side-channel attacks. See [blinding](usage-guide/topics/ch03-error-handling.md#blinding).
 
 ### Which security policy should I use if I want to make sure that it will never be altered?
-Our numbered security policies are guaranteed to never change. We will not alter or update them based on changing cryptography standards. However, our named security policies (like “default” or “default_tls13”) change based on new cryptography standards that come out. See [security policies](USAGE-GUIDE.md/#security-policies).
+Our numbered security policies are guaranteed to never change. We will not alter or update them based on changing cryptography standards. However, our named security policies (like “default” or “default_tls13”) change based on new cryptography standards that come out. See [security policies](usage-guide/topics/ch06-security-policies.md).
 
 ### Why does s2n-tls have a dependency on OpenSSL? Isn't s2n-tls a replacement for OpenSSL?
 OpenSSL includes both a TLS library, called libssl, and a cryptography library, called libcrypto. s2n-tls implements a TLS library, but does not implement a cryptography library. Instead, s2n-tls links to a separate libcrypto in order to perform cryptographic operations. Libcryptos other than OpenSSL can be used, such as [AWS-LC](https://github.com/aws/aws-lc).