1nbdkit-tls(1) NBDKIT nbdkit-tls(1)
2
6 nbdkit-tls - authentication and encryption of NBD connections
7 (sometimes incorrectly called "SSL")
8
10 nbdkit [--tls=off|on|require] [--tls-certificates /path/to/certificates]
11 [--tls-psk /path/to/pskfile] [--tls-verify-peer]
12 PLUGIN [...]
13
15 TLS (authentication and encryption, sometimes incorrectly called "SSL")
16 is supported if nbdkit was compiled with GnuTLS. This allows the
17 server to verify that the client is allowed access, and to encrypt the
18 contents of the protocol in transit over the network.
19 TLS can be disabled or enabled by specifying either --tls=off or
21 --tls=on. With --tls=off, if a client tries to use TLS to connect, it
22 will be rejected by the server (in other words, as if the server
23 doesn't support TLS).
24 --tls=on means that the client may choose to connect either with or
26 without TLS. In this mode, a plugin may wish to serve different
27 content depending on whether the client has authenticated; the function
28 "nbdkit_is_tls()" can be used during the ".open" callback for that
29 purpose. Or, you can opt to use nbdkit-tls-fallback-filter(1) to
30 provide safe fallback content to plaintext connections, saving the
31 plugin content only for secure connections.
32 Because --tls=on is subject to downgrade attacks where a malicious
34 proxy pretends not to support TLS in order to force either the client
35 or server to communicate in plaintext, you can also specify
36 --tls=require, where the server enables TLS and rejects all non-TLS
37 connection attempts.
38 If certificates have been set up correctly then you should be able to
40 start a TLS server by doing:
41 nbdkit --tls=require memory 1G
43 and connect to it by doing:
45 nbdinfo nbds://localhost
47 TLS with X.509 certificates
49 When nbdkit starts up, it loads TLS certificates from some built-in
50 paths, or from the directory specified by the --tls-certificates
51 option.
52 Without --tls-certificates, if nbdkit is started as a non-root user
54 (note this does not include use of the -u or -g options), nbdkit looks
55 in each of these paths in turn:
56 $HOME/.pki/nbdkit/
58 $HOME/.config/pki/nbdkit/
59 Without --tls-certificates, if nbdkit is started as root, nbkit looks
61 in:
62 $sysconfdir/pki/nbdkit/
64 (Use "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
66 setting to get the actual directory built into the binary.)
67 You can override both directories above by using --tls-certificates
69 /path/to/certificates.
70 In this directory, nbdkit expects to find several files:
72 ca-cert.pem
74 The Certificate Authority certificate.
75 server-cert.pem
77 The server certificate.
78 server-key.pem
80 The server private key.
81 ca-crl.pem
83 (Optional) The certificate revocation list.
84 Setting up the Certificate Authority
86 This step only needs to be done once per organization. It may be that
88 your organization already has a CA.
89 $ certtool --generate-privkey > ca-key.pem
91 $ chmod 0600 ca-key.pem
92 The ca-key.pem file is the CA private key and is extremely sensitive
94 data. With possession of this key, anyone can create certificates
95 pretending to be your organization!
96 To create the CA certificate file:
98 $ cat > ca.info <<EOF
100 cn = Name of your organization
101 ca
102 cert_signing_key
103 EOF
104 $ certtool --generate-self-signed \
105 --load-privkey ca-key.pem \
106 --template ca.info \
107 --outfile ca-cert.pem
108 Issuing a server certificate for the nbdkit server
110 Each nbdkit server (or host) needs a secret key and certificate.
112 $ certtool --generate-privkey > server-key.pem
114 $ chmod 0600 server-key.pem
115 The server key file is sensitive. Setting the mode to 0600 helps to
117 prevent other users on the same machine from reading it.
118 The server DNS name ("cn" below) must be the fully qualified hostname —
120 and the only hostname — that the client connects to.
121 $ cat > server.info <<EOF
123 organization = Name of your organization
124 cn = nbd-server.example.com
125 tls_www_server
126 encryption_key
127 signing_key
128 EOF
129 $ certtool --generate-certificate \
130 --load-ca-certificate ca-cert.pem \
131 --load-ca-privkey ca-key.pem \
132 --load-privkey server-key.pem \
133 --template server.info \
134 --outfile server-cert.pem
135 Issuing and checking client certificates
137 Note: You don't need to create client certificates unless you want to
139 check and limit which clients can connect to nbdkit. nbdkit does not
140 check client certificates unless you specify the --tls-verify-peer
141 option on the command line.
142 For each client you should generate a private key and a client
144 certificate:
145 $ certtool --generate-privkey > client-key.pem
147 $ chmod 0600 client-key.pem
148 The client key file is sensitive.
150 The client DNS name ("cn" below) is the client's name that nbdkit sees
152 and checks.
153 $ cat > client.info <<EOF
155 country = US
156 state = New York
157 locality = New York
158 organization = Name of your organization
159 cn = client.example.com
160 tls_www_client
161 encryption_key
162 signing_key
163 EOF
164 $ certtool --generate-certificate \
165 --load-ca-certificate ca-cert.pem \
166 --load-ca-privkey ca-key.pem \
167 --load-privkey client-key.pem \
168 --template client.info \
169 --outfile client-cert.pem
170 Client certificates do not need to be present anywhere on the nbdkit
172 host. You don't need to copy them into nbdkit's TLS certificates
173 directory. The security comes from the fact that the client must
174 present a client certificate signed by the Certificate Authority, and
175 nbdkit can check this because it has the ca-cert.pem file.
176 To enable checking of client certificates, specify the
178 --tls-verify-peer option on the command line. Clients which don't
179 present a valid certificate (eg. not signed, incorrect signature) are
180 denied. Also denied are clients which present a valid certificate
181 signed by another CA. Also denied are clients with certificates added
182 to the certificate revocation list (ca-crl.pem).
183 TLS with Pre-Shared Keys (PSK)
185 As a simpler alternative to TLS certificates, you may used pre-shared
186 keys to authenticate clients.
187 Create a PSK file containing one or more "username:key" pairs. It is
189 easiest to use psktool(1) for this:
190 mkdir -m 0700 /tmp/keys
192 psktool -u alice -p /tmp/keys/keys.psk
193 The PSK file contains the hex-encoded random keys in plaintext. Any
195 client which can read this file will be able to connect to the server.
196 Use the nbdkit --tls-psk option to start the server:
198 nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk file disk.img
200 This option overrides X.509 certificate authentication.
202 Clients must supply one of the usernames in the PSK file and the
204 corresponding key in order to connect.
205 An example of connecting using nbdinfo(1) using an NBD URI is:
207 nbdinfo 'nbds://alice@localhost?tls-psk-file=/tmp/keys/keys.psk'
209 An example of connecting using qemu-img(1) is:
211 qemu-img info \
213 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=alice,endpoint=client \
214 --image-opts \
215 file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
216 Default TLS behaviour
218 If nbdkit was compiled without GnuTLS support, then TLS is disabled and
219 TLS connections will be rejected (as if --tls=off was specified on the
220 command line). Also it is impossible to turn on TLS in this scenario.
221 You can tell if nbdkit was compiled without GnuTLS support because
222 "nbdkit --dump-config" will contain "tls=no".
223 If TLS certificates cannot be loaded either from the built-in path or
225 from the directory specified by --tls-certificates, then TLS defaults
226 to disabled. Turning TLS on will give a warning (--tls=on) or error
227 (--tls=require) about the missing certificates.
228 If TLS certificates can be loaded from the built-in path or from the
230 --tls-certificates directory, then TLS will by default be enabled (like
231 --tls=on), but it is not required. Clients can choose whether or not
232 to use TLS and whether or not to present certificates.
233 TLS client certificates are not checked by default unless you specify
235 --tls-verify-peer.
236 If the --tls-psk option is used then TLS is enabled (but not required).
238 To ensure that all clients are authorized you must use --tls=require.
239 Each of these defaults is insecure to some extent (including --tls=on
241 which could be subject to a downgrade attack), so if you expect TLS
242 then it is best to specify the --tls option that you require, and if
243 you want to check client certificates, specify the --tls-verify-peer
244 option.
245 Choice of TLS algorithms
247 TLS has a bewildering choice of algorithms that can be used. To enable
248 you to choose a default set of algorithms, there is a configure setting
249 "--with-tls-priority". This defaults to "NORMAL" which, to quote the
250 GnuTLS documentation:
251 ""NORMAL" means all "secure" ciphersuites. The 256-bit ciphers are
253 included as a fallback only. The ciphers are sorted by security
254 margin."
255 You could also set the TLS priority so that it can be configured from a
257 file at runtime:
258 ./configure --with-tls-priority=@SYSTEM
260 means use the policy from /etc/crypto-policies/config.
262 ./configure --with-tls-priority=@NBDKIT,SYSTEM
264 means use the policy from /etc/crypto-policies/local.d/nbdkit.config
266 and fall back to /etc/crypto-policies/config if the first file does not
267 exist.
268 More information can be found in gnutls_priority_init(3).
270 NBD URIs for TLS
272 Tools such nbdcopy(1), nbdinfo(1) and nbdsh(1) (from libnbd(3)) allow
273 you to use "nbds://" or "nbds+unix://" URIs to connect to nbdkit
274 servers using TLS.
275 The syntax is fully documented in the NBD URI specification:
277 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md. This
278 section contains an outline. You can also find further examples in
279 nbd_connect_uri(3).
280 nbds://example.com
282 Connect over TCP with TLS, to "example.com" port 10809. If the
283 server does not support TLS then this will fail.
284 nbds+unix:///?socket=SOCKET
286 As above, but connect over a Unix domain socket called SOCKET.
287 nbds+unix:///?socket=SOCKET&tls-psk-file=FILENAME
289 As above, but use TLS with Pre-Shared Keys (PSK), stored in the
290 secrets file FILENAME.
291 nbds+unix://alice@/?socket=SOCKET&tls-psk-file=FILENAME
293 As above, but use "alice" as the username.
294
296 nbdkit(1), nbdkit-tls-fallback-filter(1), nbdcopy(1), nbdinfo(1),
297 nbdsh(1), nbd_connect_uri(1), gnutls_priority_init(3), psktool(1),
298 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
299 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md,
300 https://nbd.sourceforge.io/.
301
303 Eric Blake
304 Richard W.M. Jones
306 Pino Toscano
308
310 Copyright (C) 2013-2020 Red Hat Inc.
311
313 Redistribution and use in source and binary forms, with or without
314 modification, are permitted provided that the following conditions are
315 met:
316 • Redistributions of source code must retain the above copyright
318 notice, this list of conditions and the following disclaimer.
319 • Redistributions in binary form must reproduce the above copyright
321 notice, this list of conditions and the following disclaimer in the
322 documentation and/or other materials provided with the
323 distribution.
324 • Neither the name of Red Hat nor the names of its contributors may
326 be used to endorse or promote products derived from this software
327 without specific prior written permission.
328 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
330 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
331 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
332 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
333 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
334 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
335 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
336 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
337 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
338 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
339 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
340nbdkit-1.25.8 2021-05-25 nbdkit-tls(1)