1nbdkit-tls(1)                       NBDKIT                       nbdkit-tls(1)
2
3
4

NAME

6       nbdkit-tls - authentication and encryption of NBD connections
7       (sometimes called "SSL")
8

SYNOPSIS

10        nbdkit [--tls=off|on|require]
11               [--tls-certificates=/path/to/certificates]
12               [--tls-psk=/path/to/pskfile]
13               [--tls-verify-peer]
14               PLUGIN [...]
15

DESCRIPTION

17       TLS (authentication and encryption, sometimes incorrectly called "SSL")
18       is supported if nbdkit was compiled with GnuTLS.  This allows the
19       server to verify that the client is allowed access, and to encrypt the
20       contents of the protocol in transit over the network.
21
22       TLS can be disabled or enabled by specifying either --tls=off or
23       --tls=on.  With --tls=off, if a client tries to use TLS to connect, it
24       will be rejected by the server (in other words, as if the server
25       doesn't support TLS).
26
27       --tls=on means that the client may choose to connect either with or
28       without TLS.
29
30       --tls=require enables TLS and rejects all non-TLS connection attempts.
31       This prevents downgrade attacks where a malicious proxy pretends not to
32       support TLS in order to force either the client or server to
33       communicate in plaintext.
34
35   Example
36       If certificates have been set up correctly then you should be able to
37       start a TLS server by doing:
38
39        nbdkit --tls=require memory 1G
40
41       and connect to it by doing:
42
43        nbdinfo nbds://localhost
44
45       If certificates are in a non-standard directory and you have
46       libnbd ≥ 1.10:
47
48        nbdkit --tls=require --tls-certificates=/certs memory 1G
49        nbdinfo nbds://localhost?tls-certificates=/certs
50
51   TLS with X.509 certificates
52       When nbdkit starts up, it loads TLS certificates from some built-in
53       paths, or from the directory specified by the --tls-certificates
54       option.
55
56       In this directory, nbdkit expects to find several files:
57
58       ca-cert.pem
59           The Certificate Authority certificate.
60
61       server-cert.pem
62           The server certificate.
63
64       server-key.pem
65           The server private key.
66
67       ca-crl.pem
68           (Optional) The certificate revocation list.
69
70       Setting up the Certificate Authority
71
72       This step only needs to be done once per organization.  It may be that
73       your organization already has a CA.
74
75        $ certtool --generate-privkey > ca-key.pem
76        $ chmod 0600 ca-key.pem
77
78       The ca-key.pem file is the CA private key and is extremely sensitive
79       data.  With possession of this key, anyone can create certificates
80       pretending to be your organization!
81
82       To create the CA certificate file:
83
84        $ cat > ca.info <<EOF
85        cn = Name of your organization
86        ca
87        cert_signing_key
88        EOF
89        $ certtool --generate-self-signed \
90                   --load-privkey ca-key.pem \
91                   --template ca.info \
92                   --outfile ca-cert.pem
93
94       Issuing a server certificate for the nbdkit server
95
96       Each nbdkit server (or host) needs a secret key and certificate.
97
98        $ certtool --generate-privkey > server-key.pem
99        $ chmod 0600 server-key.pem
100
101       The server key file is sensitive.  Setting the mode to 0600 helps to
102       prevent other users on the same machine from reading it.
103
104       The common name ("cn" below) field must be the fully qualified hostname
105       that the client connects to.  However most clients and servers
106       including nbdkit support the Subject Alternative Name extension
107       (RFC 2818) which uses the "dns_name" and "ip_address" fields and
108       deprecates "cn".
109
110        $ cat > server.info <<EOF
111        organization = Name of your organization
112        cn = nbd-server.example.com
113        dns_name = nbd-server
114        dns_name = nbd-server.example.com
115        ip_address = 10.0.1.2
116        ip_address = 2001:24::92
117        tls_www_server
118        encryption_key
119        signing_key
120        EOF
121        $ certtool --generate-certificate \
122                   --load-ca-certificate ca-cert.pem \
123                   --load-ca-privkey ca-key.pem \
124                   --load-privkey server-key.pem \
125                   --template server.info \
126                   --outfile server-cert.pem
127
128       Issuing and checking client certificates
129
130       Note: You don't need to create client certificates unless you want to
131       check and limit which clients can connect to nbdkit.  nbdkit does not
132       check client certificates unless you specify the --tls-verify-peer
133       option on the command line.  There are other methods for limiting
134       access to nbdkit including nbdkit-ip-filter(1).
135
136       For each client you should generate a private key and a client
137       certificate:
138
139        $ certtool --generate-privkey > client-key.pem
140        $ chmod 0600 client-key.pem
141
142       The client key file is sensitive.
143
144       The client DNS name ("cn" below) is the client's name that nbdkit sees
145       and checks.
146
147        $ cat > client.info <<EOF
148        country = US
149        state = New York
150        locality = New York
151        organization = Name of your organization
152        cn = client.example.com
153        tls_www_client
154        encryption_key
155        signing_key
156        EOF
157        $ certtool --generate-certificate \
158                   --load-ca-certificate ca-cert.pem \
159                   --load-ca-privkey ca-key.pem \
160                   --load-privkey client-key.pem \
161                   --template client.info \
162                   --outfile client-cert.pem
163
164       Client certificates do not need to be present anywhere on the nbdkit
165       host.  You don't need to copy them into nbdkit's TLS certificates
166       directory.  The security comes from the fact that the client must
167       present a client certificate signed by the Certificate Authority, and
168       nbdkit can check this because it has the ca-cert.pem file.
169
170       To enable checking of client certificates, specify the
171       --tls-verify-peer option on the command line.  Clients which don't
172       present a valid certificate (eg. not signed, incorrect signature) are
173       denied.  Also denied are clients which present a valid certificate
174       signed by another CA.  Also denied are clients with certificates added
175       to the certificate revocation list (ca-crl.pem).
176
177   Connecting nbd-client to nbdkit with TLS certificates
178       With the TLS certificates files generated above in the current
179       directory (".") you can use:
180
181        nbdkit --tls=require --tls-certificates=. --tls-verify-peer memory 1G
182
183        nbd-client /dev/nbd0 \
184                  -cacertfile ca-cert.pem \
185                  -certfile client-cert.pem \
186                  -keyfile client-key.pem
187
188       --tls-verify-peer is only required if you want to check the client
189       certificate.  If you want to allow any client to connect then you can
190       omit it.
191
192   TLS with Pre-Shared Keys (PSK)
193       As a simpler alternative to TLS certificates, you may use pre-shared
194       keys to authenticate clients.
195
196       Create a PSK file containing one or more "username:key" pairs.  It is
197       easiest to use psktool(1) for this:
198
199        mkdir -m 0700 /tmp/keys
200        psktool -u alice -p /tmp/keys/keys.psk
201
202       The PSK file contains the hex-encoded random keys in plaintext.  Any
203       client which can read this file will be able to connect to the server.
204
205       Use the nbdkit --tls-psk option to start the server:
206
207        nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk file disk.img
208
209       This option overrides X.509 certificate authentication.
210
211       Clients must supply one of the usernames in the PSK file and the
212       corresponding key in order to connect.
213
214       An example of connecting using nbdinfo(1) using an NBD URI is:
215
216        nbdinfo 'nbds://alice@localhost?tls-psk-file=/tmp/keys/keys.psk'
217
218       An example of connecting using qemu-img(1) is:
219
220        qemu-img info \
221          --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=alice,endpoint=client \
222          --image-opts \
223          file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
224
225   Default TLS behaviour
226       If nbdkit was compiled without GnuTLS support, then TLS is disabled and
227       TLS connections will be rejected (as if --tls=off was specified on the
228       command line).  Also it is impossible to turn on TLS in this scenario.
229       You can tell if nbdkit was compiled without GnuTLS support because
230       "nbdkit --dump-config" will contain "tls=no".
231
232       If TLS certificates cannot be loaded either from the built-in path or
233       from the directory specified by --tls-certificates, then TLS defaults
234       to disabled.  Turning TLS on will give a warning (--tls=on) or error
235       (--tls=require) about the missing certificates.
236
237       If TLS certificates can be loaded from the built-in path or from the
238       --tls-certificates directory, then TLS will by default be enabled (like
239       --tls=on), but it is not required.  Clients can choose whether or not
240       to use TLS and whether or not to present certificates.
241
242       TLS client certificates are not checked by default unless you specify
243       --tls-verify-peer.
244
245       If the --tls-psk option is used then TLS is enabled (but not required).
246       To ensure that all clients are authorized you must use --tls=require.
247
248       Each of these defaults is insecure to some extent (including --tls=on
249       which could be subject to a downgrade attack).  If you expect TLS then
250       it is best to specify --tls=require, and if you want to check client
251       certificates, additionally use the --tls-verify-peer option.
252
253   Controlling TLS fallback to plaintext
254       When --tls=on is used, the connection can fall back to plaintext.  You
255       can use nbdkit-tls-fallback-filter(1) to provide safe fallback content
256       to plaintext connections.  With this filter the underlying plugin
257       content is only served on secure connections.
258
259       Alternatively a plugin may wish to serve different content depending on
260       whether the client is using TLS.  The function nbdkit_is_tls() can be
261       used during the ".open" callback for that purpose.
262
263   NBD URIs for TLS
264       Tools such nbdcopy(1), nbdinfo(1) and nbdsh(1) (from libnbd(3)) allow
265       you to use "nbds://" or "nbds+unix://" URIs to connect to nbdkit
266       servers using TLS.
267
268       The syntax is fully documented in the NBD URI specification:
269       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.  This
270       section contains an outline.  You can also find further examples in
271       nbd_connect_uri(3).
272
273       nbds://example.com
274           Connect over TCP with TLS, to "example.com" port 10809.  If the
275           server does not support TLS then this will fail.
276
277       nbds+unix:///?socket=SOCKET
278           As above, but connect over a Unix domain socket called SOCKET.
279
280       nbds+unix:///?socket=SOCKET&tls-certificates=DIR
281           As above, but specify the directory DIR containing TLS certificates
282           (used by the client to verify the server, and to present client
283           authentication to the server).  Note this requires libnbd ≥ 1.10.
284
285       nbds+unix:///?socket=SOCKET&tls-psk-file=FILENAME
286           As above, but use TLS with Pre-Shared Keys (PSK), stored in the
287           secrets file FILENAME.
288
289       nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
290           As above, but use "alice" as the username.
291
292   Default location of certificates
293       Without --tls-certificates nbdkit and libnbd look in several locations
294       for certificates.
295
296       If nbdkit is started as a non-root user (note this does not include use
297       of the -u or -g options), nbdkit looks in each of these paths in turn:
298
299        $HOME/.pki/nbdkit/
300        $HOME/.config/pki/nbdkit/
301
302       If nbdkit is started as root:
303
304        $sysconfdir/pki/nbdkit/
305
306       where $sysconfdir is set when nbdkit is compiled, usually /etc.  (Use
307       "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
308       setting to get the actual directory built into the binary.)
309
310       In libnbd the paths are different.  For non-root:
311
312        $HOME/.pki/libnbd/
313        $HOME/.config/pki/libnbd/
314
315       For root:
316
317        $sysconfdir/pki/libnbd/
318
319       In nbdkit you can override these directories by using
320       --tls-certificates=/path/to/certificates.
321
322       In libnbd you can use nbd_set_tls_certificates(3).  In libnbd ≥ 1.10
323       you can append "&tls-certificates=/path/to/certificates" to URIs.
324
325   Choice of TLS algorithms
326       TLS has a bewildering choice of algorithms that can be used.  To enable
327       you to choose a default set of algorithms, there is a configure setting
328       --with-tls-priority.  This defaults to "NORMAL" which, to quote the
329       GnuTLS documentation:
330
331           ""NORMAL" means all "secure" ciphersuites.  The 256-bit ciphers are
332           included as a fallback only.  The ciphers are sorted by security
333           margin."
334
335       You could also set the TLS priority so that it can be configured from a
336       file at runtime:
337
338        ./configure --with-tls-priority=@SYSTEM
339
340       means use the policy from /etc/crypto-policies/config.
341
342        ./configure --with-tls-priority=@NBDKIT,SYSTEM
343
344       means use the policy from /etc/crypto-policies/local.d/nbdkit.config
345       and fall back to /etc/crypto-policies/config if the first file does not
346       exist.
347
348       More information can be found in gnutls_priority_init(3).
349
350   Debugging TLS connections
351       Encrypted connections makes snooping on network traffic with Wireshark
352       impossible, by design.
353
354       The TLS library used by nbdkit, called gnutls, supports the
355       "SSLKEYLOGFILE" standard:
356       https://web.archive.org/web/20200118013150/https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
357
358       Before running nbdkit set the environment variable to point to a log
359       file (note it will append to the file if it already exists):
360
361        SSLKEYLOGFILE=/tmp/keylog nbdkit [...]
362
363       In Wireshark go to Edit → Preferences → Protocols → TLS and set
364       (Pre)-Master-Secret log filename to the log file name.  Wireshark
365       should be able to see the unencrypted traffic.  For further information
366       read: https://wiki.wireshark.org/TLS#using-the-pre-master-secret
367

SEE ALSO

369       nbdkit(1), nbdkit-luks-filter(1), nbdkit-tls-fallback-filter(1),
370       nbdcopy(1), nbdfuse(1), nbdinfo(1), nbdsh(1), nbd_connect_uri(3),
371       nbd_set_tls(3), nbd_set_tls_certificates(3), gnutls_priority_init(3),
372       psktool(1),
373       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
374       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md,
375       https://nbd.sourceforge.io/.
376

AUTHORS

378       Eric Blake
379
380       Richard W.M. Jones
381
382       Pino Toscano
383
385       Copyright Red Hat
386

LICENSE

388       Redistribution and use in source and binary forms, with or without
389       modification, are permitted provided that the following conditions are
390       met:
391
392       •   Redistributions of source code must retain the above copyright
393           notice, this list of conditions and the following disclaimer.
394
395       •   Redistributions in binary form must reproduce the above copyright
396           notice, this list of conditions and the following disclaimer in the
397           documentation and/or other materials provided with the
398           distribution.
399
400       •   Neither the name of Red Hat nor the names of its contributors may
401           be used to endorse or promote products derived from this software
402           without specific prior written permission.
403
404       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
405       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
406       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
407       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
408       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
409       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
410       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
411       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
412       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
413       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
414       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
415
416
417
418nbdkit-1.36.2                     2023-11-26                     nbdkit-tls(1)
Impressum