Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_client_random.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_GET_CLIENT_RANDOM 3SSL"
58 .TH SSL_GET_CLIENT_RANDOM 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_get_client_random,
65 SSL_get_server_random,
66 SSL_SESSION_get_master_key,
67 SSL_SESSION_set1_master_key
68 \&\- get internal TLS/SSL random values and get/set master key
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/ssl.h>
73 \&
74 \& size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
75 \& size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
76 \& size_t SSL_SESSION_get_master_key(const SSL_SESSION *session,
77 \& unsigned char *out, size_t outlen);
78 \& int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in,
79 \& size_t len);
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 \&\fBSSL_get_client_random()\fR extracts the random value sent from the client
84 to the server during the initial SSL/TLS handshake. It copies as many
85 bytes as it can of this value into the buffer provided in \fBout\fR,
86 which must have at least \fBoutlen\fR bytes available. It returns the
87 total number of bytes that were actually copied. If \fBoutlen\fR is
88 zero, \fBSSL_get_client_random()\fR copies nothing, and returns the
89 total size of the client_random value.
90 .PP
91 \&\fBSSL_get_server_random()\fR behaves the same, but extracts the random value
92 sent from the server to the client during the initial SSL/TLS handshake.
93 .PP
94 \&\fBSSL_SESSION_get_master_key()\fR behaves the same, but extracts the master
95 secret used to guarantee the security of the SSL/TLS session. This one
96 can be dangerous if misused; see NOTES below.
97 .PP
98 \&\fBSSL_SESSION_set1_master_key()\fR sets the master key value associated with the
99 SSL_SESSION \fBsess\fR. For example, this could be used to set up a session based
100 PSK (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). The master key of length
101 \&\fBlen\fR should be provided at \fBin\fR. The supplied master key is copied by the
102 function, so the caller is responsible for freeing and cleaning any memory
103 associated with \fBin\fR. The caller must ensure that the length of the key is
104 suitable for the ciphersuite associated with the SSL_SESSION.
105 .SH NOTES
106 .IX Header "NOTES"
107 You probably shouldn't use these functions.
108 .PP
109 These functions expose internal values from the TLS handshake, for
110 use in low-level protocols. You probably should not use them, unless
111 you are implementing something that needs access to the internal protocol
112 details.
113 .PP
114 Despite the names of \fBSSL_get_client_random()\fR and \fBSSL_get_server_random()\fR, they
115 ARE NOT random number generators. Instead, they return the mostly-random values that
116 were already generated and used in the TLS protocol. Using them
117 in place of \fBRAND_bytes()\fR would be grossly foolish.
118 .PP
119 The security of your TLS session depends on keeping the master key secret:
120 do not expose it, or any information about it, to anybody.
121 If you need to calculate another secret value that depends on the master
122 secret, you should probably use \fBSSL_export_keying_material()\fR instead, and
123 forget that you ever saw these functions.
124 .PP
125 In current versions of the TLS protocols, the length of client_random
126 (and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
127 other outlen arguments to the SSL_get_*\fB_random()\fR functions is provided
128 in case of the unlikely event that a future version or variant of TLS
129 uses some other length there.
130 .PP
131 Finally, though the "client_random" and "server_random" values are called
132 "random", many TLS implementations will generate four bytes of those
133 values based on their view of the current time.
134 .SH "RETURN VALUES"
135 .IX Header "RETURN VALUES"
136 \&\fBSSL_SESSION_set1_master_key()\fR returns 1 on success or 0 on failure.
137 .PP
138 For the other functions, if \fBoutlen\fR is greater than 0 then these functions
139 return the number of bytes actually copied, which will be less than or equal to
140 \&\fBoutlen\fR. If \fBoutlen\fR is 0 then these functions return the maximum number
141 of bytes they would copy \-\- that is, the length of the underlying field.
142 .SH "SEE ALSO"
143 .IX Header "SEE ALSO"
144 \&\fBssl\fR\|(7),
145 \&\fBRAND_bytes\fR\|(3),
146 \&\fBSSL_export_keying_material\fR\|(3),
147 \&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3)
148 .SH COPYRIGHT
149 .IX Header "COPYRIGHT"
150 Copyright 2015\-2017 The OpenSSL Project Authors. All Rights Reserved.
151 .PP
152 Licensed under the Apache License 2.0 (the "License"). You may not use
153 this file except in compliance with the License. You can obtain a copy
154 in the file LICENSE in the source distribution or at
155 <https://www.openssl.org/source/license.html>.