NAME

SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key — get internal TLS handshake random values and 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);

DESCRIPTION

SSL_get_client_random() extracts the random value that was sent from the client to the server during the initial TLS handshake. It copies at most outlen bytes of this value into the buffer out. If outlen is zero, nothing is copied.

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

SSL_SESSION_get_master_key() behaves the same, but extracts the master secret used to guarantee the security of the TLS session. The security of the TLS session depends on keeping the master key secret: do not expose it, or any information about it, to anybody. To calculate another secret value that depends on the master secret, use SSL_export_keying_material(3) instead.

All these functions expose internal values from the TLS handshake, for use in low-level protocols. Avoid using them unless implementing a feature that requires 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.

In current versions of the TLS protocols, the length of client_random and server_random is always SSL3_RANDOM_SIZE bytes. Support for other outlen arguments is provided for the unlikely event that a future version or variant of TLS uses some other length.

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

RETURN VALUES

If outlen is greater than 0, these functions return the number of bytes actually copied, which is less than or equal to outlen. If outlen is 0, these functions return the maximum number of bytes they would copy — that is, the length of the underlying field.

SEE ALSO

ssl(3), SSL_export_keying_material(3), SSL_SESSION_get_id(3), SSL_SESSION_get_time(3), SSL_SESSION_new(3)

HISTORY

These functions first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3.