1nbdkit-tls(1) NBDKIT nbdkit-tls(1)
2
6 nbdkit-tls - authentication and encryption of NBD connections
7 (sometimes called "SSL")
8
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
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 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 --tls=on means that the client may choose to connect either with or
28 without TLS.
29 --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 Example
36 If certificates have been set up correctly then you should be able to
37 start a TLS server by doing:
38 nbdkit --tls=require memory 1G
40 and connect to it by doing:
42 nbdinfo nbds://localhost
44 If certificates are in a non-standard directory and you have
46 libnbd ≥ 1.10:
47 nbdkit --tls=require --tls-certificates=/certs memory 1G
49 nbdinfo nbds://localhost?tls-certificates=/certs
50 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 In this directory, nbdkit expects to find several files:
57 ca-cert.pem
59 The Certificate Authority certificate.
60 server-cert.pem
62 The server certificate.
63 server-key.pem
65 The server private key.
66 ca-crl.pem
68 (Optional) The certificate revocation list.
69 Setting up the Certificate Authority
71 This step only needs to be done once per organization. It may be that
73 your organization already has a CA.
74 $ certtool --generate-privkey > ca-key.pem
76 $ chmod 0600 ca-key.pem
77 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 To create the CA certificate file:
83 $ 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 Issuing a server certificate for the nbdkit server
95 Each nbdkit server (or host) needs a secret key and certificate.
97 $ certtool --generate-privkey > server-key.pem
99 $ chmod 0600 server-key.pem
100 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 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 $ 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 Issuing and checking client certificates
129 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 For each client you should generate a private key and a client
137 certificate:
138 $ certtool --generate-privkey > client-key.pem
140 $ chmod 0600 client-key.pem
141 The client key file is sensitive.
143 The client DNS name ("cn" below) is the client's name that nbdkit sees
145 and checks.
146 $ 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 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 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 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 nbdkit --tls=require --tls-certificates=. --tls-verify-peer memory 1G
182 nbd-client /dev/nbd0 \
184 -cacertfile ca-cert.pem \
185 -certfile client-cert.pem \
186 -keyfile client-key.pem
187 --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 TLS with Pre-Shared Keys (PSK)
193 As a simpler alternative to TLS certificates, you may used pre-shared
194 keys to authenticate clients.
195 Create a PSK file containing one or more "username:key" pairs. It is
197 easiest to use psktool(1) for this:
198 mkdir -m 0700 /tmp/keys
200 psktool -u alice -p /tmp/keys/keys.psk
201 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 Use the nbdkit --tls-psk option to start the server:
206 nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk file disk.img
208 This option overrides X.509 certificate authentication.
210 Clients must supply one of the usernames in the PSK file and the
212 corresponding key in order to connect.
213 An example of connecting using nbdinfo(1) using an NBD URI is:
215 nbdinfo 'nbds://alice@localhost?tls-psk-file=/tmp/keys/keys.psk'
217 An example of connecting using qemu-img(1) is:
219 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 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 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 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 TLS client certificates are not checked by default unless you specify
243 --tls-verify-peer.
244 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 Each of these defaults is insecure to some extent (including --tls=on
249 which could be subject to a downgrade attack), so if you expect TLS
250 then it is best to specify the --tls option that you require, and if
251 you want to check client certificates, specify the --tls-verify-peer
252 option.
253 Controlling TLS fallback to plaintext
255 When --tls=on is used, the connection can fall back to plaintext. You
256 can use nbdkit-tls-fallback-filter(1) to provide safe fallback content
257 to plaintext connections. With this filter the underlying plugin
258 content is only served on secure connections.
259 Alternatively a plugin may wish to serve different content depending on
261 whether the client is using TLS. The function "nbdkit_is_tls()" can be
262 used during the ".open" callback for that purpose.
263 NBD URIs for TLS
265 Tools such nbdcopy(1), nbdinfo(1) and nbdsh(1) (from libnbd(3)) allow
266 you to use "nbds://" or "nbds+unix://" URIs to connect to nbdkit
267 servers using TLS.
268 The syntax is fully documented in the NBD URI specification:
270 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md. This
271 section contains an outline. You can also find further examples in
272 nbd_connect_uri(3).
273 nbds://example.com
275 Connect over TCP with TLS, to "example.com" port 10809. If the
276 server does not support TLS then this will fail.
277 nbds+unix:///?socket=SOCKET
279 As above, but connect over a Unix domain socket called SOCKET.
280 nbds+unix:///?socket=SOCKET&tls-certificates=DIR
282 As above, but specify the directory DIR containing TLS certificates
283 (used by the client to verify the server, and to present client
284 authentication to the server). Note this requires libnbd ≥ 1.10.
285 nbds+unix:///?socket=SOCKET&tls-psk-file=FILENAME
287 As above, but use TLS with Pre-Shared Keys (PSK), stored in the
288 secrets file FILENAME.
289 nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
291 As above, but use "alice" as the username.
292 Default location of certificates
294 Without --tls-certificates nbdkit and libnbd look in several locations
295 for certificates.
296 If nbdkit is started as a non-root user (note this does not include use
298 of the -u or -g options), nbdkit looks in each of these paths in turn:
299 $HOME/.pki/nbdkit/
301 $HOME/.config/pki/nbdkit/
302 If nbdkit is started as root:
304 $sysconfdir/pki/nbdkit/
306 where $sysconfdir is set when nbdkit is compiled, usually /etc. (Use
308 "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
309 setting to get the actual directory built into the binary.)
310 In libnbd the paths are different. For non-root:
312 $HOME/.pki/libnbd/
314 $HOME/.config/pki/libnbd/
315 For root:
317 $sysconfdir/pki/libnbd/
319 In nbdkit you can override these directories by using
321 --tls-certificates=/path/to/certificates.
322 In libnbd you can use nbd_set_tls_certificates(3). In libnbd ≥ 1.10
324 you can append "&tls-certificates=/path/to/certificates" to URIs.
325 Choice of TLS algorithms
327 TLS has a bewildering choice of algorithms that can be used. To enable
328 you to choose a default set of algorithms, there is a configure setting
329 --with-tls-priority. This defaults to "NORMAL" which, to quote the
330 GnuTLS documentation:
331 ""NORMAL" means all "secure" ciphersuites. The 256-bit ciphers are
333 included as a fallback only. The ciphers are sorted by security
334 margin."
335 You could also set the TLS priority so that it can be configured from a
337 file at runtime:
338 ./configure --with-tls-priority=@SYSTEM
340 means use the policy from /etc/crypto-policies/config.
342 ./configure --with-tls-priority=@NBDKIT,SYSTEM
344 means use the policy from /etc/crypto-policies/local.d/nbdkit.config
346 and fall back to /etc/crypto-policies/config if the first file does not
347 exist.
348 More information can be found in gnutls_priority_init(3).
350
352 nbdkit(1), nbdkit-luks-filter(1), nbdkit-tls-fallback-filter(1),
353 nbdcopy(1), nbdfuse(1), nbdinfo(1), nbdsh(1), nbd_connect_uri(3),
354 nbd_set_tls(3), nbd_set_tls_certificates(3), gnutls_priority_init(3),
355 psktool(1),
356 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
357 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md,
358 https://nbd.sourceforge.io/.
359
361 Eric Blake
362 Richard W.M. Jones
364 Pino Toscano
366
368 Copyright (C) 2013-2021 Red Hat Inc.
369
371 Redistribution and use in source and binary forms, with or without
372 modification, are permitted provided that the following conditions are
373 met:
374 • Redistributions of source code must retain the above copyright
376 notice, this list of conditions and the following disclaimer.
377 • Redistributions in binary form must reproduce the above copyright
379 notice, this list of conditions and the following disclaimer in the
380 documentation and/or other materials provided with the
381 distribution.
382 • Neither the name of Red Hat nor the names of its contributors may
384 be used to endorse or promote products derived from this software
385 without specific prior written permission.
386 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
388 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
389 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
390 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
391 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
392 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
393 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
394 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
395 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
396 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
397 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
398nbdkit-1.32.5 2023-01-03 nbdkit-tls(1)