e31d3f0a282f38c1cb64d22f99afbb972cfa701a
[openssl.git] / doc / ssl / SSL_get_client_random.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key
6
7 =head1 SYNOPSIS
8
9  #include <openssl/ssl.h>
10
11  int SSL_get_client_random(const SSL *ssl, unsigned char *out, int outlen);
12  int SSL_get_server_random(const SSL *ssl, unsigned char *out, int outlen);
13  int SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, int outlen);
14
15 =head1 DESCRIPTION
16
17 SSL_get_client_random() extracts the random value sent from the client
18 to the server during the initial SSL/TLS handshake.  It copies this
19 value into the buffer provided in B<out>, which must have at least
20 B<outlen> bytes available. It returns the total number of bytes that were
21 actually copied.
22 If B<outlen> is less than zero, SSL_get_client_random() copies nothing, and
23 returns the total size of the client_random value.
24
25 SSL_get_server_random() behaves the same, but extracts the random value
26 sent from the server to the client during the initial SSL/TLS handshake.
27
28 SSL_SESSION_get_master_key() behaves the same, but extracts the master
29 secret used to guarantee the security of the SSL/TLS session.  This one
30 can be dangerous if misused; see NOTES below.
31
32
33 =head1 NOTES
34
35 You probably shouldn't use these functions.
36
37 These functions expose internal values from the TLS handshake, for
38 use in low-level protocols.  You probably should not use them, unless
39 you are implementing something that needs access to the internal protocol
40 details.
41
42 Despite the names of SSL_get_client_random() and SSL_get_server_random(), they
43 ARE NOT random number generators.  Instead, they return the mostly-random values that
44 were already generated and used in the TLS protoccol.  Using them
45 in place of RAND_bytes() would be grossly foolish.
46
47 The security of your TLS session depends on keeping the master key secret:
48 do not expose it, or any information about it, to anybody.
49 If you need to calculate another secret value that depends on the master
50 secret, you should probably use SSL_export_keying_material() instead, and
51 forget that you ever saw these functions.
52
53 Finally, though the "client_random" and "server_random" values are called
54 "random", many TLS implementations will generate four bytes of those
55 values based on their view of the current time.
56
57
58 =head1 RETURN VALUES
59
60 If B<outlen> is at least 0, these functions return the number of bytes
61 actually copied, which will be less than or equal to B<outlen>.
62
63 If B<outlen> is less than 0, these functions return the maximum number
64 of bytes they would copy--that is, the length of the underlying field.
65
66 =head1 SEE ALSO
67
68 L<ssl(3)|ssl(3)>,
69 L<RAND_bytes(3)|RAND_bytes(3)>,
70 L<SSL_export_keying_material(3)|SSL_export_keying_material(3)>
71
72
73 =cut