More documentation

api/s2n.h

@@ -1396,6 +1396,9 @@ S2N_API extern struct s2n_client_hello *s2n_connection_get_client_hello(struct s
 /**
  * Creates an s2n_client_hello from bytes representing a ClientHello message.
  *
+ * The input bytes should include the message header (message type and length),
+ * but not the record header.
+ *
  * Unlike s2n_connection_get_client_hello, the s2n_client_hello returned by this
  * method is owned by the application and must be freed with s2n_client_hello_free.
  *

docs/usage-guide/topics/ch10-client-hello.md

@@ -1,14 +1,30 @@
 # Examining the Client Hello
 
+## Getting a Client Hello
+
+### From a connection
 s2n-tls stores the received Client Hello and makes it available to the application. Call `s2n_connection_get_client_hello()` to get a pointer to the `s2n_client_hello` struct storing the Client Hello message. A NULL value will be returned if the connection has not yet received the Client Hello. The earliest point in the handshake when this struct is available is during the [Client Hello Callback](#client-hello-callback). The stored Client Hello message will not be available after calling `s2n_connection_free_handshake()`.
 
+### From raw bytes
+s2n-tls can parse a Client Hello from raw bytes. Call `s2n_client_hello_parse_message`
+with raw bytes representing a Client Hello message (including the message header, but excluding
+the record header). The returned pointer to a `s2n_client_hello` struct behaves
+the same as a pointer returned from `s2n_connection_get_client_hello()`, except
+that the memory is owned by the application and must be freed with `s2n_client_hello_free`.
+
+## Examining the message
+
 Call `s2n_client_hello_get_raw_message()` to retrieve the complete Client Hello message with the random bytes on it zeroed out.
 
 Call `s2n_client_hello_get_cipher_suites()` to retrieve the list of cipher suites sent by the client.
 
 Call `s2n_client_hello_get_session_id()` to retrieve the session ID sent by the client in the ClientHello message. Note that this value may not be the session ID eventually associated with this particular connection since the session ID can change when the server sends the Server Hello. The official session ID can be retrieved with `s2n_connection_get_session_id()`after the handshake completes.
 
-Call `s2n_client_hello_get_extensions()` to retrieve the entire list of extensions sent in the Client Hello. Calling `s2n_client_hello_get_extension_by_id()` allows you to interrogate the `s2n_client_hello` struct for a specific extension.
+Call `s2n_client_hello_get_extensions()` to retrieve the entire list of extensions sent in the Client Hello. Calling `s2n_client_hello_get_extension_by_id()` to retrieve a specific extension. Because `s2n_client_hello_get_extension_by_id()` doesn't distinguish between zero-length extensions and missing extensions,
+`s2n_client_hello_has_extension()` should be used to check for the existence of an extension.
+
+Call `s2n_client_hello_get_supported_groups()` to retrieve the entire list of
+supported groups sent by the client.
 
 ## SSLv2
 s2n-tls will not negotiate SSLv2, but will accept SSLv2 ClientHellos advertising a