Client Hello carries not SNI, signature schemes and ALPN protocols.

  - Added a base.rs for structs providing strings, string arrays and
    short arrays to C callback functions.
  - Extended rustls_client_hello, adapted the prototype and added
    documentation.
  - Made a section about EXPERIMENTAL features in the README.md

Author: Stefan Eissing

README.md

@@ -114,3 +114,41 @@ Functions that are theoretically infallible don't return rustls_result, so we
 can't return RUSTLS_RESULT_PANIC. In those cases, if there's a panic, we'll
 return a default value suitable to the return type: NULL for pointer types,
 false for bool types, and 0 for integer types.
+
+# Experimentals
+
+Several features of the C bindings are marked as `EXPERIMENTAL` as they are
+need further evaluation and will most likely change significantly in the future.
+
+## Server Side Experimentals
+
+The `rustls_server_config_builder_set_hello_callback` and its provided information
+in `rustls_client_hello` will change. The current design is a snapshot of the 
+implementation efforts in [mod_tls](https://github.com/icing/mod_tls) to provide
+`rustls` base TLS as module for the Apache webserver.
+
+For a webserver hosting multiple domains on the same endpoint, it is highly desirable
+to have individual TLS settings, depending on the domain the client wants to talk to.
+Most domains have their own TLS certificates, some have configured restrictions on
+other features as well, such as TLS protocol versions, ciphers or client authentication.
+
+The approach to this taken with the current `rustls_client_hello` is as follows:
+
+#### One domain, one cert
+
+If you have a single site and one certificate, you can preconfigure the `rustls_server_config` accordingly and do not need to register any callback.
+
+#### Multiple domains/certs/settings
+
+If you need to support multiple `rustls_server_config`s on the same connection endpoint, you can start the connection with a default `rustls_server_config` and register a client hello callback. The callback inspects the SNI/ALPN/cipher values announced by the client and selects the appropriate configuration to use.
+
+When your callback returns, the handshake of `rustls` will fail, as no certifcate was configured. This will be noticeable as an error returned from `rustls_server_session_write_tls()`. You can then free this session
+and create the one with the correct setting for the domain chosen.
+
+For this to work, your connection needs ot buffer the initial data from the client, so these bytes can be 
+replayed to the second session you use. Do not write any data back to the client while your are
+in the initial session. The client hellos are usually only a few hundred bytes.
+
+
+
+

src/base.rs

@@ -0,0 +1,108 @@
+use libc::size_t;
+use std::os::raw::{c_char, c_ushort};
+
+/// A read-only view on a Rust utf-8 string or byte array.
+/// This is used to pass data from crustls to callback functions provided
+/// by the user of the API. The `data` is not NUL-terminated.
+/// `len` indicates the number of bytes than can be safely read.
+/// A `len` of 0 is used to represent a missing value.
+///
+/// The memmory exposed is available for the duration of the call (e.g.
+/// when passed to a callback) and must be copied if the values are
+/// needed for longer.
+///
+#[allow(non_camel_case_types)]
+#[repr(C)]
+pub struct rustls_string {
+    data: *const c_char,
+    len: size_t,
+}
+
+impl<'a> From<&'a String> for rustls_string {
+    fn from(s: &String) -> Self {
+        rustls_string {
+            data: s.as_ptr() as *const c_char,
+            len: s.len() as size_t,
+        }
+    }
+}
+
+impl<'a> From<&'a str> for rustls_string {
+    fn from(s: &str) -> Self {
+        rustls_string {
+            data: s.as_ptr() as *const c_char,
+            len: s.len() as size_t,
+        }
+    }
+}
+
+impl<'a> From<&'a [u8]> for rustls_string {
+    fn from(s: &[u8]) -> Self {
+        rustls_string {
+            data: s.as_ptr() as *const c_char,
+            len: s.len() as size_t,
+        }
+    }
+}
+
+pub(crate) fn rustls_strings<'a>(values: Option<&'a [&'a [u8]]>) -> Vec<rustls_string> {
+    let mut strings: Vec<rustls_string> = Vec::new();
+    match values {
+        Some(values) => {
+            for entry in values.iter() {
+                strings.push(rustls_string::from(*entry))
+            }
+        }
+        None => (),
+    };
+    strings
+}
+
+/// A read-only view on a list of Rust utf-8 strings or byte arrays.
+/// This is used to pass data from crustls to callback functions provided
+/// by the user of the API. The `data` is an array of `rustls_string`
+/// structures with `len` elements.
+///
+/// The memmory exposed is available for the duration of the call (e.g.
+/// when passed to a callback) and must be copied if the values are
+/// needed for longer.
+///
+#[allow(non_camel_case_types)]
+#[repr(C)]
+pub struct rustls_vec_string {
+    data: *const rustls_string,
+    len: size_t,
+}
+
+impl<'a> From<&'a Vec<rustls_string>> for rustls_vec_string {
+    fn from(values: &Vec<rustls_string>) -> Self {
+        rustls_vec_string {
+            data: values.as_ptr(),
+            len: values.len(),
+        }
+    }
+}
+
+/// A read-only view on a list of Rust owned unsigned short values.
+/// This is used to pass data from crustls to callback functions provided
+/// by the user of the API. The `data` is an array of `len` 16 bit values.
+///
+/// The memmory exposed is available for the duration of the call (e.g.
+/// when passed to a callback) and must be copied if the values are
+/// needed for longer.
+///
+#[allow(non_camel_case_types)]
+#[repr(C)]
+pub struct rustls_vec_ushort {
+    data: *const c_ushort,
+    len: size_t,
+}
+
+impl From<&Vec<u16>> for rustls_vec_ushort {
+    fn from(values: &Vec<u16>) -> Self {
+        rustls_vec_ushort {
+            data: values.as_ptr(),
+            len: values.len(),
+        }
+    }
+}

src/cipher.rs

@@ -4,7 +4,10 @@ use crate::{ffi_panic_boundary_generic, ffi_panic_boundary_unit};
 use libc::{c_char, size_t};
 use std::os::raw::c_ushort;
 
-static ALL_SIGNATURE_SCHEMES: &[rustls::SignatureScheme] = &[
+/// All SignatureScheme currently defines in rustls.
+/// At the moment not exposed by rustls itself.
+#[no_mangle]
+pub(crate) static ALL_SIGNATURE_SCHEMES: &[rustls::SignatureScheme] = &[
     rustls::SignatureScheme::RSA_PKCS1_SHA1,
     rustls::SignatureScheme::ECDSA_SHA1_Legacy,
     rustls::SignatureScheme::RSA_PKCS1_SHA256,
@@ -20,25 +23,39 @@ static ALL_SIGNATURE_SCHEMES: &[rustls::SignatureScheme] = &[
     rustls::SignatureScheme::ED448,
 ];
 
+/// rustls has the names in its Debug trait implementation, which
+/// we use for all known schemes. For all others we return the hex value.
+/// Note that this u16 values are used in protocol handshake by both sides,
+/// so we have to expect unknown values to arrive here.
 fn signature_scheme_name(n: u16) -> String {
     for scheme in ALL_SIGNATURE_SCHEMES {
         if scheme.get_u16() == n {
             return format!("{:?}", scheme);
         }
     }
-    String::from("Unknown")
+    format!("Unknown({:#06x})", n)
 }
 
-pub(crate) fn map_signature_schemes(schemes: &[rustls::SignatureScheme]) -> Vec<u16> {
+/// Collect the u16 values of the given SignatureScheme slice, so they
+/// can be exposed in our API.
+pub(crate) fn rustls_cipher_map_signature_schemes(schemes: &[rustls::SignatureScheme]) -> Vec<u16> {
     let mut mapped_schemes: Vec<u16> = Vec::new();
     for s in schemes {
         mapped_schemes.push(s.get_u16());
     }
     mapped_schemes
 }
 
+/// Get the name of a SignatureScheme, represented by the `scheme` short value,
+/// if known by the rustls library. For unknown schemes, this returns a string
+/// with the scheme value in hex notation.
+/// Mainly useful for debugging output.
+/// The caller provides `buf` for holding the string and gives its size as `len`
+/// bytes. On return `out_n` carries the number of bytes copied into `buf`. The
+/// `buf` is not NUL-terminated.
+///
 #[no_mangle]
-pub extern "C" fn rustls_signature_scheme_name(
+pub extern "C" fn rustls_cipher_get_signature_scheme_name(
     scheme: c_ushort,
     buf: *mut c_char,
     len: size_t,

src/crustls.h

@@ -134,17 +134,76 @@ typedef struct rustls_server_session rustls_server_session;
  */
 typedef void *rustls_client_hello_userdata;
 
+/**
+ * A read-only view on a Rust utf-8 string or byte array.
+ * This is used to pass data from crustls to callback functions provided
+ * by the user of the API. The `data` is not NUL-terminated.
+ * `len` indicates the number of bytes than can be safely read.
+ * A `len` of 0 is used to represent a missing value.
+ *
+ * The memmory exposed is available for the duration of the call (e.g.
+ * when passed to a callback) and must be copied if the values are
+ * needed for longer.
+ *
+ */
+typedef struct rustls_string {
+  const char *data;
+  size_t len;
+} rustls_string;
+
+/**
+ * A read-only view on a list of Rust owned unsigned short values.
+ * This is used to pass data from crustls to callback functions provided
+ * by the user of the API. The `data` is an array of `len` 16 bit values.
+ *
+ * The memmory exposed is available for the duration of the call (e.g.
+ * when passed to a callback) and must be copied if the values are
+ * needed for longer.
+ *
+ */
+typedef struct rustls_vec_ushort {
+  const unsigned short *data;
+  size_t len;
+} rustls_vec_ushort;
+
+/**
+ * A read-only view on a list of Rust utf-8 strings or byte arrays.
+ * This is used to pass data from crustls to callback functions provided
+ * by the user of the API. The `data` is an array of `rustls_string`
+ * structures with `len` elements.
+ *
+ * The memmory exposed is available for the duration of the call (e.g.
+ * when passed to a callback) and must be copied if the values are
+ * needed for longer.
+ *
+ */
+typedef struct rustls_vec_string {
+  const struct rustls_string *data;
+  size_t len;
+} rustls_vec_string;
+
 /**
  * The TLS Client Hello information provided to a ClientHelloCallback function.
- * `sni_name` is the SNI servername provided by the client (not 0 terminated) with
- * `sni_name_len` as its length. If the client did not provide an SNI, the name
- * length is 0.
+ * `sni_name` is the SNI servername provided by the client. If the client
+ * did not provide an SNI, the length of this `rustls_string` will be 0.
+ * The signature_schemes carries the values supplied by the client or, should
+ * the client not use this TLS extension, the default schemes in the rustls
+ * library. See:
+ * https://docs.rs/rustls/0.19.0/rustls/internal/msgs/enums/enum.SignatureScheme.html
+ * `alpn` carries the list of ALPN protocol names that the client proposed to
+ * the server. Again, the length of this list will be 0 if non were supplied.
+ *
+ * All this data, when passed to a callback function, is only accessible during
+ * the call and may not be modified. Users of this API must copy any values that
+ * they want to access when the callback returned.
+ *
+ * EXPERIMENTAL: this feature of crustls is likely to change in the future, as
+ * the rustls library is re-evaluating their current approach to client hello handling.
  */
 typedef struct rustls_client_hello {
-  const char *sni_name;
-  size_t sni_name_len;
-  const unsigned short *signature_schemes;
-  size_t signature_schemes_len;
+  struct rustls_string sni_name;
+  struct rustls_vec_ushort signature_schemes;
+  struct rustls_vec_string alpn;
 } rustls_client_hello;
 
 /**
@@ -154,6 +213,21 @@ typedef struct rustls_client_hello {
  */
 size_t rustls_version(char *buf, size_t len);
 
+/**
+ * Get the name of a SignatureScheme, represented by the `scheme` short value,
+ * if known by the rustls library. For unknown schemes, this returns a string
+ * with the scheme value in hex notation.
+ * Mainly useful for debugging output.
+ * The caller provides `buf` for holding the string and gives its size as `len`
+ * bytes. On return `out_n` carries the number of bytes copied into `buf`. The
+ * `buf` is not NUL-terminated.
+ *
+ */
+void rustls_cipher_get_signature_scheme_name(unsigned short scheme,
+                                             char *buf,
+                                             size_t len,
+                                             size_t *out_n);
+
 /**
  * Create a rustls_client_config_builder. Caller owns the memory and must
  * eventually call rustls_client_config_builder_build, then free the
@@ -438,17 +512,16 @@ enum rustls_result rustls_server_session_get_sni_hostname(const struct rustls_se
  * Register a callback to be invoked when a session created from this config
  * is seeing a TLS ClientHello message. The given `userdata` will be passed
  * to the callback when invoked.
- * Specifying `replace`!= 0 will replace any existing `ResolvesServerCert` in
- * the config. Otherwise, the existing `ResolvesServerCert` will be invoked
- * after the callback has been returned successfully.
- * Any error returned by the callback will abort the TLS handshake and give
- * an error in the called rustls function (most likely
- * `rustls_server_session_write_tls`).
+ * Any existing `ResolvesServerCert` implementation currently installed in the
+ * `rustls_server_config` will be replaced. This also means registering twice
+ * will overwrite the first registration. It is not permitted to pass a NULL
+ * value for `callback`, but it is possible to have `userdata` as NULL.
+ *
+ * EXPERIMENTAL: this feature of crustls is likely to change in the future, as
+ * the rustls library is re-evaluating their current approach to client hello handling.
  */
 enum rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_server_config_builder *builder,
                                                                    void (*callback)(rustls_client_hello_userdata userdata, const struct rustls_client_hello *hello),
                                                                    rustls_client_hello_userdata userdata);
 
-void rustls_signature_scheme_name(unsigned short scheme, char *buf, size_t len, size_t *out_n);
-
 #endif /* CRUSTLS_H */

src/lib.rs

@@ -3,10 +3,11 @@ use libc::{c_char, size_t};
 use std::{cmp::min, sync::Arc};
 use std::{mem, slice};
 
+mod base;
+mod cipher;
 mod client;
 mod error;
 mod server;
-mod cipher;
 
 // Keep in sync with Cargo.toml.
 const RUSTLS_CRATE_VERSION: &str = "0.19.0";