1nbd_set_tls_username(3)             LIBNBD             nbd_set_tls_username(3)
2
3
4

NAME

6       nbd_set_tls_username - set the TLS username
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_set_tls_username (
12              struct nbd_handle *h, const char *username
13            );
14

DESCRIPTION

16       Set the TLS client username.  This is used if authenticating with PSK
17       over TLS is enabled.  If not set then the local username is used.
18
19       This function may be called regardless of whether TLS is supported, but
20       will have no effect unless nbd_set_tls(3) is also used to request or
21       require TLS.
22

RETURN VALUE

24       If the call is successful the function returns 0.
25

ERRORS

27       On error -1 is returned.
28
29       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
30       of the error.
31
32       The following parameters must not be NULL: "h", "username".  For more
33       information see "Non-NULL parameters" in libnbd(3).
34

HANDLE STATE

36       The handle must be newly created, otherwise this call will return an
37       error.
38

VERSION

40       This function first appeared in libnbd 1.0.
41
42       If you need to test if this function is available at compile time check
43       if the following macro is defined:
44
45        #define LIBNBD_HAVE_NBD_SET_TLS_USERNAME 1
46

EXAMPLE

48       This example is also available as examples/encryption.c in the libnbd
49       source code.
50
51        /* An example showing how to connect to a server which is
52         * using TLS encryption.
53         *
54         * This requires nbdkit, and psktool from gnutls.
55         *
56         * Both libnbd and nbdkit support TLS-PSK which is a
57         * simpler-to-deploy form of encryption.  (Of course
58         * certificate-based encryption is also supported, but
59         * it’s harder to make a self-contained example).
60         */
61
62        #include <stdio.h>
63        #include <stdlib.h>
64        #include <string.h>
65        #include <unistd.h>
66
67        #include <libnbd.h>
68
69        #define TMPDIR "/tmp/XXXXXX"
70        #define KEYS "keys.psk"
71        #define USERNAME "alice"
72
73        static char dir[] = TMPDIR;
74        static char keys[] = TMPDIR "/" KEYS;
75        static char cmd[] =
76          "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
77
78        /* Remove the temporary keys file when the program
79         * exits.
80         */
81        static void
82        cleanup_keys (void)
83        {
84          unlink (keys);
85          rmdir (dir);
86        }
87
88        /* Create the temporary keys file to share with the
89         * server.
90         */
91        static void
92        create_keys (void)
93        {
94          size_t i;
95
96          if (mkdtemp (dir) == NULL) {
97            perror ("mkdtemp");
98            exit (EXIT_FAILURE);
99          }
100          i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
101          memcpy (&cmd[i], dir, strlen (TMPDIR));
102          memcpy (keys, dir, strlen (TMPDIR));
103
104          if (system (cmd) != 0) {
105            fprintf (stderr, "psktool command failed\n");
106            exit (EXIT_FAILURE);
107          }
108
109          atexit (cleanup_keys);
110        }
111
112        int
113        main (int argc, char *argv[])
114        {
115          struct nbd_handle *nbd;
116          char buf[512];
117
118          create_keys ();
119
120          /* Create the libnbd handle. */
121          nbd = nbd_create ();
122          if (nbd == NULL) {
123            fprintf (stderr, "%s\n", nbd_get_error ());
124            exit (EXIT_FAILURE);
125          }
126
127          /* Enable TLS in the client. */
128          if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
129            fprintf (stderr, "%s\n", nbd_get_error ());
130            exit (EXIT_FAILURE);
131          }
132
133          /* Enable TLS-PSK and pass the keys filename. */
134          if (nbd_set_tls_psk_file (nbd, keys) == -1) {
135            fprintf (stderr, "%s\n", nbd_get_error ());
136            exit (EXIT_FAILURE);
137          }
138
139          /* Set the local username for authentication. */
140          if (nbd_set_tls_username (nbd, USERNAME) == -1) {
141            fprintf (stderr, "%s\n", nbd_get_error ());
142            exit (EXIT_FAILURE);
143          }
144
145          /* Run nbdkit as a subprocess, enabling and requiring
146           * TLS-PSK encryption.
147           */
148          char *args[] = {
149            "nbdkit", "-s", "--exit-with-parent",
150            "--tls", "require", "--tls-psk", keys,
151            "pattern", "size=1M", NULL
152          };
153          if (nbd_connect_command (nbd, args) == -1) {
154            fprintf (stderr, "%s\n", nbd_get_error ());
155            exit (EXIT_FAILURE);
156          }
157
158          /* Read the first sector. */
159          if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
160            fprintf (stderr, "%s\n", nbd_get_error ());
161            exit (EXIT_FAILURE);
162          }
163
164          /* TLS connections must be shut down. */
165          if (nbd_shutdown (nbd, 0) == -1) {
166            fprintf (stderr, "%s\n", nbd_get_error ());
167            exit (EXIT_FAILURE);
168          }
169
170          /* Close the libnbd handle. */
171          nbd_close (nbd);
172
173          exit (EXIT_SUCCESS);
174        }
175

SEE ALSO

177       nbd_create(3), nbd_get_tls_username(3), nbd_set_tls(3), libnbd(3).
178

AUTHORS

180       Eric Blake
181
182       Richard W.M. Jones
183
185       Copyright Red Hat
186

LICENSE

188       This library is free software; you can redistribute it and/or modify it
189       under the terms of the GNU Lesser General Public License as published
190       by the Free Software Foundation; either version 2 of the License, or
191       (at your option) any later version.
192
193       This library is distributed in the hope that it will be useful, but
194       WITHOUT ANY WARRANTY; without even the implied warranty of
195       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
196       Lesser General Public License for more details.
197
198       You should have received a copy of the GNU Lesser General Public
199       License along with this library; if not, write to the Free Software
200       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
201       02110-1301 USA
202
203
204
205libnbd-1.18.1                     2023-10-31           nbd_set_tls_username(3)
Impressum