SSL_GET_CLIENT_RANDOM(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 SSL_GET_CLIENT_RANDOM 💖

okay bestie, so this is a page from the OpenSSL manual, section 3SSL — welcome to the group chat 🫶

✨ NAME ✨

SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key, SSL_SESSION_set1_master_key — grab the internal TLS/SSL random values, and get/set the master key 👑

🌸 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);

💫 DESCRIPTION 💫

SSL_get_client_random() pulls out the random value that the client sent over to the server during that very first SSL/TLS handshake 🌈. It copies as many bytes of that value as it possibly can into the buffer you handed it in out, and that buffer has to have at least outlen bytes available, no negotiating 💅. It hands back the total number of bytes it actually copied. Little fun fact: if outlen is zero, it copies literally nothing and just returns the total size of the client_random value. iconic behavior, honestly ✨

SSL_get_server_random() does the exact same thing, except it's the random value that the server sent to the client during the initial SSL/TLS handshake 🦋.

SSL_SESSION_get_master_key() also behaves the same way, but it's pulling out the master secret — the thing that guarantees the security of the SSL/TLS session 🔐. And like… this one can be dangerous if you misuse it. Go read NOTES, I'm serious 😭.

SSL_SESSION_set1_master_key() sets the master key value that's associated with the SSL_SESSION called sess 🌟. So for example, you could use this to set up a session based PSK (peep SSL_CTX_set_psk_use_session_callback(3)). You pass the master key of length len in at in. The function copies the master key you supply, so you, the caller, are the one responsible for freeing and cleaning up any memory associated with in 🧹. And you also have to make sure the length of the key is suitable for the ciphersuite that's associated with the SSL_SESSION, no cap.

🔥 NOTES 🔥

okay so real talk: you probably shouldn't use these functions. 🙈

They expose internal values straight out of the TLS handshake, for low-level protocols. And like, you probably should not be using them, unless you're implementing something that genuinely needs access to the internal protocol details. iykyk.

And despite what the names SSL_get_client_random() and SSL_get_server_random() are giving… they ARE NOT random number generators 💀. They just return the mostly-random values that were already generated and used inside the TLS protocol. Using them in place of RAND_bytes() would be grossly foolish. do not do that bestie.

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

In current versions of the TLS protocols, the length of client_random (and server_random too) is always SSL3_RANDOM_SIZE bytes ⭐. Support for other outlen arguments to the SSL_get_*_random() functions exists just in case — in the unlikely event that some future version or variant of TLS uses a different length there. Future-proofing, slay 🎀.

And finally, even though the client_random and server_random values are literally called "random"… many TLS implementations will generate four bytes of those values based on their view of the current time ⏰. yep. that's the vibe.

🌈 RETURN VALUES 🌈

  • SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure ✨.
  • For the other functions: if outlen is greater than 0, they return the number of bytes actually copied, which will be less than or equal to outlen 💅. If outlen is 0, they return the maximum number of bytes they would copy — that is, the length of the underlying field 🦋.

👑 SEE ALSO 👑

ssl(7), RAND_bytes(3), SSL_export_keying_material(3), SSL_CTX_set_psk_use_session_callback(3) 🌸

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 <https://www.openssl.org/source/license.html>.

and that's the whole page bestie, mwah 💋 this was version 4.0.3, dated 2026-09-29, from the SSL_GET_CLIENT_RANDOM(3SSL) era — go forth and not misuse your master keys 🫶🎀

📦 where this page comes from