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.
27 Because --tls=on is subject to downgrade attacks where a malicious
29 proxy pretends not to support TLS in order to force either the client
30 or server to communicate in plaintext, you can also specify
31 --tls=require, where the server enables TLS and rejects all non-TLS
32 connection attempts.
33 TLS with X.509 certificates
35 When nbdkit starts up, it loads TLS certificates from some built-in
36 paths, or from the directory specified by the --tls-certificates
37 option.
38 Without --tls-certificates, if nbdkit is started as a non-root user
40 (note this does not include use of the -u or -g options), nbdkit looks
41 in each of these paths in turn:
42 $HOME/.pki/nbdkit/
44 $HOME/.config/pki/nbdkit/
45 Without --tls-certificates, if nbdkit is started as root, nbkit looks
47 in:
48 $sysconfdir/pki/nbdkit/
50 (Use "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
52 setting to get the actual directory built into the binary.)
53 You can override both directories above by using --tls-certificates
55 /path/to/certificates.
56 In this directory, nbdkit expects to find several files:
58 ca-cert.pem
60 The Certificate Authority certificate.
61 server-cert.pem
63 The server certificate.
64 server-key.pem
66 The server private key.
67 ca-crl.pem
69 (Optional) The certificate revocation list.
70 Setting up the Certificate Authority
72 This step only needs to be done once per organization. It may be that
74 your organization already has a CA.
75 $ certtool --generate-privkey > ca-key.pem
77 $ chmod 0600 ca-key.pem
78 The ca-key.pem file is the CA private key and is extremely sensitive
80 data. With possession of this key, anyone can create certificates
81 pretending to be your organization!
82 To create the CA certificate file:
84 $ cat > ca.info <<EOF
86 cn = Name of your organization
87 ca
88 cert_signing_key
89 EOF
90 $ certtool --generate-self-signed \
91 --load-privkey ca-key.pem \
92 --template ca.info \
93 --outfile ca-cert.pem
94 Issuing a server certificate for the nbdkit server
96 Each nbdkit server (or host) needs a secret key and certificate.
98 $ certtool --generate-privkey > server-key.pem
100 $ chmod 0600 server-key.pem
101 The server key file is sensitive. Setting the mode to 0600 helps to
103 prevent other users on the same machine from reading it.
104 The server DNS name ("cn" below) must be the fully qualified hostname —
106 and the only hostname — that the client connects to.
107 $ cat > server.info <<EOF
109 organization = Name of your organization
110 cn = nbd-server.example.com
111 tls_www_server
112 encryption_key
113 signing_key
114 EOF
115 $ certtool --generate-certificate \
116 --load-ca-certificate ca-cert.pem \
117 --load-ca-privkey ca-key.pem \
118 --load-privkey server-key.pem \
119 --template server.info \
120 --outfile server-cert.pem
121 Issuing and checking client certificates
123 Note: You don't need to create client certificates unless you want to
125 check and limit which clients can connect to nbdkit. nbdkit does not
126 check client certificates unless you specify the --tls-verify-peer
127 option on the command line.
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 rich -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 -e / 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. An example of connecting using
191 qemu-img(1) is:
192 qemu-img info \
194 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
195 --image-opts \
196 file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
197 Default TLS behaviour
199 If nbdkit was compiled without GnuTLS support, then TLS is disabled and
200 TLS connections will be rejected (as if --tls=off was specified on the
201 command line). Also it is impossible to turn on TLS in this scenario.
202 You can tell if nbdkit was compiled without GnuTLS support because
203 "nbdkit --dump-config" will contain "tls=no".
204 If TLS certificates cannot be loaded either from the built-in path or
206 from the directory specified by --tls-certificates, then TLS defaults
207 to disabled. Turning TLS on will give a warning (--tls=on) or error
208 (--tls=require) about the missing certificates.
209 If TLS certificates can be loaded from the built-in path or from the
211 --tls-certificates directory, then TLS will by default be enabled (like
212 --tls=on), but it is not required. Clients can choose whether or not
213 to use TLS and whether or not to present certificates.
214 TLS client certificates are not checked by default unless you specify
216 --tls-verify-peer.
217 If the --tls-psk option is used then TLS is enabled (but not required).
219 To ensure that all clients are authorized you must use --tls=require.
220 Each of these defaults is insecure to some extent (including --tls=on
222 which could be subject to a downgrade attack), so if you expect TLS
223 then it is best to specify the --tls option that you require, and if
224 you want to check client certificates, specify the --tls-verify-peer
225 option.
226 Choice of TLS algorithms
228 TLS has a bewildering choice of algorithms that can be used. To enable
229 you to choose a default set of algorithms, there is a configure setting
230 "--with-tls-priority". This defaults to "NORMAL" which, to quote the
231 GnuTLS documentation:
232 ""NORMAL" means all "secure" ciphersuites. The 256-bit ciphers are
234 included as a fallback only. The ciphers are sorted by security
235 margin."
236 You could also set the TLS priority so that it can be configured from a
238 file at runtime:
239 ./configure --with-tls-priority=@SYSTEM
241 means use the policy from /etc/crypto-policies/config.
243 ./configure --with-tls-priority=@NBDKIT,SYSTEM
245 means use the policy from /etc/crypto-policies/local.d/nbdkit.config
247 and fall back to /etc/crypto-policies/config if the first file does not
248 exist.
249 More information can be found in gnutls_priority_init(3).
251
253 nbdkit(1), gnutls_priority_init(3), psktool(1),
254 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
255 https://nbd.sourceforge.io/.
256
258 Eric Blake
259 Richard W.M. Jones
261 Pino Toscano
263
265 Copyright (C) 2013-2018 Red Hat Inc.
266
268 Redistribution and use in source and binary forms, with or without
269 modification, are permitted provided that the following conditions are
270 met:
271 · Redistributions of source code must retain the above copyright
273 notice, this list of conditions and the following disclaimer.
274 · Redistributions in binary form must reproduce the above copyright
276 notice, this list of conditions and the following disclaimer in the
277 documentation and/or other materials provided with the
278 distribution.
279 · Neither the name of Red Hat nor the names of its contributors may
281 be used to endorse or promote products derived from this software
282 without specific prior written permission.
283 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
285 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
286 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
287 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
288 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
289 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
290 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
291 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
292 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
293 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
294 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
295nbdkit-1.16.1 2019-12-03 nbdkit-tls(1)