[thirdparty/openssl.git] / doc / man3 / SSL_get_client_random.pod

=pod

=head1 NAME

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

=head1 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);
 int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in,
                                 size_t len);

=head1 DESCRIPTION

SSL_get_client_random() extracts the random value sent from the client
to the server during the initial SSL/TLS handshake.  It copies as many
bytes as it can of this value into the buffer provided in B<out>,
which must have at least B<outlen> bytes available. It returns the
total number of bytes that were actually copied.  If B<outlen> is
zero, SSL_get_client_random() copies nothing, and returns the
total size of the client_random value.

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

SSL_SESSION_get_master_key() behaves the same, but extracts the master
secret used to guarantee the security of the SSL/TLS session.  This one
can be dangerous if misused; see NOTES below.

SSL_SESSION_set1_master_key() sets the master key value associated with the
SSL_SESSION B<sess>. For example, this could be used to set up a session based
PSK (see L<SSL_CTX_set_psk_use_session_callback(3)>). The master key of length
B<len> should be provided at B<in>. The supplied master key is copied by the
function, so the caller is responsible for freeing and cleaning any memory
associated with B<in>. The caller must ensure that the length of the key is
suitable for the ciphersuite associated with the SSL_SESSION.

=head1 NOTES

You probably shouldn't use these functions.

These functions expose internal values from the TLS handshake, for
use in low-level protocols.  You probably should not use them, unless
you are implementing something that needs 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.  Using them
in place of RAND_bytes() would be grossly foolish.

The security of your TLS session depends on keeping the master key secret:
do not expose it, or any information about it, to anybody.
If you need to calculate another secret value that depends on the master
secret, you should probably use SSL_export_keying_material() instead, and
forget that you ever saw these functions.

In current versions of the TLS protocols, the length of client_random
(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
other outlen arguments to the SSL_get_*_random() functions is provided
in case of the unlikely event that a future version or variant of TLS
uses some other length there.

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


=head1 RETURN VALUES

SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure.

For the other functions, if B<outlen> is greater than 0 then these functions
return the number of bytes actually copied, which will be less than or equal to
B<outlen>. If B<outlen> is 0 then these functions return the maximum number
of bytes they would copy -- that is, the length of the underlying field.

=head1 SEE ALSO

L<ssl(7)>,
L<RAND_bytes(3)>,
L<SSL_export_keying_material(3)>,
L<SSL_CTX_set_psk_use_session_callback(3)>


=head1 COPYRIGHT

Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

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