1nbdkit-tls(1) NBDKIT nbdkit-tls(1)
2
3
4
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
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
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
340 Richard W.M. Jones
341
342 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
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)