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