1nbdkit-tls(1)                       NBDKIT                       nbdkit-tls(1)
2
3
4

NAME

6       nbdkit-tls - authentication and encryption of NBD connections
7       (sometimes incorrectly called "SSL")
8

SYNOPSIS

10        nbdkit [--tls=off|on|require] [--tls-certificates /path/to/certificates]
11               [--tls-psk /path/to/pskfile] [--tls-verify-peer]
12               PLUGIN [...]
13

DESCRIPTION

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
20       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
25       --tls=on means that the client may choose to connect either with or
26       without TLS.
27
28       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
34   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
39       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
43        $HOME/.pki/nbdkit/
44        $HOME/.config/pki/nbdkit/
45
46       Without --tls-certificates, if nbdkit is started as root, nbkit looks
47       in:
48
49        $sysconfdir/pki/nbdkit/
50
51       (Use "nbdkit --dump-config" and look at the "root_tls_certificates_dir"
52       setting to get the actual directory built into the binary.)
53
54       You can override both directories above by using --tls-certificates
55       /path/to/certificates.
56
57       In this directory, nbdkit expects to find several files:
58
59       ca-cert.pem
60           The Certificate Authority certificate.
61
62       server-cert.pem
63           The server certificate.
64
65       server-key.pem
66           The server private key.
67
68       ca-crl.pem
69           (Optional) The certificate revocation list.
70
71       Setting up the Certificate Authority
72
73       This step only needs to be done once per organization.  It may be that
74       your organization already has a CA.
75
76        $ certtool --generate-privkey > ca-key.pem
77        $ chmod 0600 ca-key.pem
78
79       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
83       To create the CA certificate file:
84
85        $ 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
95       Issuing a server certificate for the nbdkit server
96
97       Each nbdkit server (or host) needs a secret key and certificate.
98
99        $ certtool --generate-privkey > server-key.pem
100        $ chmod 0600 server-key.pem
101
102       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
105       The server DNS name ("cn" below) must be the fully qualified hostname —
106       and the only hostname — that the client connects to.
107
108        $ 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
122       Issuing and checking client certificates
123
124       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
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 rich -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 -e / 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.  An example of connecting using
191       qemu-img(1) is:
192
193        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
198   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
205       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
210       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
215       TLS client certificates are not checked by default unless you specify
216       --tls-verify-peer.
217
218       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
221       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
227   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
233           ""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
237       You could also set the TLS priority so that it can be configured from a
238       file at runtime:
239
240        ./configure --with-tls-priority=@SYSTEM
241
242       means use the policy from /etc/crypto-policies/config.
243
244        ./configure --with-tls-priority=@NBDKIT,SYSTEM
245
246       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
250       More information can be found in gnutls_priority_init(3).
251

SEE ALSO

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

AUTHORS

258       Eric Blake
259
260       Richard W.M. Jones
261
262       Pino Toscano
263
265       Copyright (C) 2013-2018 Red Hat Inc.
266

LICENSE

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
272       ·   Redistributions of source code must retain the above copyright
273           notice, this list of conditions and the following disclaimer.
274
275       ·   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
280       ·   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
284       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.
295
296
297
298nbdkit-1.18.4                     2020-04-16                     nbdkit-tls(1)
Impressum