SSL_CTX_USE_...IDENTITY_HINT(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

✨ SSL_CTX_USE_...IDENTITY_HINT ✨

okay bestie, so this is a page from the OpenSSL manual, section 3ossl — and it's literally the whole PSK identity hint situation. yes, the title has an ellipsis in it, no that's not me being lazy, that's how they wrote it 💅 let's get into it.

💖 NAME 💖

Okay so this one page covers a whole squad of functions, and you're gonna want all of them:

  • 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 what do they all do? they set the PSK identity hint to use. that's the whole vibe. periodt.

🎀 SYNOPSIS 🎀

#include <openssl/ssl.h>

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

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

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

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

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

like, look at all those signatures bestie, they ate 🔥

🦋 DESCRIPTION 🦋

💫 the TLSv1.3 era (find_session callback)

so if you're a server app and you wanna use TLSv1.3 PSKs, you set a callback using either SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback(), whichever one fits your situation. iykyk.

the callback gets:

  • a pointer to the SSL connection, in ssl
  • an identity in identity, with a length of identity_len

and your job as the callback girly is to identify an SSL_SESSION object that hands over the PSK details, and store it in *sess. that SSL_SESSION object needs, at minimum, to set:

  • the master key
  • the ciphersuite
  • the protocol version

for the deets, go see SSL_CTX_set_psk_use_session_callback(3). 👑

also, plot twist: it is also possible for the callback to succeed but not supply a PSK. in that case no PSK gets used, but the handshake keeps going. how do you do that? the callback returns successfully and makes sure *sess is NULL. simple as. 🫶

💫 identity hints (the TLSv1.2-and-below squad)

heads up: identity hints are not relevant for TLSv1.3. nope, not a thing there.

but a server app that does want 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 the same NUL-terminated PSK identity hint hint, but for the SSL connection object ssl.

oh and if hint is NULL? the current hint from ctx or ssl gets deleted. gone. bye. 💀

when the PSK identity hint is NULL, the server does not send the ServerKeyExchange message to the client. no cap.

💫 the server callback (TLSv1.2 and below)

a server app wanting PSKs for TLSv1.2 and below must provide a callback function. it gets called when the server receives the ClientKeyExchange message from the client. what's it for? two things:

  1. validate the received PSK identity
  2. fetch the pre-shared key used during the connection setup phase

you set this callback with SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). and the callback receives:

  • the connection, in parameter ssl
  • the NUL-terminated PSK identity sent by the client, in parameter identity
  • a buffer psk of length max_psk_len bytes where the pre-shared key is to be stored

that's the whole assignment bestie, go store that key 🌸

💫 mixing eras (yes, the TLSv1.2 callback works in 1.3)

the callback for use in TLSv1.2 will also work in TLSv1.3 — but ngl, it's recommended to use SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() for that purpose instead. glow-up advice ✨

so if TLSv1.3 has been negotiated, OpenSSL checks stuff in this exact order:

  1. first it checks whether a callback was set via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() — and it uses that in preference
  2. if no such callback is present, it checks whether a callback was set via SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback() and uses that one

in that second case, the handshake digest will default to SHA-256 for any returned PSK.

and important: 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 to that callback 😭

💫 one more little vibe

a connection established via a TLSv1.3 PSK will appear as if session resumption has occurred, so that SSL_session_reused(3) will return true. sneaky but iconic 💅

🌈 RETURN VALUES 🌈

SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return 1 on success, 0 otherwise. that's it, that's the binary.

return values from the TLSv1.2 and below server callback are interpreted like this:

  • 0 — PSK identity was not found. an "unknown_psk_identity" alert message will be sent and the connection setup fails. 💀
  • >0 — PSK identity was found and the server callback has provided the PSK successfully in parameter psk. the return value is the length of psk in bytes. it is an error to return a value greater than max_psk_len.
okay so about that >0 case: 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 the random data — so the connection will fail with decryption_error before it will be finished completely. like, it's a controlled fail, not a free pass, bestie 🙈

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

⭐ NOTES ⭐

good news: there are no known security issues with sharing the same PSK between TLSv1.2 (or below) and TLSv1.3. slay.

however, the RFC has this note of caution, and i'm quoting it exactly because it's important:

"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. that's the whole note. 🧚

🔥 SEE ALSO 🔥

go read those next, bestie, i believe in you 📚

💜 HISTORY 💜

SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback() were added in OpenSSL 1.1.1. a whole 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!! 🎀 this lil gem is from OpenSSL version 3.5.6, dated 2026-04-0, and it's the SSL_CTX_USE_...IDENTITY_HINT(3ossl) page one last time for the road. mwah, go set some PSK identity hints responsibly 💖✨🫶

📦 where this page comes from