gnutls_psk_set...tials_function3(3)

📦
version 3.8.13 · 5 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, ubuntu stonking

✨ gnutls_psk_set_server_credentials_function3 ✨

okay bestie, gather round, because we're doing gnutls internals today and honestly? it's giving ✨server-side PSK vibes✨. this page lives in the gnutls manual, and it's literally just one lil API function that you're about to become obsessed with. 💖

🌸 NAME 🌸

gnutls_psk_set_server_credentials_function3 — an API function, no cap. that's the whole name. she's long, she's specific, she ate. 👑

🎀 SYNOPSIS 🎀

first things first, you gotta bring in the header:

#include <gnutls/gnutls.h>

and here's the signature, character for character, don't you dare touch it:

void
gnutls_psk_set_server_credentials_function3(gnutls_psk_server_credentials_t
cred, gnutls_psk_server_credentials_function3 func);

yes she's a void girlie. she returns nothing. she just does things. 💅

🦋 ARGUMENTS 🦋

two args, both important, let's go:

  • gnutls_psk_server_credentials_t cred — this is a gnutls_psk_server_credentials_t type. your creds. your whole identity bestie.
  • gnutls_psk_server_credentials_function3 func — this is the callback function. the actual little worker bee that goes and fetches stuff when the handshake asks nicely. 🐝

💜 DESCRIPTION 💜

so what does this actually do? this function lets you set a callback that retrieves the user's PSK credentials. that's the tea. ☕

the callback's function form is, exactly:

int
(*callback)(gnutls_session_t, const gnutls_datum_t* username,
gnutls_datum_t* key, gnutls_psk_key_flags *flags);

now — this callback has the same semantics as gnutls_psk_set_server_credentials_function2(), except it also returns flags associated with the key. that's the glow-up between v2 and v3, and we love an upgrade arc. 🌈

also, the callback may import external PSK using the method described in RFC 9258 by using gnutls_psk_format_imported_identity(). iykyk.

here's the important part, don't skip it:

  • username contains the actual username.
  • key must be filled in using gnutls_malloc(). must. not malloc, not vibes, gnutls_malloc(). 🙈

and if the callback returns a negative number, gnutls will assume the username does not exist. like, ghosted. 👻

heads up: the callback function will only be called once per handshake. one shot, one opportunity. 🎤

return values? the callback should return 0 on success, while -1 indicates an error. that's it. that's the contract. periodt. ✨

😭 REPORTING BUGS 😭

found a bug? spill it, but professionally:

Copyright © 2001-2023 Free Software Foundation, Inc., and others.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

🌟 SEE ALSO 🌟

The full documentation for gnutls is maintained as a Texinfo manual. If the /usr/share/doc/gnutls/ directory does not contain the HTML form visit

https://www.gnutls.org/manual/

and that's the whole page, bestie. this was shipped as part of gnutls 3.8.13 — go forth, set your callback, fill that key with gnutls_malloc(), and slay your handshake. mwah. 💋🎀🦋

📦 where this page comes from