SSL_GET_CLIENT_RANDOM(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_GET_CLIENT_RANDOM — OpenSSL manual, page SSL_GET_CLIENT_RANDOM(3ossl)

okay so bestie, this is one of those pages in the OpenSSL manual (section 3ossl) that's like... technically about grabbing the internal handshake random values and the master key. Buckle up, it comes with a big warning label 🎀

✨ NAME ✨

SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key, SSL_SESSION_set1_master_key — like, literally here to get the internal TLS/SSL random values and to get/set the master key. That's the whole gig 🫶

🦋 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 🌸

the getters (client_random, server_random) ✨

SSL_get_client_random() pulls out the random value that the client sent to the server during the initial SSL/TLS handshake. It copies as many bytes of that value as it can into the buffer you hand it in out — and out better have at least outlen bytes available, no cap. It returns the total number of bytes that were actually copied. And if outlen is zero? It copies nothing and just returns the total size of the client_random value. Lowkey a size-query feature, slay 💅

SSL_get_server_random() is the same vibe, except it extracts the random value sent from the server to the client during the initial SSL/TLS handshake. Mirror image, iconic.

the master key ones 👑

SSL_SESSION_get_master_key() behaves the same way, but it extracts the master secret used to guarantee the security of the SSL/TLS session. ⚠️ Heads up bestie: this one can be dangerous if misused — see NOTES below, fr fr.

SSL_SESSION_set1_master_key() sets the master key value associated with the SSL_SESSION sess. For example (and I'm just quoting the lore here), this could be used to set up a session based PSK — see SSL_CTX_set_psk_use_session_callback(3). The master key of length len should be provided at in. The supplied master key is copied by the function, so you (the caller) are responsible for freeing and cleaning any memory associated with in. And the caller must ensure that the length of the key is suitable for the ciphersuite associated with the SSL_SESSION. Like, get the length right or it's not giving what it needs to give 🙈

💀 NOTES 💀

You probably shouldn't use these functions. That's it. That's the note. (jk there's more, keep reading.)

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. Niche behavior only, iykyk.

Despite the names of SSL_get_client_random() and SSL_get_server_random(), they ARE NOT random number generators. The caps are doing the heavy lifting there. 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. Like, genuinely embarrassing. Don't. 😭

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 your group chat, not your situationship, nobody. 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. Memory wiped. Never happened 💜

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. Future-proofing, we love to see it ⭐

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. Which is... a choice. But it's their choice 🕰️

🌈 RETURN VALUES 🌈

  • SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure. Simple, binary, no drama.
  • 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, these functions return the maximum number of bytes they would copy — that is, the length of the underlying field. Chef's kiss preview mode 👑

🎀 SEE ALSO 🎀

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

Go read those too, bestie, cross-referencing is main character energy 💖

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>.

okay and that's the whole page!! this was version 3.5.0, dated 2026-09-25, filed under SSL_GET_CLIENT_RANDOM(3ossl) in the OpenSSL manual. mwah, go use these responsibly (or, per the NOTES, don't) 💅✨🍓

📦 where this page comes from