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