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 server DNS name ("cn" below) must be the fully qualified hostname —
105       and the only hostname — that the client connects to.
106
107        $ cat > server.info <<EOF
108        organization = Name of your organization
109        cn = nbd-server.example.com
110        tls_www_server
111        encryption_key
112        signing_key
113        EOF
114        $ certtool --generate-certificate \
115                   --load-ca-certificate ca-cert.pem \
116                   --load-ca-privkey ca-key.pem \
117                   --load-privkey server-key.pem \
118                   --template server.info \
119                   --outfile server-cert.pem
120
121       Issuing and checking client certificates
122
123       Note: You don't need to create client certificates unless you want to
124       check and limit which clients can connect to nbdkit.  nbdkit does not
125       check client certificates unless you specify the --tls-verify-peer
126       option on the command line.  There are other methods for limiting
127       access to nbdkit including nbdkit-ip-filter(1).
128
129       For each client you should generate a private key and a client
130       certificate:
131
132        $ certtool --generate-privkey > client-key.pem
133        $ chmod 0600 client-key.pem
134
135       The client key file is sensitive.
136
137       The client DNS name ("cn" below) is the client's name that nbdkit sees
138       and checks.
139
140        $ cat > client.info <<EOF
141        country = US
142        state = New York
143        locality = New York
144        organization = Name of your organization
145        cn = client.example.com
146        tls_www_client
147        encryption_key
148        signing_key
149        EOF
150        $ certtool --generate-certificate \
151                   --load-ca-certificate ca-cert.pem \
152                   --load-ca-privkey ca-key.pem \
153                   --load-privkey client-key.pem \
154                   --template client.info \
155                   --outfile client-cert.pem
156
157       Client certificates do not need to be present anywhere on the nbdkit
158       host.  You don't need to copy them into nbdkit's TLS certificates
159       directory.  The security comes from the fact that the client must
160       present a client certificate signed by the Certificate Authority, and
161       nbdkit can check this because it has the ca-cert.pem file.
162
163       To enable checking of client certificates, specify the
164       --tls-verify-peer option on the command line.  Clients which don't
165       present a valid certificate (eg. not signed, incorrect signature) are
166       denied.  Also denied are clients which present a valid certificate
167       signed by another CA.  Also denied are clients with certificates added
168       to the certificate revocation list (ca-crl.pem).
169
170   TLS with Pre-Shared Keys (PSK)
171       As a simpler alternative to TLS certificates, you may used pre-shared
172       keys to authenticate clients.
173
174       Create a PSK file containing one or more "username:key" pairs.  It is
175       easiest to use psktool(1) for this:
176
177        mkdir -m 0700 /tmp/keys
178        psktool -u alice -p /tmp/keys/keys.psk
179
180       The PSK file contains the hex-encoded random keys in plaintext.  Any
181       client which can read this file will be able to connect to the server.
182
183       Use the nbdkit --tls-psk option to start the server:
184
185        nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk file disk.img
186
187       This option overrides X.509 certificate authentication.
188
189       Clients must supply one of the usernames in the PSK file and the
190       corresponding key in order to connect.
191
192       An example of connecting using nbdinfo(1) using an NBD URI is:
193
194        nbdinfo 'nbds://alice@localhost?tls-psk-file=/tmp/keys/keys.psk'
195
196       An example of connecting using qemu-img(1) is:
197
198        qemu-img info \
199          --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=alice,endpoint=client \
200          --image-opts \
201          file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
202
203   Default TLS behaviour
204       If nbdkit was compiled without GnuTLS support, then TLS is disabled and
205       TLS connections will be rejected (as if --tls=off was specified on the
206       command line).  Also it is impossible to turn on TLS in this scenario.
207       You can tell if nbdkit was compiled without GnuTLS support because
208       "nbdkit --dump-config" will contain "tls=no".
209
210       If TLS certificates cannot be loaded either from the built-in path or
211       from the directory specified by --tls-certificates, then TLS defaults
212       to disabled.  Turning TLS on will give a warning (--tls=on) or error
213       (--tls=require) about the missing certificates.
214
215       If TLS certificates can be loaded from the built-in path or from the
216       --tls-certificates directory, then TLS will by default be enabled (like
217       --tls=on), but it is not required.  Clients can choose whether or not
218       to use TLS and whether or not to present certificates.
219
220       TLS client certificates are not checked by default unless you specify
221       --tls-verify-peer.
222
223       If the --tls-psk option is used then TLS is enabled (but not required).
224       To ensure that all clients are authorized you must use --tls=require.
225
226       Each of these defaults is insecure to some extent (including --tls=on
227       which could be subject to a downgrade attack), so if you expect TLS
228       then it is best to specify the --tls option that you require, and if
229       you want to check client certificates, specify the --tls-verify-peer
230       option.
231
232   Controlling TLS fallback to plaintext
233       When --tls=on is used, the connection can fall back to plaintext.  You
234       can use nbdkit-tls-fallback-filter(1) to provide safe fallback content
235       to plaintext connections.  With this filter the underlying plugin
236       content is only served on secure connections.
237
238       Alternatively a plugin may wish to serve different content depending on
239       whether the client is using TLS.  The function "nbdkit_is_tls()" can be
240       used during the ".open" callback for that purpose.
241
242   NBD URIs for TLS
243       Tools such nbdcopy(1), nbdinfo(1) and nbdsh(1) (from libnbd(3)) allow
244       you to use "nbds://" or "nbds+unix://" URIs to connect to nbdkit
245       servers using TLS.
246
247       The syntax is fully documented in the NBD URI specification:
248       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.  This
249       section contains an outline.  You can also find further examples in
250       nbd_connect_uri(3).
251
252       nbds://example.com
253           Connect over TCP with TLS, to "example.com" port 10809.  If the
254           server does not support TLS then this will fail.
255
256       nbds+unix:///?socket=SOCKET
257           As above, but connect over a Unix domain socket called SOCKET.
258
259       nbds+unix:///?socket=SOCKET&tls-certificates=DIR
260           As above, but specify the directory DIR containing TLS certificates
261           (used by the client to verify the server, and to present client
262           authentication to the server).  Note this requires libnbd ≥ 1.10.
263
264       nbds+unix:///?socket=SOCKET&tls-psk-file=FILENAME
265           As above, but use TLS with Pre-Shared Keys (PSK), stored in the
266           secrets file FILENAME.
267
268       nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
269           As above, but use "alice" as the username.
270
271   Default location of certificates
272       Without --tls-certificates nbdkit and libnbd look in several locations
273       for certificates.
274
275       If nbdkit is started as a non-root user (note this does not include use
276       of the -u or -g options), nbdkit looks in each of these paths in turn:
277
278        $HOME/.pki/nbdkit/
279        $HOME/.config/pki/nbdkit/
280
281       If nbdkit is started as root:
282
283        $sysconfdir/pki/nbdkit/
284
285       where $sysconfdir is set when nbdkit is compiled, usually /etc.  (Use
286       "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
287       setting to get the actual directory built into the binary.)
288
289       In libnbd the paths are different.  For non-root:
290
291        $HOME/.pki/libnbd/
292        $HOME/.config/pki/libnbd/
293
294       For root:
295
296        $sysconfdir/pki/libnbd/
297
298       In nbdkit you can override these directories by using
299       --tls-certificates=/path/to/certificates.
300
301       In libnbd you can use nbd_set_tls_certificates(3).  In libnbd ≥ 1.10
302       you can append "&tls-certificates=/path/to/certificates" to URIs.
303
304   Choice of TLS algorithms
305       TLS has a bewildering choice of algorithms that can be used.  To enable
306       you to choose a default set of algorithms, there is a configure setting
307       --with-tls-priority.  This defaults to "NORMAL" which, to quote the
308       GnuTLS documentation:
309
310           ""NORMAL" means all "secure" ciphersuites.  The 256-bit ciphers are
311           included as a fallback only.  The ciphers are sorted by security
312           margin."
313
314       You could also set the TLS priority so that it can be configured from a
315       file at runtime:
316
317        ./configure --with-tls-priority=@SYSTEM
318
319       means use the policy from /etc/crypto-policies/config.
320
321        ./configure --with-tls-priority=@NBDKIT,SYSTEM
322
323       means use the policy from /etc/crypto-policies/local.d/nbdkit.config
324       and fall back to /etc/crypto-policies/config if the first file does not
325       exist.
326
327       More information can be found in gnutls_priority_init(3).
328

