SSL_CTX_USE_...IDENTITY_HINT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 SSL_CTX_USE_...IDENTITY_HINT 💖

okay bestie, so this is a page from the OpenSSL manual (third section, 3ossl, iykyk) and it's all about PSK identity hints and the server-side callbacks that make pre-shared keys work. it's giving "niche but essential", fr fr. let's get into it 🫶

✨ NAME ✨

so here's the whole squad of things this page covers, no cap:

  • SSL_psk_server_cb_func
  • SSL_psk_find_session_cb_func
  • SSL_CTX_use_psk_identity_hint
  • SSL_use_psk_identity_hint
  • SSL_CTX_set_psk_server_callback
  • SSL_set_psk_server_callback
  • SSL_CTX_set_psk_find_session_callback
  • SSL_set_psk_find_session_callback

…and their collective mission statement is literally just: set PSK identity hint to use. periodt 💅

🌈 SYNOPSIS 🌈

grab the header first, always:

#include <openssl/ssl.h>

then here's the callback type for TLSv1.3 style session-finding, she's the main character:

typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl,
                                            const unsigned char *identity,
                                            size_t identity_len,
                                            SSL_SESSION **sess);

and the setters that attach her to a context or a connection:

void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
                                           SSL_psk_find_session_cb_func cb);
void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);

now the classic TLSv1.2-and-below server callback type, the OG:

typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
                                               const char *identity,
                                               unsigned char *psk,
                                               unsigned int max_psk_len);

the identity hint setters:

int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);

and the server callback setters, attached either way:

void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb);
void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb);

🌸 DESCRIPTION 🌸

okay so listen. a server app that wants to use TLSv1.3 PSKs should set a callback — using SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback(), whichever one fits your vibe. 🦋

that callback function gets a pointer to the SSL connection in ssl, plus an identity in identity with length identity_len. her job? identify an SSL_SESSION object that carries the PSK details, and stash it in *sess. and bestie, that SSL_SESSION object has to set at minimum the master key, the ciphersuite, and the protocol version. for the full tea, go read SSL_CTX_set_psk_use_session_callback(3).

plot twist tho: the callback can also succeed without actually supplying a PSK. in that case no PSK gets used, but the handshake keeps going anyway. how? the callback returns successfully and makes sure *sess is NULL. iconic, honestly.

now — identity hints are not relevant for TLSv1.3, just so we're clear. 💀 but a server app that wants PSK ciphersuites for TLSv1.2 and below can call SSL_CTX_use_psk_identity_hint() to set the given NUL-terminated PSK identity hint hint for the SSL context object ctx. and SSL_use_psk_identity_hint() sets that same NUL-terminated PSK identity hint hint for the SSL connection object ssl. if hint is NULL, the current hint from ctx or ssl gets deleted. gone. poof. 🎀

and when the PSK identity hint is NULL? then the server does not send the ServerKeyExchange message to the client. that's the rule, no cap.

so, a server app wanting PSKs for TLSv1.2 and below must provide a callback function, and it gets called when the server receives the ClientKeyExchange message from the client. what's the point of it? two things: validate the received PSK identity, and fetch the pre-shared key used during the connection setup phase. you set that callback with SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). the callback gets the connection in parameter ssl, the NUL-terminated PSK identity sent by the client in parameter identity, and a buffer psk of length max_psk_len bytes where the pre-shared key is supposed to go. 🍓

here's the gossip tho: the callback for TLSv1.2 will also work in TLSv1.3 — but it's <highkey>recommended</highkey> that you use SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() instead for that purpose. and if TLSv1.3 has been negotiated, OpenSSL will first check whether a callback was set via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() and use that one in preference. if there's no such callback present, it checks whether one was set via SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback() and uses that instead. in <em>that</em> case, the handshake digest defaults to SHA-256 for any returned PSK. and heads up: TLSv1.3 early data exchanges are possible in PSK connections only with the SSL_psk_find_session_cb_func callback — they are not possible with the SSL_psk_server_cb_func callback. sorry bestie, that's just how it is. 😭

one more thing: a connection established via a TLSv1.3 PSK will appear as if session resumption has occurred, so SSL_session_reused(3) will return true. sneaky but slay. 👑

💜 RETURN VALUES 💜

SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return 1 on success, 0 otherwise. simple as.

return values from the TLSv1.2 and below server callback get read like this:

  • 0 — the PSK identity was not found. an "unknown_psk_identity" alert message will be sent and the connection setup fails. 💀
  • >0 — the PSK identity was found and the server callback successfully provided the PSK in parameter psk. the return value is the length of psk in bytes. and listen — it is an error to return a value greater than max_psk_len. don't do it. 🙈
    • now, if the PSK identity was not found but the callback instructs the protocol to continue anyway, the callback must provide some random data to psk and return the length of that random data — so the connection will fail with decryption_error before it finishes completely. chaotic but intentional.
  • and the SSL_psk_find_session_cb_func callback should return 1 on success or 0 on failure. in the event of failure, the connection setup fails.

🧚 NOTES 🧚

good news: there are no known security issues with sharing the same PSK between TLSv1.2 (or below) and TLSv1.3. however, the RFC has this little note of caution, and I'm quoting it exactly because it matters:

"While there is no known way in which the same PSK might produce related output in both versions, only limited analysis has been done. Implementations can ensure safety from cross-protocol related output by not reusing PSKs between TLS 1.3 and TLS 1.2."

so like… be careful, bestie. 🌸

🎀 SEE ALSO 🎀

go read these next, they're all connected:

⭐ HISTORY ⭐

SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback() were added in OpenSSL 1.1.1. glow-up era. ✨

Copyright 2006-2020 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 💖 this was OpenSSL 3.5.9, dated 2026-09-2, and it's the SSL_CTX_USE_...IDENTITY_HINT(3ossl) manual. go forth and PSK responsibly 🫶🌸🎀

📦 where this page comes from