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