1nbd_set_tls_psk_file(3) LIBNBD nbd_set_tls_psk_file(3)
2
6 nbd_set_tls_psk_file - set the TLS Pre-Shared Keys (PSK) filename
7
9 #include <libnbd.h>
10 int nbd_set_tls_psk_file (struct nbd_handle *h,
12 const char *filename);
13
15 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
16 authenticate to the server using with a pre-shared key. There is no
17 default so if this is not set then PSK authentication cannot be used to
18 connect to the server.
19 This function may be called regardless of whether TLS is supported, but
21 will have no effect unless nbd_set_tls(3) is also used to request or
22 require TLS.
23
25 If the call is successful the function returns 0.
26
28 On error "-1" is returned.
29 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
31 of the error.
32 The following parameters must not be NULL: "h", "filename". For more
34 information see "Non-NULL parameters" in libnbd(3).
35
37 The handle must be newly created, otherwise this call will return an
38 error.
39
41 This function first appeared in libnbd 1.0.
42 If you need to test if this function is available at compile time check
44 if the following macro is defined:
45 #define LIBNBD_HAVE_NBD_SET_TLS_PSK_FILE 1
47
49 This example is also available as examples/encryption.c in the libnbd
50 source code.
51 /* An example showing how to connect to a server which is
53 * using TLS encryption.
54 *
55 * This requires nbdkit, and psktool from gnutls.
56 *
57 * Both libnbd and nbdkit support TLS-PSK which is a
58 * simpler-to-deploy form of encryption. (Of course
59 * certificate-based encryption is also supported, but
60 * it’s harder to make a self-contained example).
61 */
62 #include <stdio.h>
64 #include <stdlib.h>
65 #include <string.h>
66 #include <unistd.h>
67 #include <libnbd.h>
69 #define TMPDIR "/tmp/XXXXXX"
71 #define KEYS "keys.psk"
72 #define USERNAME "alice"
73 static char dir[] = TMPDIR;
75 static char keys[] = TMPDIR "/" KEYS;
76 static char cmd[] =
77 "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
78 /* Remove the temporary keys file when the program
80 * exits.
81 */
82 static void
83 cleanup_keys (void)
84 {
85 unlink (keys);
86 rmdir (dir);
87 }
88 /* Create the temporary keys file to share with the
90 * server.
91 */
92 static void
93 create_keys (void)
94 {
95 size_t i;
96 if (mkdtemp (dir) == NULL) {
98 perror ("mkdtemp");
99 exit (EXIT_FAILURE);
100 }
101 i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
102 memcpy (&cmd[i], dir, strlen (TMPDIR));
103 memcpy (keys, dir, strlen (TMPDIR));
104 if (system (cmd) != 0) {
106 fprintf (stderr, "psktool command failed\n");
107 exit (EXIT_FAILURE);
108 }
109 atexit (cleanup_keys);
111 }
112 int
114 main (int argc, char *argv[])
115 {
116 struct nbd_handle *nbd;
117 char buf[512];
118 create_keys ();
120 /* Create the libnbd handle. */
122 nbd = nbd_create ();
123 if (nbd == NULL) {
124 fprintf (stderr, "%s\n", nbd_get_error ());
125 exit (EXIT_FAILURE);
126 }
127 /* Enable TLS in the client. */
129 if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
130 fprintf (stderr, "%s\n", nbd_get_error ());
131 exit (EXIT_FAILURE);
132 }
133 /* Enable TLS-PSK and pass the keys filename. */
135 if (nbd_set_tls_psk_file (nbd, keys) == -1) {
136 fprintf (stderr, "%s\n", nbd_get_error ());
137 exit (EXIT_FAILURE);
138 }
139 /* Set the local username for authentication. */
141 if (nbd_set_tls_username (nbd, USERNAME) == -1) {
142 fprintf (stderr, "%s\n", nbd_get_error ());
143 exit (EXIT_FAILURE);
144 }
145 /* Run nbdkit as a subprocess, enabling and requiring
147 * TLS-PSK encryption.
148 */
149 char *args[] = {
150 "nbdkit", "-s", "--exit-with-parent",
151 "--tls", "require", "--tls-psk", keys,
152 "pattern", "size=1M", NULL
153 };
154 if (nbd_connect_command (nbd, args) == -1) {
155 fprintf (stderr, "%s\n", nbd_get_error ());
156 exit (EXIT_FAILURE);
157 }
158 /* Read the first sector. */
160 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
161 fprintf (stderr, "%s\n", nbd_get_error ());
162 exit (EXIT_FAILURE);
163 }
164 /* TLS connections must be shut down. */
166 if (nbd_shutdown (nbd, 0) == -1) {
167 fprintf (stderr, "%s\n", nbd_get_error ());
168 exit (EXIT_FAILURE);
169 }
170 /* Close the libnbd handle. */
172 nbd_close (nbd);
173 exit (EXIT_SUCCESS);
175 }
176
178 nbd_create(3), nbd_set_tls(3), libnbd(3).
179
181 Eric Blake
182 Richard W.M. Jones
184
186 Copyright (C) 2019-2021 Red Hat Inc.
187
189 This library is free software; you can redistribute it and/or modify it
190 under the terms of the GNU Lesser General Public License as published
191 by the Free Software Foundation; either version 2 of the License, or
192 (at your option) any later version.
193 This library is distributed in the hope that it will be useful, but
195 WITHOUT ANY WARRANTY; without even the implied warranty of
196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
197 Lesser General Public License for more details.
198 You should have received a copy of the GNU Lesser General Public
200 License along with this library; if not, write to the Free Software
201 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
202 02110-1301 USA
203libnbd-1.14.2 2023-01-03 nbd_set_tls_psk_file(3)