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