docs/nbdkit-tls.pod

   1 =head1 NAME
   2
   3 nbdkit-tls - authentication and encryption of NBD connections
   4 (sometimes incorrectly called "SSL")
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit [--tls=off|on|require] [--tls-certificates /path/to/certificates]
   9         [--tls-psk /path/to/pskfile] [--tls-verify-peer]
  10         PLUGIN [...]
  11
  12 =head1 DESCRIPTION
  13
  14 TLS (authentication and encryption, sometimes incorrectly called
  15 "SSL") is supported if nbdkit was compiled with GnuTLS.  This allows
  16 the server to verify that the client is allowed access, and to encrypt
  17 the contents of the protocol in transit over the network.
  18
  19 TLS can be disabled or enabled by specifying either I<--tls=off> or
  20 I<--tls=on>.  With I<--tls=off>, if a client tries to use TLS to
  21 connect, it will be rejected by the server (in other words, as if the
  22 server doesn't support TLS).
  23
  24 I<--tls=on> means that the client may choose to connect either with or
  25 without TLS.
  26
  27 Because I<--tls=on> is subject to downgrade attacks where a malicious
  28 proxy pretends not to support TLS in order to force either the client
  29 or server to communicate in plaintext, you can also specify
  30 I<--tls=require>, where the server enables TLS B<and> rejects all
  31 non-TLS connection attempts.
  32
  33 =head2 TLS with X.509 certificates
  34
  35 When nbdkit starts up, it loads TLS certificates from some built-in
  36 paths, or from the directory specified by the I<--tls-certificates>
  37 option.
  38
  39 Without I<--tls-certificates>, if nbdkit is started as a non-root user
  40 (note this does not include use of the I<-u> or I<-g> options), nbdkit
  41 looks in each of these paths in turn:
  42
  43  $HOME/.pki/nbdkit/
  44  $HOME/.config/pki/nbdkit/
  45
  46 Without I<--tls-certificates>, if nbdkit is started as root, nbkit
  47 looks in:
  48
  49  $sysconfdir/pki/nbdkit/
  50
  51 (Use C<nbdkit --dump-config> and look at the
  52 C<root_tls_certificates_dir> setting to get the actual directory built
  53 into the binary.)
  54
  55 You can override both directories above by using
  56 I<--tls-certificates /path/to/certificates>.
  57
  58 In this directory, nbdkit expects to find several files:
  59
  60 =over 4
  61
  62 =item F<ca-cert.pem>
  63
  64 The Certificate Authority certificate.
  65
  66 =item F<server-cert.pem>
  67
  68 The server certificate.
  69
  70 =item F<server-key.pem>
  71
  72 The server private key.
  73
  74 =item F<ca-crl.pem>
  75
  76 (Optional) The certificate revocation list.
  77
  78 =back
  79
  80 =head3 Setting up the Certificate Authority
  81
  82 This step only needs to be done once per organization.  It may be that
  83 your organization already has a CA.
  84
  85  $ certtool --generate-privkey > ca-key.pem
  86  $ chmod 0600 ca-key.pem
  87
  88 The F<ca-key.pem> file is the CA private key and is I<extremely>
  89 sensitive data.  With possession of this key, anyone can create
  90 certificates pretending to be your organization!
  91
  92 To create the CA certificate file:
  93
  94  $ cat > ca.info <<EOF
  95  cn = Name of your organization
  96  ca
  97  cert_signing_key
  98  EOF
  99  $ certtool --generate-self-signed \
 100             --load-privkey ca-key.pem \
 101             --template ca.info \
 102             --outfile ca-cert.pem
 103
 104 =head3 Issuing a server certificate for the nbdkit server
 105
 106 Each nbdkit server (or host) needs a secret key and certificate.
 107
 108  $ certtool --generate-privkey > server-key.pem
 109  $ chmod 0600 server-key.pem
 110
 111 The server key file is sensitive.  Setting the mode to C<0600> helps
 112 to prevent other users on the same machine from reading it.
 113
 114 The server DNS name (C<cn> below) must be the fully qualified hostname
 115 — and the only hostname — that the client connects to.
 116
 117  $ cat > server.info <<EOF
 118  organization = Name of your organization
 119  cn = nbd-server.example.com
 120  tls_www_server
 121  encryption_key
 122  signing_key
 123  EOF
 124  $ certtool --generate-certificate \
 125             --load-ca-certificate ca-cert.pem \
 126             --load-ca-privkey ca-key.pem \
 127             --load-privkey server-key.pem \
 128             --template server.info \
 129             --outfile server-cert.pem
 130
 131 =head3 Issuing and checking client certificates
 132
 133 B<Note:>
 134 You don't need to create client certificates unless you want to check
 135 and limit which clients can connect to nbdkit.  nbdkit B<does not>
 136 check client certificates unless you specify the I<--tls-verify-peer>
 137 option on the command line.
 138
 139 For each client you should generate a private key and a client
 140 certificate:
 141
 142  $ certtool --generate-privkey > client-key.pem
 143  $ chmod 0600 client-key.pem
 144
 145 The client key file is sensitive.
 146
 147 The client DNS name (C<cn> below) is the client's name that nbdkit
 148 sees and checks.
 149
 150  $ cat > client.info <<EOF
 151  country = US
 152  state = New York
 153  locality = New York
 154  organization = Name of your organization
 155  cn = client.example.com
 156  tls_www_client
 157  encryption_key
 158  signing_key
 159  EOF
 160  $ certtool --generate-certificate \
 161             --load-ca-certificate ca-cert.pem \
 162             --load-ca-privkey ca-key.pem \
 163             --load-privkey client-key.pem \
 164             --template client.info \
 165             --outfile client-cert.pem
 166
 167 Client certificates do I<not> need to be present anywhere on the
 168 nbdkit host.  You don't need to copy them into nbdkit's TLS
 169 certificates directory.  The security comes from the fact that the
 170 client must present a client certificate signed by the Certificate
 171 Authority, and nbdkit can check this because it has the F<ca-cert.pem>
 172 file.
 173
 174 To enable checking of client certificates, specify the
 175 I<--tls-verify-peer> option on the command line.  Clients which don't
 176 present a valid certificate (eg. not signed, incorrect signature) are
 177 denied.  Also denied are clients which present a valid certificate
 178 signed by another CA.  Also denied are clients with certificates added
 179 to the certificate revocation list (F<ca-crl.pem>).
 180
 181 =head2 TLS with Pre-Shared Keys (PSK)
 182
 183 As a simpler alternative to TLS certificates, you may used pre-shared
 184 keys to authenticate clients.
 185
 186 Create a PSK file containing one or more C<username:key> pairs.  It is
 187 easiest to use L<psktool(1)> for this:
 188
 189  mkdir -m 0700 /tmp/keys
 190  psktool -u rich -p /tmp/keys/keys.psk
 191
 192 The PSK file contains the hex-encoded random keys in plaintext.  Any
 193 client which can read this file will be able to connect to the server.
 194
 195 Use the nbdkit I<--tls-psk> option to start the server:
 196
 197  nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk -e / file disk.img
 198
 199 This option overrides X.509 certificate authentication.
 200
 201 Clients must supply one of the usernames in the PSK file and the
 202 corresponding key in order to connect.  An example of connecting using
 203 L<qemu-img(1)> is:
 204
 205  qemu-img info \
 206    --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
 207    --image-opts \
 208    file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
 209
 210 =head2 Default TLS behaviour
 211
 212 If nbdkit was compiled without GnuTLS support, then TLS is disabled
 213 and TLS connections will be rejected (as if I<--tls=off> was specified
 214 on the command line).  Also it is impossible to turn on TLS in this
 215 scenario.  You can tell if nbdkit was compiled without GnuTLS support
 216 because C<nbdkit --dump-config> will contain C<tls=no>.
 217
 218 If TLS certificates cannot be loaded either from the built-in path or
 219 from the directory specified by I<--tls-certificates>, then TLS
 220 defaults to disabled.  Turning TLS on will give a warning
 221 (I<--tls=on>) or error (I<--tls=require>) about the missing
 222 certificates.
 223
 224 If TLS certificates can be loaded from the built-in path or from the
 225 I<--tls-certificates> directory, then TLS will by default be enabled
 226 (like I<--tls=on>), but it is not required.  Clients can choose
 227 whether or not to use TLS and whether or not to present certificates.
 228
 229 TLS client certificates are I<not> checked by default unless you
 230 specify I<--tls-verify-peer>.
 231
 232 If the I<--tls-psk> option is used then TLS is enabled (but I<not>
 233 required).  To ensure that all clients are authorized you must use
 234 I<--tls=require>.
 235
 236 Each of these defaults is insecure to some extent (including
 237 I<--tls=on> which could be subject to a downgrade attack), so if you
 238 expect TLS then it is best to specify the I<--tls> option that you
 239 require, and if you want to check client certificates, specify the
 240 I<--tls-verify-peer> option.
 241
 242 =head2 Choice of TLS algorithms
 243
 244 TLS has a bewildering choice of algorithms that can be used.  To
 245 enable you to choose a default set of algorithms, there is a configure
 246 setting C<--with-tls-priority>.  This defaults to C<NORMAL> which, to
 247 quote the GnuTLS documentation:
 248
 249 =over 4
 250
 251 "C<NORMAL> means all C<secure> ciphersuites.  The 256-bit ciphers are
 252 included as a fallback only.  The ciphers are sorted by security
 253 margin."
 254
 255 =back
 256
 257 You could also set the TLS priority so that it can be configured from
 258 a file at runtime:
 259
 260  ./configure --with-tls-priority=@SYSTEM
 261
 262 means use the policy from F</etc/crypto-policies/config>.
 263
 264  ./configure --with-tls-priority=@NBDKIT,SYSTEM
 265
 266 means use the policy from
 267 F</etc/crypto-policies/local.d/nbdkit.config> and fall back to
 268 F</etc/crypto-policies/config> if the first file does not exist.
 269
 270 More information can be found in L<gnutls_priority_init(3)>.
 271
 272 =head1 SEE ALSO
 273
 274 L<nbdkit(1)>,
 275 L<gnutls_priority_init(3)>,
 276 L<psktool(1)>,
 277 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>,
 278 L<https://nbd.sourceforge.io/>.
 279
 280 =head1 AUTHORS
 281
 282 Eric Blake
 283
 284 Richard W.M. Jones
 285
 286 Pino Toscano
 287
 288 =head1 COPYRIGHT
 289
 290 Copyright (C) 2013-2018 Red Hat Inc.