Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-tls(1)			    NBDKIT			 nbdkit-tls(1)

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 a
       and the only hostname a 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-2020 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:

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

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

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

nbdkit-1.20.4			  2020-08-28			 nbdkit-tls(1)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-tls&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help