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 server DNS name ("cn" below) must be the fully qualified hostname —
105 and the only hostname — that the client connects to.
106 $ 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 Issuing and checking client certificates
122 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 For each client you should generate a private key and a client
130 certificate:
131 $ certtool --generate-privkey > client-key.pem
133 $ chmod 0600 client-key.pem
134 The client key file is sensitive.
136 The client DNS name ("cn" below) is the client's name that nbdkit sees
138 and checks.
139 $ 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 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 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 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 Create a PSK file containing one or more "username:key" pairs. It is
175 easiest to use psktool(1) for this:
176 mkdir -m 0700 /tmp/keys
178 psktool -u alice -p /tmp/keys/keys.psk
179 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 Use the nbdkit --tls-psk option to start the server:
184 nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk file disk.img
186 This option overrides X.509 certificate authentication.
188 Clients must supply one of the usernames in the PSK file and the
190 corresponding key in order to connect.
191 An example of connecting using nbdinfo(1) using an NBD URI is:
193 nbdinfo 'nbds://alice@localhost?tls-psk-file=/tmp/keys/keys.psk'
195 An example of connecting using qemu-img(1) is:
197 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 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 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 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 TLS client certificates are not checked by default unless you specify
221 --tls-verify-peer.
222 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 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 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 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 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 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 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 nbds+unix:///?socket=SOCKET
257 As above, but connect over a Unix domain socket called SOCKET.
258 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 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 nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
269 As above, but use "alice" as the username.
270 Default location of certificates
272 Without --tls-certificates nbdkit and libnbd look in several locations
273 for certificates.
274 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 $HOME/.pki/nbdkit/
279 $HOME/.config/pki/nbdkit/
280 If nbdkit is started as root:
282 $sysconfdir/pki/nbdkit/
284 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 In libnbd the paths are different. For non-root:
290 $HOME/.pki/libnbd/
292 $HOME/.config/pki/libnbd/
293 For root:
295 $sysconfdir/pki/libnbd/
297 In nbdkit you can override these directories by using
299 --tls-certificates=/path/to/certificates.
300 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 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 ""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 You could also set the TLS priority so that it can be configured from a
315 file at runtime:
316 ./configure --with-tls-priority=@SYSTEM
318 means use the policy from /etc/crypto-policies/config.
320 ./configure --with-tls-priority=@NBDKIT,SYSTEM
322 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 More information can be found in gnutls_priority_init(3).
328
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
338 Eric Blake
339 Richard W.M. Jones
341 Pino Toscano
343
345 Copyright (C) 2013-2021 Red Hat Inc.
346
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 • Redistributions of source code must retain the above copyright
353 notice, this list of conditions and the following disclaimer.
354 • 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 • 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 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.
375nbdkit-1.30.7 2022-07-10 nbdkit-tls(1)