Release Summary:

Add a new public API, s2n_client_hello_get_random(), and move client_random storage from the connection to the s2n_client_hello struct so applications can retrieve the client random from a parsed ClientHello.

Goal

Add a public API function to retrieve the client random value from a parsed client hello message.

Why

Applications may need access to the client random, but currently have no way to retrieve it without manually parsing the raw client hello message. The raw message has the client random zeroed out for security, making it inaccessible. Moving forward, we want to have one souce of truth for CH random, so this change moves random from the connection object to the client_hello object so that it can be accessed.

How

• Add client_random field to s2n_client_hello struct to store the actual client random value
• Implement s2n_client_hello_get_random() public API function that copies the stored value to caller's buffer
• Use s2n_stuffer_erase_and_read_bytes() during parsing to read the client random into the struct field while zeroing it in the raw message for security
• Migrate all references from conn->handshake_params.client_random to conn->client_hello.client_random throughout the codebase

Callouts

The raw message continues to have the client random zeroed for security/privacy reasons. Applications must use the new getter function to access the actual client random value. On Hello Retry Request, the client random is preserved from the first client hello for validation purposes.

This change consolidates client random storage from handshake_params to client_hello, making it the single source of truth for the client random value and aligning with the logical ownership of this data. This also mitigates the performance/memory impact of adding a new field since we are replacing a connection level field with a client_hello field.

Testing

• Added new unit test in s2n_client_hello_test.c that:
  • Constructs a minimal TLS 1.2 ClientHello with custom random value
  • Parses the ClientHello and retrieves the random using the new getter
  • Verifies the retrieved value matches the original custom value
  • Verifies the raw message has the client random zeroed out
• All client hello and retry tests pass, including s2n_client_hello_retry_test
• Updated all unit tests which relied on handshake_params client random (PRF, key log, serialization, SSL v2) to use the new client_hello field.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.