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.