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 use 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). 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 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 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 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 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 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 nbds+unix:///?socket=SOCKET
278 As above, but connect over a Unix domain socket called SOCKET.
279 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 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 nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
290 As above, but use "alice" as the username.
291 Default location of certificates
293 Without --tls-certificates nbdkit and libnbd look in several locations
294 for certificates.
295 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 $HOME/.pki/nbdkit/
300 $HOME/.config/pki/nbdkit/
301 If nbdkit is started as root:
303 $sysconfdir/pki/nbdkit/
305 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 In libnbd the paths are different. For non-root:
311 $HOME/.pki/libnbd/
313 $HOME/.config/pki/libnbd/
314 For root:
316 $sysconfdir/pki/libnbd/
318 In nbdkit you can override these directories by using
320 --tls-certificates=/path/to/certificates.
321 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 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 ""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 You could also set the TLS priority so that it can be configured from a
336 file at runtime:
337 ./configure --with-tls-priority=@SYSTEM
339 means use the policy from /etc/crypto-policies/config.
341 ./configure --with-tls-priority=@NBDKIT,SYSTEM
343 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 More information can be found in gnutls_priority_init(3).
349
351 nbdkit(1), nbdkit-luks-filter(1), nbdkit-tls-fallback-filter(1),
352 nbdcopy(1), nbdfuse(1), nbdinfo(1), nbdsh(1), nbd_connect_uri(3),
353 nbd_set_tls(3), nbd_set_tls_certificates(3), gnutls_priority_init(3),
354 psktool(1),
355 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
356 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md,
357 https://nbd.sourceforge.io/.
358
360 Eric Blake
361 Richard W.M. Jones
363 Pino Toscano
365
367 Copyright Red Hat
368
370 Redistribution and use in source and binary forms, with or without
371 modification, are permitted provided that the following conditions are
372 met:
373 • Redistributions of source code must retain the above copyright
375 notice, this list of conditions and the following disclaimer.
376 • Redistributions in binary form must reproduce the above copyright
378 notice, this list of conditions and the following disclaimer in the
379 documentation and/or other materials provided with the
380 distribution.
381 • Neither the name of Red Hat nor the names of its contributors may
383 be used to endorse or promote products derived from this software
384 without specific prior written permission.
385 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
387 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
388 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
389 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
390 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
391 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
392 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
393 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
394 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
395 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
396 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
397nbdkit-1.34.4 2023-09-26 nbdkit-tls(1)