SEE ALSO

330       nbdkit(1), nbdkit-tls-fallback-filter(1), nbdcopy(1), nbdfuse(1),
331       nbdinfo(1), nbdsh(1), nbd_connect_uri(3), nbd_set_tls(3),
332       nbd_set_tls_certificates(3), gnutls_priority_init(3), psktool(1),
333       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
334       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md,
335       https://nbd.sourceforge.io/.
336

AUTHORS

338       Eric Blake
339
340       Richard W.M. Jones
341
342       Pino Toscano
343
345       Copyright (C) 2013-2021 Red Hat Inc.
346

LICENSE

348       Redistribution and use in source and binary forms, with or without
349       modification, are permitted provided that the following conditions are
350       met:
351
352       •   Redistributions of source code must retain the above copyright
353           notice, this list of conditions and the following disclaimer.
354
355       •   Redistributions in binary form must reproduce the above copyright
356           notice, this list of conditions and the following disclaimer in the
357           documentation and/or other materials provided with the
358           distribution.
359
360       •   Neither the name of Red Hat nor the names of its contributors may
361           be used to endorse or promote products derived from this software
362           without specific prior written permission.
363
364       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
365       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
366       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
367       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
368       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
369       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
370       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
371       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
372       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
373       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
374       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
375
376
377
378nbdkit-1.28.2                     2021-11-09                     nbdkit-tls(1)
Impressum