.\" Automatically generated by Podwrapper::Man 1.24.1 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-tls 1"
.TH nbdkit-tls 1 "2021-01-20" "nbdkit-1.24.1" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-tls \- authentication and encryption of NBD connections
(sometimes incorrectly called "SSL")
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& nbdkit [\-\-tls=off|on|require] [\-\-tls\-certificates /path/to/certificates]
\&        [\-\-tls\-psk /path/to/pskfile] [\-\-tls\-verify\-peer]
\&        PLUGIN [...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1TLS\s0 (authentication and encryption, sometimes incorrectly called
\&\*(L"\s-1SSL\*(R"\s0) 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.
.PP
\&\s-1TLS\s0 can be disabled or enabled by specifying either \fI\-\-tls=off\fR or
\&\fI\-\-tls=on\fR.  With \fI\-\-tls=off\fR, if a client tries to use \s-1TLS\s0 to
connect, it will be rejected by the server (in other words, as if the
server doesn't support \s-1TLS\s0).
.PP
\&\fI\-\-tls=on\fR means that the client may choose to connect either with or
without \s-1TLS.\s0  In this mode, a plugin may wish to serve different
content depending on whether the client has authenticated; the
function \f(CW\*(C`nbdkit_is_tls()\*(C'\fR can be used during the \f(CW\*(C`.open\*(C'\fR callback
for that purpose.  Or, you can opt to use
\&\fBnbdkit\-tls\-fallback\-filter\fR\|(1) to provide safe fallback content to
plaintext connections, saving the plugin content only for secure
connections.
.PP
Because \fI\-\-tls=on\fR is subject to downgrade attacks where a malicious
proxy pretends not to support \s-1TLS\s0 in order to force either the client
or server to communicate in plaintext, you can also specify
\&\fI\-\-tls=require\fR, where the server enables \s-1TLS\s0 \fBand\fR rejects all
non-TLS connection attempts.
.SS "\s-1TLS\s0 with X.509 certificates"
.IX Subsection "TLS with X.509 certificates"
When nbdkit starts up, it loads \s-1TLS\s0 certificates from some built-in
paths, or from the directory specified by the \fI\-\-tls\-certificates\fR
option.
.PP
Without \fI\-\-tls\-certificates\fR, if nbdkit is started as a non-root user
(note this does not include use of the \fI\-u\fR or \fI\-g\fR options), nbdkit
looks in each of these paths in turn:
.PP
.Vb 2
\& $HOME/.pki/nbdkit/
\& $HOME/.config/pki/nbdkit/
.Ve
.PP
Without \fI\-\-tls\-certificates\fR, if nbdkit is started as root, nbkit
looks in:
.PP
.Vb 1
\& $sysconfdir/pki/nbdkit/
.Ve
.PP
(Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR and look at the
\&\f(CW\*(C`root_tls_certificates_dir\*(C'\fR setting to get the actual directory built
into the binary.)
.PP
You can override both directories above by using
\&\fI\-\-tls\-certificates /path/to/certificates\fR.
.PP
In this directory, nbdkit expects to find several files:
.IP "\fIca\-cert.pem\fR" 4
.IX Item "ca-cert.pem"
The Certificate Authority certificate.
.IP "\fIserver\-cert.pem\fR" 4
.IX Item "server-cert.pem"
The server certificate.
.IP "\fIserver\-key.pem\fR" 4
.IX Item "server-key.pem"
The server private key.
.IP "\fIca\-crl.pem\fR" 4
.IX Item "ca-crl.pem"
(Optional) The certificate revocation list.
.PP
\fISetting up the Certificate Authority\fR
.IX Subsection "Setting up the Certificate Authority"
.PP
This step only needs to be done once per organization.  It may be that
your organization already has a \s-1CA.\s0
.PP
.Vb 2
\& $ certtool \-\-generate\-privkey > ca\-key.pem
\& $ chmod 0600 ca\-key.pem
.Ve
.PP
The \fIca\-key.pem\fR file is the \s-1CA\s0 private key and is \fIextremely\fR
sensitive data.  With possession of this key, anyone can create
certificates pretending to be your organization!
.PP
To create the \s-1CA\s0 certificate file:
.PP
.Vb 9
\& $ cat > ca.info <<EOF
\& cn = Name of your organization
\& ca
\& cert_signing_key
\& EOF
\& $ certtool \-\-generate\-self\-signed \e
\&            \-\-load\-privkey ca\-key.pem \e
\&            \-\-template ca.info \e
\&            \-\-outfile ca\-cert.pem
.Ve
.PP
\fIIssuing a server certificate for the nbdkit server\fR
.IX Subsection "Issuing a server certificate for the nbdkit server"
.PP
Each nbdkit server (or host) needs a secret key and certificate.
.PP
.Vb 2
\& $ certtool \-\-generate\-privkey > server\-key.pem
\& $ chmod 0600 server\-key.pem
.Ve
.PP
The server key file is sensitive.  Setting the mode to \f(CW0600\fR helps
to prevent other users on the same machine from reading it.
.PP
The server \s-1DNS\s0 name (\f(CW\*(C`cn\*(C'\fR below) must be the fully qualified hostname
— and the only hostname — that the client connects to.
.PP
.Vb 10
\& $ 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 \e
\&            \-\-load\-ca\-certificate ca\-cert.pem \e
\&            \-\-load\-ca\-privkey ca\-key.pem \e
\&            \-\-load\-privkey server\-key.pem \e
\&            \-\-template server.info \e
\&            \-\-outfile server\-cert.pem
.Ve
.PP
\fIIssuing and checking client certificates\fR
.IX Subsection "Issuing and checking client certificates"
.PP
\&\fBNote:\fR
You don't need to create client certificates unless you want to check
and limit which clients can connect to nbdkit.  nbdkit \fBdoes not\fR
check client certificates unless you specify the \fI\-\-tls\-verify\-peer\fR
option on the command line.
.PP
For each client you should generate a private key and a client
certificate:
.PP
.Vb 2
\& $ certtool \-\-generate\-privkey > client\-key.pem
\& $ chmod 0600 client\-key.pem
.Ve
.PP
The client key file is sensitive.
.PP
The client \s-1DNS\s0 name (\f(CW\*(C`cn\*(C'\fR below) is the client's name that nbdkit
sees and checks.
.PP
.Vb 10
\& $ 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 \e
\&            \-\-load\-ca\-certificate ca\-cert.pem \e
\&            \-\-load\-ca\-privkey ca\-key.pem \e
\&            \-\-load\-privkey client\-key.pem \e
\&            \-\-template client.info \e
\&            \-\-outfile client\-cert.pem
.Ve
.PP
Client certificates do \fInot\fR need to be present anywhere on the
nbdkit host.  You don't need to copy them into nbdkit's \s-1TLS\s0
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 \fIca\-cert.pem\fR
file.
.PP
To enable checking of client certificates, specify the
\&\fI\-\-tls\-verify\-peer\fR 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 \s-1CA.\s0  Also denied are clients with certificates added
to the certificate revocation list (\fIca\-crl.pem\fR).
.SS "\s-1TLS\s0 with Pre-Shared Keys (\s-1PSK\s0)"
.IX Subsection "TLS with Pre-Shared Keys (PSK)"
As a simpler alternative to \s-1TLS\s0 certificates, you may used pre-shared
keys to authenticate clients.
.PP
Create a \s-1PSK\s0 file containing one or more \f(CW\*(C`username:key\*(C'\fR pairs.  It is
easiest to use \fBpsktool\fR\|(1) for this:
.PP
.Vb 2
\& mkdir \-m 0700 /tmp/keys
\& psktool \-u rich \-p /tmp/keys/keys.psk
.Ve
.PP
The \s-1PSK\s0 file contains the hex-encoded random keys in plaintext.  Any
client which can read this file will be able to connect to the server.
.PP
Use the nbdkit \fI\-\-tls\-psk\fR option to start the server:
.PP
.Vb 1
\& nbdkit \-\-tls=require \-\-tls\-psk=/tmp/keys/keys.psk \-e / file disk.img
.Ve
.PP
This option overrides X.509 certificate authentication.
.PP
Clients must supply one of the usernames in the \s-1PSK\s0 file and the
corresponding key in order to connect.  An example of connecting using
\&\fBqemu\-img\fR\|(1) is:
.PP
.Vb 4
\& qemu\-img info \e
\&   \-\-object tls\-creds\-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \e
\&   \-\-image\-opts \e
\&   file.driver=nbd,file.host=localhost,file.port=10809,file.tls\-creds=tls0,file.export=/
.Ve
.SS "Default \s-1TLS\s0 behaviour"
.IX Subsection "Default TLS behaviour"
If nbdkit was compiled without GnuTLS support, then \s-1TLS\s0 is disabled
and \s-1TLS\s0 connections will be rejected (as if \fI\-\-tls=off\fR was specified
on the command line).  Also it is impossible to turn on \s-1TLS\s0 in this
scenario.  You can tell if nbdkit was compiled without GnuTLS support
because \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR will contain \f(CW\*(C`tls=no\*(C'\fR.
.PP
If \s-1TLS\s0 certificates cannot be loaded either from the built-in path or
from the directory specified by \fI\-\-tls\-certificates\fR, then \s-1TLS\s0
defaults to disabled.  Turning \s-1TLS\s0 on will give a warning
(\fI\-\-tls=on\fR) or error (\fI\-\-tls=require\fR) about the missing
certificates.
.PP
If \s-1TLS\s0 certificates can be loaded from the built-in path or from the
\&\fI\-\-tls\-certificates\fR directory, then \s-1TLS\s0 will by default be enabled
(like \fI\-\-tls=on\fR), but it is not required.  Clients can choose
whether or not to use \s-1TLS\s0 and whether or not to present certificates.
.PP
\&\s-1TLS\s0 client certificates are \fInot\fR checked by default unless you
specify \fI\-\-tls\-verify\-peer\fR.
.PP
If the \fI\-\-tls\-psk\fR option is used then \s-1TLS\s0 is enabled (but \fInot\fR
required).  To ensure that all clients are authorized you must use
\&\fI\-\-tls=require\fR.
.PP
Each of these defaults is insecure to some extent (including
\&\fI\-\-tls=on\fR which could be subject to a downgrade attack), so if you
expect \s-1TLS\s0 then it is best to specify the \fI\-\-tls\fR option that you
require, and if you want to check client certificates, specify the
\&\fI\-\-tls\-verify\-peer\fR option.
.SS "Choice of \s-1TLS\s0 algorithms"
.IX Subsection "Choice of TLS algorithms"
\&\s-1TLS\s0 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 \f(CW\*(C`\-\-with\-tls\-priority\*(C'\fR.  This defaults to \f(CW\*(C`NORMAL\*(C'\fR which, to
quote the GnuTLS documentation:
.Sp
.RS 4
"\f(CW\*(C`NORMAL\*(C'\fR means all \f(CW\*(C`secure\*(C'\fR ciphersuites.  The 256\-bit ciphers are
included as a fallback only.  The ciphers are sorted by security
margin."
.RE
.PP
You could also set the \s-1TLS\s0 priority so that it can be configured from
a file at runtime:
.PP
.Vb 1
\& ./configure \-\-with\-tls\-priority=@SYSTEM
.Ve
.PP
means use the policy from \fI/etc/crypto\-policies/config\fR.
.PP
.Vb 1
\& ./configure \-\-with\-tls\-priority=@NBDKIT,SYSTEM
.Ve
.PP
means use the policy from
\&\fI/etc/crypto\-policies/local.d/nbdkit.config\fR and fall back to
\&\fI/etc/crypto\-policies/config\fR if the first file does not exist.
.PP
More information can be found in \fBgnutls_priority_init\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-tls\-fallback\-filter\fR\|(1),
\&\fBgnutls_priority_init\fR\|(3),
\&\fBpsktool\fR\|(1),
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
https://nbd.sourceforge.io/.
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.PP
Pino Toscano
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2013\-2020 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0