SSL_CTX_USE_PSK_IDENTITY_HINT(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💅 SSL_CTX_USE_PSK_IDENTITY_HINT — the OpenSSL manual, but make it make sense

okay bestie, sit down, hydrate, and let me tell you about the OpenSSL page for SSL_CTX_USE_PSK_IDENTITY_HINT(3SSL) — yes that's a lot of capitals, no you don't have to memorise them all at once, we're doing this together 🫶

✨ NAME ✨

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 — the whole girl squad that sets the PSK identity hint to use 💖

✨ SYNOPSIS ✨

like, here's the vibe, copy-paste approved:

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

🌸 DESCRIPTION 🌸

so, if you're a server application and you wanna use TLSv1.3 PSKs? you gotta set a callback, bestie — either with SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback(), whichever one fits your situation. pick your fighter 💅

🦋 the find-session callback

your callback function gets handed a pointer to the SSL connection in ssl, plus an identity in identity of length identity_len. what's it supposed to do? it should identify an SSL_SESSION object that has the PSK details, and store that in *sess. that SSL_SESSION object needs, at minimum, to set the master key, the ciphersuite and the protocol version. for the full tea, go read SSL_CTX_set_psk_use_session_callback(3) 👑

and here's a lil plot twist — the callback is allowed to succeed and still not give you a PSK. in that case, no PSK gets used but the handshake keeps going anyway. how? just return successfully and make sure *sess is NULL. iconic behaviour, honestly.

🎀 identity hints (TLSv1.2 and below energy)

ngl, identity hints are not relevant for TLSv1.3. periodt. but if you're a server application that wants PSK ciphersuites for TLSv1.2 and below, you can call SSL_CTX_use_psk_identity_hint() to set the given NUL-terminated PSK identity hint hint for the SSL context object ctx.

SSL_use_psk_identity_hint() does the same thing but for the SSL connection object ssl — it sets the given NUL-terminated PSK identity hint hint. and if hint is NULL? the current hint from ctx or ssl gets deleted. poof. gone. 💨

so like, when the PSK identity hint is NULL, the server does not send the ServerKeyExchange message to the client. that's just what it is.

🌈 the server callback (for the TLSv1.2-and-below girlies)

a server application that wishes to use 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 the point of it? to validate the received PSK identity and to fetch the pre-shared key used during the connection setup phase. set it with SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback().

your callback function receives:

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

like, that's the whole assignment. very demure, very mindful.

💜 the crossover episode: TLSv1.2 callback, TLSv1.3 world

the callback for use in TLSv1.2 will also work in TLSv1.3 — but bestie, it is recommended to use SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() for that instead. upgrade your life ✨

here's the order of operations if TLSv1.3 has been negotiated. OpenSSL:

  1. first checks whether a callback has been set via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() — and it will use that in preference.
  2. if no such callback is present, it then checks whether a callback has been 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. also!! 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. so if you wanted early data and you picked the second callback, that's a you problem, sorry 😭

and a fun fact: 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. love that for us. 🙈

⭐ RETURN VALUES ⭐

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

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 the 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.
and listen closely: 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 will be finished completely. do not skip this step, I'm begging 🫶

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

🧚 NOTES 🧚

there are no known security issues with sharing the same PSK between TLSv1.2 (or below) and TLSv1.3. lowkey a relief!

buuut 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, you can, but the RFC is side-eyeing you a little. your call, bestie. 👀

🔥 SEE ALSO 🔥

👑 HISTORY 👑

SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback() were added in OpenSSL 1.1.1. the origin story, if you will. ⭐

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 — 💖 4.0.3, dated 2026-09-2 💖 — go forth and configure your PSKs, you absolute icon, mwah 🎀✨

📦 where this page comes from