nbd_set_tls(3)

1nbd_set_tls(3)                      LIBNBD                      nbd_set_tls(3)
2
3
4

NAME

6       nbd_set_tls - enable or require TLS (authentication and encryption)
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_set_tls (
12              struct nbd_handle *h, int tls
13            );
14

DESCRIPTION

16       Enable or require TLS (authenticated and encrypted connections) to the
17       NBD server.  The possible settings are:
18
19       "LIBNBD_TLS_DISABLE"
20           Disable TLS.  (The default setting, unless using nbd_connect_uri(3)
21           with a URI that requires TLS).
22
23           This setting is also necessary if you use nbd_set_opt_mode(3) and
24           want to interact in plaintext with a server that implements the NBD
25           protocol's "SELECTIVETLS" mode, prior to enabling TLS with
26           nbd_opt_starttls(3).  Most NBD servers with TLS support prefer the
27           NBD protocol's "FORCEDTLS" mode, so this sort of manual interaction
28           tends to be useful mainly during integration testing.
29
30       "LIBNBD_TLS_ALLOW"
31           Enable TLS if possible.
32
33           This option is insecure (or best effort) in that in some cases it
34           will fall back to an unencrypted and/or unauthenticated connection
35           if TLS could not be established.  Use "LIBNBD_TLS_REQUIRE" below if
36           the connection must be encrypted.
37
38           Some servers will drop the connection if TLS fails so fallback may
39           not be possible.
40
41       "LIBNBD_TLS_REQUIRE"
42           Require an encrypted and authenticated TLS connection.  Always fail
43           to connect if the connection is not encrypted and authenticated.
44
45       As well as calling this you may also need to supply the path to the
46       certificates directory (nbd_set_tls_certificates(3)), the username
47       (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
48       (nbd_set_tls_psk_file(3)).  For now, when using nbd_connect_uri(3), any
49       URI query parameters related to TLS are not handled automatically.
50       Setting the level higher than zero will fail if libnbd was not compiled
51       against gnutls; you can test whether this is the case with
52       nbd_supports_tls(3).
53

RETURN VALUE

55       If the call is successful the function returns 0.
56

ERRORS

58       On error -1 is returned.
59
60       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
61       of the error.
62
63       The following parameters must not be NULL: "h".  For more information
64       see "Non-NULL parameters" in libnbd(3).
65

HANDLE STATE

67       The handle must be newly created, otherwise this call will return an
68       error.
69

VERSION

71       This function first appeared in libnbd 1.0.
72
73       If you need to test if this function is available at compile time check
74       if the following macro is defined:
75
76        #define LIBNBD_HAVE_NBD_SET_TLS 1
77

EXAMPLE

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

AUTHORS

215       Eric Blake
216
217       Richard W.M. Jones
218

COPYRIGHT

220       Copyright Red Hat
221

LICENSE

223       This library is free software; you can redistribute it and/or modify it
224       under the terms of the GNU Lesser General Public License as published
225       by the Free Software Foundation; either version 2 of the License, or
226       (at your option) any later version.
227
228       This library is distributed in the hope that it will be useful, but
229       WITHOUT ANY WARRANTY; without even the implied warranty of
230       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
231       Lesser General Public License for more details.
232
233       You should have received a copy of the GNU Lesser General Public
234       License along with this library; if not, write to the Free Software
235       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
236       02110-1301 USA
237
238
239
240libnbd-1.18.1                     2023-10-31                    nbd_set_tls(3)