1=pod 2 3=head1 NAME 4 5SSL_get_client_random, 6SSL_get_server_random, 7SSL_SESSION_get_master_key, 8SSL_SESSION_set1_master_key 9- get internal TLS/SSL random values and get/set master key 10 11=head1 SYNOPSIS 12 13 #include <openssl/ssl.h> 14 15 size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen); 16 size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen); 17 size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, 18 unsigned char *out, size_t outlen); 19 int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in, 20 size_t len); 21 22=head1 DESCRIPTION 23 24SSL_get_client_random() extracts the random value sent from the client 25to the server during the initial SSL/TLS handshake. It copies as many 26bytes as it can of this value into the buffer provided in B<out>, 27which must have at least B<outlen> bytes available. It returns the 28total number of bytes that were actually copied. If B<outlen> is 29zero, SSL_get_client_random() copies nothing, and returns the 30total size of the client_random value. 31 32SSL_get_server_random() behaves the same, but extracts the random value 33sent from the server to the client during the initial SSL/TLS handshake. 34 35SSL_SESSION_get_master_key() behaves the same, but extracts the master 36secret used to guarantee the security of the SSL/TLS session. This one 37can be dangerous if misused; see NOTES below. 38 39SSL_SESSION_set1_master_key() sets the master key value associated with the 40SSL_SESSION B<sess>. For example, this could be used to set up a session based 41PSK (see L<SSL_CTX_set_psk_use_session_callback(3)>). The master key of length 42B<len> should be provided at B<in>. The supplied master key is copied by the 43function, so the caller is responsible for freeing and cleaning any memory 44associated with B<in>. The caller must ensure that the length of the key is 45suitable for the ciphersuite associated with the SSL_SESSION. 46 47=head1 NOTES 48 49You probably shouldn't use these functions. 50 51These functions expose internal values from the TLS handshake, for 52use in low-level protocols. You probably should not use them, unless 53you are implementing something that needs access to the internal protocol 54details. 55 56Despite the names of SSL_get_client_random() and SSL_get_server_random(), they 57ARE NOT random number generators. Instead, they return the mostly-random values that 58were already generated and used in the TLS protocol. Using them 59in place of RAND_bytes() would be grossly foolish. 60 61The security of your TLS session depends on keeping the master key secret: 62do not expose it, or any information about it, to anybody. 63If you need to calculate another secret value that depends on the master 64secret, you should probably use SSL_export_keying_material() instead, and 65forget that you ever saw these functions. 66 67In current versions of the TLS protocols, the length of client_random 68(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for 69other outlen arguments to the SSL_get_*_random() functions is provided 70in case of the unlikely event that a future version or variant of TLS 71uses some other length there. 72 73Finally, though the "client_random" and "server_random" values are called 74"random", many TLS implementations will generate four bytes of those 75values based on their view of the current time. 76 77 78=head1 RETURN VALUES 79 80SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure. 81 82For the other functions, if B<outlen> is greater than 0 then these functions 83return the number of bytes actually copied, which will be less than or equal to 84B<outlen>. If B<outlen> is 0 then these functions return the maximum number 85of bytes they would copy -- that is, the length of the underlying field. 86 87=head1 SEE ALSO 88 89L<ssl(7)>, 90L<RAND_bytes(3)>, 91L<SSL_export_keying_material(3)>, 92L<SSL_CTX_set_psk_use_session_callback(3)> 93 94 95=head1 COPYRIGHT 96 97Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. 98 99Licensed under the OpenSSL license (the "License"). You may not use 100this file except in compliance with the License. You can obtain a copy 101in the file LICENSE in the source distribution or at 102L<https://www.openssl.org/source/license.html>. 103 104=cut 105