NAME

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

SYNOPSIS

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

DESCRIPTION

       TLS (authentication and encryption, sometimes incorrectly called "SSL") is supported if
       nbdkit was compiled with GnuTLS.  This allows the server to verify that the client is
       allowed access, and to encrypt the contents of the protocol in transit over the network.

       TLS can be disabled or enabled by specifying either --tls=off or --tls=on.  With
       --tls=off, if a client tries to use TLS to connect, it will be rejected by the server (in
       other words, as if the server doesn't support TLS).

       --tls=on means that the client may choose to connect either with or without TLS.

       Because --tls=on is subject to downgrade attacks where a malicious proxy pretends not to
       support TLS in order to force either the client or server to communicate in plaintext, you
       can also specify --tls=require, where the server enables TLS and rejects all non-TLS
       connection attempts.

   TLS with X.509 certificates
       When nbdkit starts up, it loads TLS certificates from some built-in paths, or from the
       directory specified by the --tls-certificates option.

       Without --tls-certificates, if nbdkit is started as a non-root user (note this does not
       include use of the -u or -g options), nbdkit looks in each of these paths in turn:

        $HOME/.pki/nbdkit/
        $HOME/.config/pki/nbdkit/

       Without --tls-certificates, if nbdkit is started as root, nbkit looks in:

        $sysconfdir/pki/nbdkit/

       (Use "nbdkit --dump-config" and look at the "root_tls_certificates_dir" setting to get the
       actual directory built into the binary.)

       You can override both directories above by using --tls-certificates /path/to/certificates.

       In this directory, nbdkit expects to find several files:

       ca-cert.pem
           The Certificate Authority certificate.

       server-cert.pem
           The server certificate.

       server-key.pem
           The server private key.

       ca-crl.pem
           (Optional) The certificate revocation list.

       Setting up the Certificate Authority

       This step only needs to be done once per organization.  It may be that your organization
       already has a CA.

        $ certtool --generate-privkey > ca-key.pem
        $ chmod 0600 ca-key.pem

       The ca-key.pem file is the CA private key and is extremely sensitive data.  With
       possession of this key, anyone can create certificates pretending to be your organization!

       To create the CA certificate file:

        $ cat > ca.info <<EOF
        cn = Name of your organization
        ca
        cert_signing_key
        EOF
        $ certtool --generate-self-signed \
                   --load-privkey ca-key.pem \
                   --template ca.info \
                   --outfile ca-cert.pem

       Issuing a server certificate for the nbdkit server

       Each nbdkit server (or host) needs a secret key and certificate.

        $ certtool --generate-privkey > server-key.pem
        $ chmod 0600 server-key.pem

       The server key file is sensitive.  Setting the mode to 0600 helps to prevent other users
       on the same machine from reading it.

       The server DNS name ("cn" below) must be the fully qualified hostname — and the only
       hostname — that the client connects to.

        $ cat > server.info <<EOF
        organization = Name of your organization
        cn = nbd-server.example.com
        tls_www_server
        encryption_key
        signing_key
        EOF
        $ certtool --generate-certificate \
                   --load-ca-certificate ca-cert.pem \
                   --load-ca-privkey ca-key.pem \
                   --load-privkey server-key.pem \
                   --template server.info \
                   --outfile server-cert.pem

       Issuing and checking client certificates

       Note: You don't need to create client certificates unless you want to check and limit
       which clients can connect to nbdkit.  nbdkit does not check client certificates unless you
       specify the --tls-verify-peer option on the command line.

       For each client you should generate a private key and a client certificate:

        $ certtool --generate-privkey > client-key.pem
        $ chmod 0600 client-key.pem

       The client key file is sensitive.

       The client DNS name ("cn" below) is the client's name that nbdkit sees and checks.

        $ cat > client.info <<EOF
        country = US
        state = New York
        locality = New York
        organization = Name of your organization
        cn = client.example.com
        tls_www_client
        encryption_key
        signing_key
        EOF
        $ certtool --generate-certificate \
                   --load-ca-certificate ca-cert.pem \
                   --load-ca-privkey ca-key.pem \
                   --load-privkey client-key.pem \
                   --template client.info \
                   --outfile client-cert.pem

       Client certificates do not need to be present anywhere on the nbdkit host.  You don't need
       to copy them into nbdkit's TLS certificates directory.  The security comes from the fact
       that the client must present a client certificate signed by the Certificate Authority, and
       nbdkit can check this because it has the ca-cert.pem file.

       To enable checking of client certificates, specify the --tls-verify-peer option on the
       command line.  Clients which don't present a valid certificate (eg. not signed, incorrect
       signature) are denied.  Also denied are clients which present a valid certificate signed
       by another CA.  Also denied are clients with certificates added to the certificate
       revocation list (ca-crl.pem).

   TLS with Pre-Shared Keys (PSK)
       As a simpler alternative to TLS certificates, you may used pre-shared keys to authenticate
       clients.

       Create a PSK file containing one or more "username:key" pairs.  It is easiest to use
       psktool(1) for this:

        mkdir -m 0700 /tmp/keys
        psktool -u rich -p /tmp/keys/keys.psk

       The PSK file contains the hex-encoded random keys in plaintext.  Any client which can read
       this file will be able to connect to the server.

       Use the nbdkit --tls-psk option to start the server:

        nbdkit --tls=require --tls-psk=/tmp/keys/keys.psk -e / file disk.img

       This option overrides X.509 certificate authentication.

       Clients must supply one of the usernames in the PSK file and the corresponding key in
       order to connect.  An example of connecting using qemu-img(1) is:

        qemu-img info \
          --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
          --image-opts \
          file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/

   Default TLS behaviour
       If nbdkit was compiled without GnuTLS support, then TLS is disabled and TLS connections
       will be rejected (as if --tls=off was specified on the command line).  Also it is
       impossible to turn on TLS in this scenario.  You can tell if nbdkit was compiled without
       GnuTLS support because "nbdkit --dump-config" will contain "tls=no".

       If TLS certificates cannot be loaded either from the built-in path or from the directory
       specified by --tls-certificates, then TLS defaults to disabled.  Turning TLS on will give
       a warning (--tls=on) or error (--tls=require) about the missing certificates.

       If TLS certificates can be loaded from the built-in path or from the --tls-certificates
       directory, then TLS will by default be enabled (like --tls=on), but it is not required.
       Clients can choose whether or not to use TLS and whether or not to present certificates.

       TLS client certificates are not checked by default unless you specify --tls-verify-peer.

       If the --tls-psk option is used then TLS is enabled (but not required).  To ensure that
       all clients are authorized you must use --tls=require.

       Each of these defaults is insecure to some extent (including --tls=on which could be
       subject to a downgrade attack), so if you expect TLS then it is best to specify the --tls
       option that you require, and if you want to check client certificates, specify the
       --tls-verify-peer option.

   Choice of TLS algorithms
       TLS has a bewildering choice of algorithms that can be used.  To enable you to choose a
       default set of algorithms, there is a configure setting "--with-tls-priority".  This
       defaults to "NORMAL" which, to quote the GnuTLS documentation:

           ""NORMAL" means all "secure" ciphersuites.  The 256-bit ciphers are included as a
           fallback only.  The ciphers are sorted by security margin."

       You could also set the TLS priority so that it can be configured from a file at runtime:

        ./configure --with-tls-priority=@SYSTEM

       means use the policy from /etc/crypto-policies/config.

        ./configure --with-tls-priority=@NBDKIT,SYSTEM

       means use the policy from /etc/crypto-policies/local.d/nbdkit.config and fall back to
       /etc/crypto-policies/config if the first file does not exist.

       More information can be found in gnutls_priority_init(3).

SEE ALSO

       nbdkit(1), gnutls_priority_init(3), psktool(1),
       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
       https://nbd.sourceforge.io/.

AUTHORS

       Eric Blake

       Richard W.M. Jones

       Pino Toscano

COPYRIGHT

       Copyright (C) 2013-2018 Red Hat Inc.

LICENSE

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       ·   Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.

       ·   Redistributions in binary form must reproduce the above copyright notice, this list of
           conditions and the following disclaimer in the documentation and/or other materials
           provided with the distribution.

       ·   Neither the name of Red Hat nor the names of its contributors may be used to endorse
           or promote products derived from this software without specific prior written
           permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.