1nbd_set_tls(3) LIBNBD nbd_set_tls(3)
2
6 nbd_set_tls - enable or require TLS (authentication and encryption)
7
9 #include <libnbd.h>
10 int nbd_set_tls (struct nbd_handle *h, int tls);
12
14 Enable or require TLS (authenticated and encrypted connections) to the
15 NBD server. The possible settings are:
16 "LIBNBD_TLS_DISABLE"
18 Disable TLS. (The default setting, unless using nbd_connect_uri(3)
19 with a URI that requires TLS)
20 "LIBNBD_TLS_ALLOW"
22 Enable TLS if possible.
23 This option is insecure (or best effort) in that in some cases it
25 will fall back to an unencrypted and/or unauthenticated connection
26 if TLS could not be established. Use "LIBNBD_TLS_REQUIRE" below if
27 the connection must be encrypted.
28 Some servers will drop the connection if TLS fails so fallback may
30 not be possible.
31 "LIBNBD_TLS_REQUIRE"
33 Require an encrypted and authenticated TLS connection. Always fail
34 to connect if the connection is not encrypted and authenticated.
35 As well as calling this you may also need to supply the path to the
37 certificates directory (nbd_set_tls_certificates(3)), the username
38 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
39 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
40 URI query parameters related to TLS are not handled automatically.
41 Setting the level higher than zero will fail if libnbd was not compiled
42 against gnutls; you can test whether this is the case with
43 nbd_supports_tls(3).
44
46 If the call is successful the function returns 0.
47
49 On error "-1" is returned.
50 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
52 of the error.
53
55 The handle must be newly created, otherwise this call will return an
56 error.
57
59 This function first appeared in libnbd 1.0.
60 If you need to test if this function is available at compile time check
62 if the following macro is defined:
63 #define LIBNBD_HAVE_NBD_SET_TLS 1
65
67 This example is also available as examples/encryption.c in the libnbd
68 source code.
69 /* An example showing how to connect to a server which is
71 * using TLS encryption.
72 *
73 * This requires nbdkit, and psktool from gnutls.
74 *
75 * Both libnbd and nbdkit support TLS-PSK which is a
76 * simpler-to-deploy form of encryption. (Of course
77 * certificate-based encryption is also supported, but
78 * it’s harder to make a self-contained example).
79 */
80 #include <stdio.h>
82 #include <stdlib.h>
83 #include <string.h>
84 #include <unistd.h>
85 #include <libnbd.h>
87 #define TMPDIR "/tmp/XXXXXX"
89 #define KEYS "keys.psk"
90 #define USERNAME "alice"
91 static char dir[] = TMPDIR;
93 static char keys[] = TMPDIR "/" KEYS;
94 static char cmd[] =
95 "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
96 /* Remove the temporary keys file when the program
98 * exits.
99 */
100 static void
101 cleanup_keys (void)
102 {
103 unlink (keys);
104 rmdir (dir);
105 }
106 /* Create the temporary keys file to share with the
108 * server.
109 */
110 static void
111 create_keys (void)
112 {
113 size_t i;
114 if (mkdtemp (dir) == NULL) {
116 perror ("mkdtemp");
117 exit (EXIT_FAILURE);
118 }
119 i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
120 memcpy (&cmd[i], dir, strlen (TMPDIR));
121 memcpy (keys, dir, strlen (TMPDIR));
122 if (system (cmd) != 0) {
124 fprintf (stderr, "psktool command failed\n");
125 exit (EXIT_FAILURE);
126 }
127 atexit (cleanup_keys);
129 }
130 int
132 main (int argc, char *argv[])
133 {
134 struct nbd_handle *nbd;
135 char buf[512];
136 create_keys ();
138 /* Create the libnbd handle. */
140 nbd = nbd_create ();
141 if (nbd == NULL) {
142 fprintf (stderr, "%s\n", nbd_get_error ());
143 exit (EXIT_FAILURE);
144 }
145 /* Enable TLS in the client. */
147 if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
148 fprintf (stderr, "%s\n", nbd_get_error ());
149 exit (EXIT_FAILURE);
150 }
151 /* Enable TLS-PSK and pass the keys filename. */
153 if (nbd_set_tls_psk_file (nbd, keys) == -1) {
154 fprintf (stderr, "%s\n", nbd_get_error ());
155 exit (EXIT_FAILURE);
156 }
157 /* Set the local username for authentication. */
159 if (nbd_set_tls_username (nbd, USERNAME) == -1) {
160 fprintf (stderr, "%s\n", nbd_get_error ());
161 exit (EXIT_FAILURE);
162 }
163 /* Run nbdkit as a subprocess, enabling and requiring
165 * TLS-PSK encryption.
166 */
167 char *args[] = {
168 "nbdkit", "-s", "--exit-with-parent",
169 "--tls", "require", "--tls-psk", keys,
170 "pattern", "size=1M", NULL
171 };
172 if (nbd_connect_command (nbd, args) == -1) {
173 fprintf (stderr, "%s\n", nbd_get_error ());
174 exit (EXIT_FAILURE);
175 }
176 /* Read the first sector. */
178 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
179 fprintf (stderr, "%s\n", nbd_get_error ());
180 exit (EXIT_FAILURE);
181 }
182 /* TLS connections must be shut down. */
184 if (nbd_shutdown (nbd, 0) == -1) {
185 fprintf (stderr, "%s\n", nbd_get_error ());
186 exit (EXIT_FAILURE);
187 }
188 /* Close the libnbd handle. */
190 nbd_close (nbd);
191 exit (EXIT_SUCCESS);
193 }
194
196 "ENCRYPTION AND AUTHENTICATION" in libnbd(3), nbd_get_tls(3),
197 nbd_get_tls_negotiated(3), nbd_create(3), libnbd(3).
198
200 Eric Blake
201 Richard W.M. Jones
203
205 Copyright (C) 2019 Red Hat Inc.
206
208 This library is free software; you can redistribute it and/or modify it
209 under the terms of the GNU Lesser General Public License as published
210 by the Free Software Foundation; either version 2 of the License, or
211 (at your option) any later version.
212 This library is distributed in the hope that it will be useful, but
214 WITHOUT ANY WARRANTY; without even the implied warranty of
215 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
216 Lesser General Public License for more details.
217 You should have received a copy of the GNU Lesser General Public
219 License along with this library; if not, write to the Free Software
220 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
221 02110-1301 USA
222libnbd-1.2.1 2019-11-14 nbd_set_tls(3)