SSL_get_client_random¶

NAME¶

SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key, SSL_SESSION_set1_master_key - get internal TLS/SSL random values and get/set master key

SYNOPSIS¶

#include <openssl/ssl.h>

size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
size_t SSL_SESSION_get_master_key(const SSL_SESSION *session,
                                  unsigned char *out, size_t outlen);
int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in,
                                size_t len);

DESCRIPTION¶

SSL_get_client_random() extracts the random value sent from the client to the server during the initial SSL/TLS handshake. It copies as many bytes as it can of this value into the buffer provided in out, which must have at least outlen bytes available. It returns the total number of bytes that were actually copied. If outlen is zero, SSL_get_client_random() copies nothing, and returns the total size of the client_random value.

SSL_get_server_random() behaves the same, but extracts the random value sent from the server to the client during the initial SSL/TLS handshake.

SSL_SESSION_get_master_key() behaves the same, but extracts the master secret used to guarantee the security of the SSL/TLS session. This one can be dangerous if misused; see NOTES below.

SSL_SESSION_set1_master_key() sets the master key value associated with the SSL_SESSION sess. For example, this could be used to set up a session based PSK (see SSL_CTX_set_psk_use_session_callback(3)). The master key of length len should be provided at in. The supplied master key is copied by the function, so the caller is responsible for freeing and cleaning any memory associated with in. The caller must ensure that the length of the key is suitable for the ciphersuite associated with the SSL_SESSION.

NOTES¶

You probably shouldn't use these functions.

These functions expose internal values from the TLS handshake, for use in low-level protocols. You probably should not use them, unless you are implementing something that needs access to the internal protocol details.

Despite the names of SSL_get_client_random() and SSL_get_server_random(), they ARE NOT random number generators. Instead, they return the mostly-random values that were already generated and used in the TLS protocol. Using them in place of RAND_bytes() would be grossly foolish.

The security of your TLS session depends on keeping the master key secret: do not expose it, or any information about it, to anybody. If you need to calculate another secret value that depends on the master secret, you should probably use SSL_export_keying_material() instead, and forget that you ever saw these functions.

In current versions of the TLS protocols, the length of client_random (and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for other outlen arguments to the SSL_get_*_random() functions is provided in case of the unlikely event that a future version or variant of TLS uses some other length there.

Finally, though the "client_random" and "server_random" values are called "random", many TLS implementations will generate four bytes of those values based on their view of the current time.

On the server side the server_random value is generated during ClientHello processing, after the protocol version has been selected and the ClientHello has passed its initial checks (such as DTLS cookie verification and cipher list validation), but before the session is looked up. It is therefore available to callbacks invoked from that point on, such as the session ticket callbacks, the servername callback and the PSK callbacks (see SSL_CTX_set_psk_find_session_callback(3) and SSL_CTX_set_psk_server_callback(3)), including in (D)TLSv1.3. It is not yet available to the ClientHello callback (see SSL_CTX_set_client_hello_cb(3)) or to the DTLS cookie verification callback (see SSL_CTX_set_cookie_verify_cb(3)). The final eight bytes of the server_random carry the downgrade protection sentinel (RFC 8446 section 4.1.3) whose value depends on the selected protocol version, and the ClientHello callback is permitted to change the set of supported versions, so the version cannot be selected before that callback has run. The cookie verification callback runs before any per-connection resources are committed to a ClientHello whose source address has not yet been validated, so the server_random is deliberately not generated until it has succeeded. From within these two callbacks SSL_get_server_random() does not return the value of the current handshake but whatever the SSL object currently holds: all zeros if no server_random has been generated on it yet, the value of the previous handshake on this SSL object, or, while processing the second ClientHello after a HelloRetryRequest, the value generated for the first ClientHello. A fresh server_random is generated for each ClientHello that reaches the session lookup, so after a HelloRetryRequest only the one generated for the final ClientHello is sent to the client. A DTLS ClientHello that is answered with a HelloVerifyRequest does not reach that point, so no server_random is generated for it. When Encrypted ClientHello (ECH) is accepted, the final eight bytes of the server_random are replaced with the ECH acceptance confirmation while the ServerHello is being constructed, so a value observed from a callback before that point will differ in those bytes from the value sent to the client. On the client side the value is available once the ServerHello has been received.

These functions also work on QUIC connection SSL objects, where they return the values from the underlying TLS handshake, including from within TLS callbacks such as the server side PSK callbacks. On QUIC stream SSL objects they return 0. Like other functions reporting TLS handshake state, on a QUIC connection they read the handshake layer without taking the QUIC connection lock. In thread assisted mode (see OSSL_QUIC_client_thread_method(3)) the background thread may be progressing the handshake concurrently, so an application must only call these functions either once the handshake has completed, for example after SSL_connect(3) or SSL_do_handshake(3) has returned 1, or from within a callback invoked by the handshake itself. In both cases the values can no longer change concurrently.

RETURN VALUES¶

SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure.

For the other functions, if outlen is greater than 0 then these functions return the number of bytes actually copied, which will be less than or equal to outlen. If outlen is 0 then these functions return the maximum number of bytes they would copy -- that is, the length of the underlying field.

COPYRIGHT¶

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.