nbd_set_tls_psk_file(3)

💖 nbd_set_tls_psk_file — from the LIBNBD manual, bestie edition 💖

Okay so picture this: it's nbd_set_tls_psk_file(3), it lives in the LIBNBD section of the manual, and it is literally here to hand your TLS connection its Pre-Shared Key (PSK) file. That's the whole vibe. Let's get into it 🫶

---

✨ NAME ✨

nbd_set_tls_psk_file — set the TLS Pre-Shared Keys (PSK) filename. That's it, that's the icon.

---

🌸 SYNOPSIS 🌸

#include <libnbd.h>

int nbd_set_tls_psk_file (
      struct nbd_handle *h, const char *filename
    );

---

🦋 DESCRIPTION 🦋

So what this does: it sets the TLS Pre-Shared Keys (PSK) filename. Slay. You use this when you're trying to authenticate to the server using a pre-shared key. And listen — there is no default, so if you don't set this, then PSK authentication straight up cannot be used to connect to the server. No file, no entry, no connection. Periodt 💅

Also, this function may be called regardless of whether TLS is supported — but it will have no effect unless nbd_set_tls(3) is also used to request or require TLS. So like, calling it alone is giving "decorative". Cute but useless without the other one ✨

---

🎀 RETURN VALUE 🎀

If the call is successful the function returns 0. Iconic. Immaculate. Zero.

---

🔥 ERRORS 🔥

On error -1 is returned 😭

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

Also important: the following parameters must not be NULL: "h", "filename". For more information see "Non-NULL parameters" in libnbd(3). Don't be out here passing NULLs, bestie, I'm begging 🙈

---

👑 HANDLE STATE 👑

nbd_set_tls_psk_file can be called when the handle is in the following state:

• Handle created, before connecting — ✅ allowed
• Connecting — ❌ error
• Connecting & handshaking (opt_mode) — ❌ error
• Connected to the server — ❌ error
• Connection shut down — ❌ error
• Handle dead — ❌ error

So basically: set it up before you connect. Once you're connecting, the door is closed, the vibe check has been failed, it's over 💀

---

🌈 VERSION 🌈

This function first appeared in libnbd 1.0.

If you need to test if this function is available at compile time, check if the following macro is defined:

#define LIBNBD_HAVE_NBD_SET_TLS_PSK_FILE 1

---

⭐ EXAMPLE ⭐

This example is also available as examples/encryption.c in the libnbd source code.

/* An example showing how to connect to a server which is
 * using TLS encryption.
 *
 * This requires nbdkit, and psktool from gnutls.
 *
 * Both libnbd and nbdkit support TLS-PSK which is a
 * simpler-to-deploy form of encryption.  (Of course
 * certificate-based encryption is also supported, but
 * it’s harder to make a self-contained example).
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <libnbd.h>

#define TMPDIR "/tmp/XXXXXX"
#define KEYS "keys.psk"
#define USERNAME "alice"

static char dir[] = TMPDIR;
static char keys[] = TMPDIR "/" KEYS;
static char cmd[] =
  "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;

/* Remove the temporary keys file when the program
 * exits.
 */
static void
cleanup_keys (void)
{
  unlink (keys);
  rmdir (dir);
}

/* Create the temporary keys file to share with the
 * server.
 */
static void
create_keys (void)
{
  size_t i;

  if (mkdtemp (dir) == NULL) {
    perror ("mkdtemp");
    exit (EXIT_FAILURE);
  }
  i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
  memcpy (&cmd[i], dir, strlen (TMPDIR));
  memcpy (keys, dir, strlen (TMPDIR));

  if (system (cmd) != 0) {
    fprintf (stderr, "psktool command failed\n");
    exit (EXIT_FAILURE);
  }

  atexit (cleanup_keys);
}

int
main (int argc, char *argv[])
{
  struct nbd_handle *nbd;
  char buf[512];

  create_keys ();

  /* Create the libnbd handle. */
  nbd = nbd_create ();
  if (nbd == NULL) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Enable TLS in the client. */
  if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Enable TLS-PSK and pass the keys filename. */
  if (nbd_set_tls_psk_file (nbd, keys) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Set the local username for authentication. */
  if (nbd_set_tls_username (nbd, USERNAME) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Run nbdkit as a subprocess, enabling and requiring
   * TLS-PSK encryption.
   */
  char *args[] = {
    "nbdkit", "-s", "--exit-with-parent",
    "--tls", "require", "--tls-psk", keys,
    "pattern", "size=1M", NULL
  };
  if (nbd_connect_command (nbd, args) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Read the first sector. */
  if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* TLS connections must be shut down. */
  if (nbd_shutdown (nbd, 0) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Close the libnbd handle. */
  nbd_close (nbd);

  exit (EXIT_SUCCESS);
}

Note the /* TLS connections must be shut down. */ comment up there — that's not a suggestion, bestie, that's a rule 🚨

---

🧚 SEE ALSO 🧚

nbd_create(3), nbd_set_tls(3), libnbd(3).

---

💜 AUTHORS 💜

Eric Blake

Richard W.M. Jones

---

🍓 COPYRIGHT 🍓

Copyright Red Hat

---

💅 LICENSE 💅

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

and that's the whole page, bestie 🫶 this one's brought to you by libnbd-1.25.8, dated 2026-10-13, and it's literally called nbd_set_tls_psk_file(3) in case you forgot. go set that PSK file. slay.