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:

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).