1SSL_GET_CLIENT_RANDOM(3)            OpenSSL           SSL_GET_CLIENT_RANDOM(3)
2
3
4

NAME

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

SYNOPSIS

11        #include <openssl/ssl.h>
12
13        size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
14        size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
15        size_t SSL_SESSION_get_master_key(const SSL_SESSION *session,
16                                          unsigned char *out, size_t outlen);
17        int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in,
18                                        size_t len);
19

DESCRIPTION

21       SSL_get_client_random() extracts the random value sent from the client
22       to the server during the initial SSL/TLS handshake.  It copies as many
23       bytes as it can of this value into the buffer provided in out, which
24       must have at least outlen bytes available. It returns the total number
25       of bytes that were actually copied.  If outlen is zero,
26       SSL_get_client_random() copies nothing, and returns the total size of
27       the client_random value.
28
29       SSL_get_server_random() behaves the same, but extracts the random value
30       sent from the server to the client during the initial SSL/TLS
31       handshake.
32
33       SSL_SESSION_get_master_key() behaves the same, but extracts the master
34       secret used to guarantee the security of the SSL/TLS session.  This one
35       can be dangerous if misused; see NOTES below.
36
37       SSL_SESSION_set1_master_key() sets the master key value associated with
38       the SSL_SESSION sess. For example, this could be used to set up a
39       session based PSK (see SSL_CTX_set_psk_use_session_callback(3)). The
40       master key of length len should be provided at in. The supplied master
41       key is copied by the function, so the caller is responsible for freeing
42       and cleaning any memory associated with in. The caller must ensure that
43       the length of the key is suitable for the ciphersuite associated with
44       the SSL_SESSION.
45

NOTES

47       You probably shouldn't use these functions.
48
49       These functions expose internal values from the TLS handshake, for use
50       in low-level protocols.  You probably should not use them, unless you
51       are implementing something that needs access to the internal protocol
52       details.
53
54       Despite the names of SSL_get_client_random() and
55       SSL_get_server_random(), they ARE NOT random number generators.
56       Instead, they return the mostly-random values that were already
57       generated and used in the TLS protocol.  Using them in place of
58       RAND_bytes() would be grossly foolish.
59
60       The security of your TLS session depends on keeping the master key
61       secret: do not expose it, or any information about it, to anybody.  If
62       you need to calculate another secret value that depends on the master
63       secret, you should probably use SSL_export_keying_material() instead,
64       and forget that you ever saw these functions.
65
66       In current versions of the TLS protocols, the length of client_random
67       (and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
68       other outlen arguments to the SSL_get_*_random() functions is provided
69       in case of the unlikely event that a future version or variant of TLS
70       uses some other length there.
71
72       Finally, though the "client_random" and "server_random" values are
73       called "random", many TLS implementations will generate four bytes of
74       those values based on their view of the current time.
75

RETURN VALUES

77       SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure.
78
79       For the other functions, if outlen is greater than 0 then these
80       functions return the number of bytes actually copied, which will be
81       less than or equal to outlen. If outlen is 0 then these functions
82       return the maximum number of bytes they would copy -- that is, the
83       length of the underlying field.
84

SEE ALSO

86       ssl(7), RAND_bytes(3), SSL_export_keying_material(3),
87       SSL_CTX_set_psk_use_session_callback(3)
88

90       Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
91
92       Licensed under the OpenSSL license (the "License").  You may not use
93       this file except in compliance with the License.  You can obtain a copy
94       in the file LICENSE in the source distribution or at
95       <https://www.openssl.org/source/license.html>.
96
97
98
991.1.1i                            2021-07-22          SSL_GET_CLIENT_RANDOM(3)
Impressum