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
34 The handle must be newly created, otherwise this call will return an
35 error.
36
38 This function first appeared in libnbd 1.0.
39 If you need to test if this function is available at compile time check
41 if the following macro is defined:
42 #define LIBNBD_HAVE_NBD_SET_TLS_PSK_FILE 1
44
46 This example is also available as examples/encryption.c in the libnbd
47 source code.
48 /* An example showing how to connect to a server which is
50 * using TLS encryption.
51 *
52 * This requires nbdkit, and psktool from gnutls.
53 *
54 * Both libnbd and nbdkit support TLS-PSK which is a
55 * simpler-to-deploy form of encryption. (Of course
56 * certificate-based encryption is also supported, but
57 * it’s harder to make a self-contained example).
58 */
59 #include <stdio.h>
61 #include <stdlib.h>
62 #include <string.h>
63 #include <unistd.h>
64 #include <libnbd.h>
66 #define TMPDIR "/tmp/XXXXXX"
68 #define KEYS "keys.psk"
69 #define USERNAME "alice"
70 static char dir[] = TMPDIR;
72 static char keys[] = TMPDIR "/" KEYS;
73 static char cmd[] =
74 "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
75 /* Remove the temporary keys file when the program
77 * exits.
78 */
79 static void
80 cleanup_keys (void)
81 {
82 unlink (keys);
83 rmdir (dir);
84 }
85 /* Create the temporary keys file to share with the
87 * server.
88 */
89 static void
90 create_keys (void)
91 {
92 size_t i;
93 if (mkdtemp (dir) == NULL) {
95 perror ("mkdtemp");
96 exit (EXIT_FAILURE);
97 }
98 i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
99 memcpy (&cmd[i], dir, strlen (TMPDIR));
100 memcpy (keys, dir, strlen (TMPDIR));
101 if (system (cmd) != 0) {
103 fprintf (stderr, "psktool command failed\n");
104 exit (EXIT_FAILURE);
105 }
106 atexit (cleanup_keys);
108 }
109 int
111 main (int argc, char *argv[])
112 {
113 struct nbd_handle *nbd;
114 char buf[512];
115 create_keys ();
117 /* Create the libnbd handle. */
119 nbd = nbd_create ();
120 if (nbd == NULL) {
121 fprintf (stderr, "%s\n", nbd_get_error ());
122 exit (EXIT_FAILURE);
123 }
124 /* Enable TLS in the client. */
126 if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
127 fprintf (stderr, "%s\n", nbd_get_error ());
128 exit (EXIT_FAILURE);
129 }
130 /* Enable TLS-PSK and pass the keys filename. */
132 if (nbd_set_tls_psk_file (nbd, keys) == -1) {
133 fprintf (stderr, "%s\n", nbd_get_error ());
134 exit (EXIT_FAILURE);
135 }
136 /* Set the local username for authentication. */
138 if (nbd_set_tls_username (nbd, USERNAME) == -1) {
139 fprintf (stderr, "%s\n", nbd_get_error ());
140 exit (EXIT_FAILURE);
141 }
142 /* Run nbdkit as a subprocess, enabling and requiring
144 * TLS-PSK encryption.
145 */
146 char *args[] = {
147 "nbdkit", "-s", "--exit-with-parent",
148 "--tls", "require", "--tls-psk", keys,
149 "pattern", "size=1M", NULL
150 };
151 if (nbd_connect_command (nbd, args) == -1) {
152 fprintf (stderr, "%s\n", nbd_get_error ());
153 exit (EXIT_FAILURE);
154 }
155 /* Read the first sector. */
157 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
158 fprintf (stderr, "%s\n", nbd_get_error ());
159 exit (EXIT_FAILURE);
160 }
161 /* TLS connections must be shut down. */
163 if (nbd_shutdown (nbd, 0) == -1) {
164 fprintf (stderr, "%s\n", nbd_get_error ());
165 exit (EXIT_FAILURE);
166 }
167 /* Close the libnbd handle. */
169 nbd_close (nbd);
170 exit (EXIT_SUCCESS);
172 }
173
175 nbd_create(3), nbd_set_tls(3), libnbd(3).
176
178 Eric Blake
179 Richard W.M. Jones
181
183 Copyright (C) 2019-2021 Red Hat Inc.
184
186 This library is free software; you can redistribute it and/or modify it
187 under the terms of the GNU Lesser General Public License as published
188 by the Free Software Foundation; either version 2 of the License, or
189 (at your option) any later version.
190 This library is distributed in the hope that it will be useful, but
192 WITHOUT ANY WARRANTY; without even the implied warranty of
193 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
194 Lesser General Public License for more details.
195 You should have received a copy of the GNU Lesser General Public
197 License along with this library; if not, write to the Free Software
198 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
199 02110-1301 USA
200libnbd-1.10.1 2021-10-25 nbd_set_tls_psk_file(3)