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 (struct nbd_handle *h,
12                                  const char *username);
13

DESCRIPTION

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
18       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

RETURN VALUE

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

ERRORS

26       On error "-1" is returned.
27
28       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
29       of the error.
30

HANDLE STATE

32       The handle must be newly created, otherwise this call will return an
33       error.
34

VERSION

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

EXAMPLE

44       This example is also available as examples/encryption.c in the libnbd
45       source code.
46
47        /* 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
58        #include <stdio.h>
59        #include <stdlib.h>
60        #include <string.h>
61        #include <unistd.h>
62
63        #include <libnbd.h>
64
65        #define TMPDIR "/tmp/XXXXXX"
66        #define KEYS "keys.psk"
67        #define USERNAME "alice"
68
69        static char dir[] = TMPDIR;
70        static char keys[] = TMPDIR "/" KEYS;
71        static char cmd[] =
72          "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
73
74        /* 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
84        /* 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
92          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
100          if (system (cmd) != 0) {
101            fprintf (stderr, "psktool command failed\n");
102            exit (EXIT_FAILURE);
103          }
104
105          atexit (cleanup_keys);
106        }
107
108        int
109        main (int argc, char *argv[])
110        {
111          struct nbd_handle *nbd;
112          char buf[512];
113
114          create_keys ();
115
116          /* 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
123          /* 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
129          /* 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
135          /* 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
141          /* 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
154          /* 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
160          /* 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
166          /* Close the libnbd handle. */
167          nbd_close (nbd);
168
169          exit (EXIT_SUCCESS);
170        }
171

SEE ALSO

173       nbd_create(3), nbd_get_tls_username(3), nbd_set_tls(3), libnbd(3).
174

AUTHORS

176       Eric Blake
177
178       Richard W.M. Jones
179
181       Copyright (C) 2019-2021 Red Hat Inc.
182

LICENSE

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
189       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
194       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
198
199
200
201libnbd-1.12.5                     2022-07-10           nbd_set_tls_username(3)
Impressum