update security policy and rust binding documentation (aws#3906)

README.md

@@ -2,6 +2,10 @@
 
 s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority. It is released and licensed under the Apache License 2.0.
 
+> s2n-tls is short for "signal to noise" and is a nod to the almost magical act of encryption — disguising meaningful signals, like your critical data, as seemingly random noise.
+>
+> -- [s2n-tls announcement](https://aws.amazon.com/blogs/security/introducing-s2n-a-new-open-source-tls-implementation/)
+
 [![Build Status](https://codebuild.us-west-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiMndlTzJNbHVxWEo3Nm82alp4eGdGNm4rTWdxZDVYU2VTbitIR0ZLbHVtcFFGOW5majk5QnhqaUp3ZEkydG1ueWg0NGlhRE43a1ZnUzZaQTVnSm91TzFFPSIsIml2UGFyYW1ldGVyU3BlYyI6IlJLbW42NENlYXhJNy80QnYiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main)](https://github.com/aws/s2n-tls/)
 [![Apache 2 License](https://img.shields.io/github/license/aws/s2n-tls.svg)](http://aws.amazon.com/apache-2-0/)
 [![C99](https://img.shields.io/badge/language-C99-blue.svg)](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf)

bindings/rust/s2n-tls-sys/README.md

@@ -0,0 +1,3 @@
+This crates provides low level rust bindings for [s2n-tls](https://github.com/aws/s2n-tls) which are autogenerated with [bindgen](https://github.com/rust-lang/rust-bindgen)
+
+This crate is not intended for direct consumption by end consumers. Interested developers should instead look at the [s2n-tls](https://crates.io/crates/s2n-tls) or [s2n-tls-tokio](https://crates.io/crates/s2n-tls-tokio) crates. These  provide higher-level, more ergonomic bindings than the `s2n-tls-sys` crate.

bindings/rust/s2n-tls-tokio/README.md

@@ -0,0 +1 @@
+`s2n-tls-tokio` provides async bindings that allow consumers to use [s2n-tls](https://github.com/aws/s2n-tls) within the tokio runtime. To consume `s2n-tls` outside of an async context consider using the [s2n-tls](https://crates.io/crates/s2n-tls) crate.

bindings/rust/s2n-tls/README.md

@@ -0,0 +1,2 @@
+This crate provides ergonomic, idiomatic Rust bindings for [s2n-tls](https://github.com/aws/s2n-tls). From the s2n-tls readme:
+> s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority. It is released and licensed under the Apache License 2.0.

tls/s2n_security_policies.h

@@ -25,12 +25,49 @@
 /* Kept up-to-date by s2n_security_policies_test */
 #define NUM_RSA_PSS_SCHEMES 6
 
+/* The s2n_security_policy struct is used to define acceptable and available
+ * algorithms for use in the TLS protocol. Note that the behavior of each field
+ * likely differs between different TLS versions, as the mechanics of cipher
+ * negotiation often have significant differences between TLS versions.
+ *
+ * In s2n-tls, the signature_algorithms extension only applies to signatures in
+ * CertificateVerify messages. To specify acceptable signature algorithms for
+ * certificates the certificate_signature_preferences field should be set in the
+ * security policy.
+ */
 struct s2n_security_policy {
     uint8_t minimum_protocol_version;
+    /* TLS 1.0 - 1.2 - cipher preference includes multiple elements such
+     * as signature algorithms, record algorithms, and key exchange algorithms
+     * TLS 1.3 - cipher preference only determines record encryption
+     */
     const struct s2n_cipher_preferences *cipher_preferences;
+    /* kem_preferences is only used for Post-Quantum cryptography */
     const struct s2n_kem_preferences *kem_preferences;
+    /* This field roughly corresponds to the "signature_algorithms" extension.
+     * The client serializes this field of the security_policy to populate the
+     * extension, and it is also used by the server to choose an appropriate
+     * entry from the options supplied by the client.
+     * TLS 1.2 - optional extension to specify signature algorithms other than
+     * default: https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.4.1
+     * TLS 1.3 - required extension specifying signature algorithms
+    */
     const struct s2n_signature_preferences *signature_preferences;
+    /* When this field is set, the endpoint will ensure that the signatures on
+     * the certificates in the peer's certificate chain are in the specified
+     * list. Note that s2n-tls does not support the signature_algorithms_cert
+     * extension. Unlike the signature_preferences field, this information is
+     * never transmitted to a peer.
+    */
     const struct s2n_signature_preferences *certificate_signature_preferences;
+    /* This field roughly corresponds to the information in the
+     * "supported_groups" extension.
+     * TLS 1.0 - 1.2 - "elliptic_curves" extension indicates supported groups
+     * for both key exchange and signature algorithms.
+     * TLS 1.3 - the "supported_groups" extension indicates the named groups
+     * which the client supports for key exchange
+     * https://www.rfc-editor.org/rfc/rfc8446#section-4.2.7
+     */
     const struct s2n_ecc_preferences *ecc_preferences;
 };
 

tls/s2n_x509_validator.c

@@ -732,6 +732,30 @@ S2N_RESULT s2n_validate_certificate_signature(struct s2n_connection *conn, X509
     const struct s2n_security_policy *security_policy;
     RESULT_GUARD_POSIX(s2n_connection_get_security_policy(conn, &security_policy));
 
+    /**
+     * We only restrict the signature algorithm on the certificates in the
+     * peer's certificate chain if the certificate_signature_preferences field
+     * is set in the security policy. This is contrary to the RFC, which
+     * specifies that the signatures in the "signature_algorithms" extension
+     * apply to signatures in the certificate chain in certain scenarios, so RFC
+     * compliance would imply validating that the certificate chain signature
+     * algorithm matches one of the algorithms specified in the
+     * "signature_algorithms" extension.
+     *
+     *= https://www.rfc-editor.org/rfc/rfc5246#section-7.4.2
+     *= type=exception
+     *= reason=not implemented due to lack of utility
+     *# If the client provided a "signature_algorithms" extension, then all
+     *# certificates provided by the server MUST be signed by a
+     *# hash/signature algorithm pair that appears in that extension.
+     *
+     *= https://www.rfc-editor.org/rfc/rfc8446#section-4.2.3
+     *= type=exception
+     *= reason=not implemented due to lack of utility
+     *# If no "signature_algorithms_cert" extension is present, then the
+     *# "signature_algorithms" extension also applies to signatures appearing in
+     *# certificates.
+     */
     if (security_policy->certificate_signature_preferences == NULL) {
         return S2N_RESULT_OK;
     }