docs/system/tls.rst

   1 .. _network_005ftls:
   2
   3 TLS setup for network services
   4 ------------------------------
   5
   6 Almost all network services in QEMU have the ability to use TLS for
   7 session data encryption, along with x509 certificates for simple client
   8 authentication. What follows is a description of how to generate
   9 certificates suitable for usage with QEMU, and applies to the VNC
  10 server, character devices with the TCP backend, NBD server and client,
  11 and migration server and client.
  12
  13 At a high level, QEMU requires certificates and private keys to be
  14 provided in PEM format. Aside from the core fields, the certificates
  15 should include various extension data sets, including v3 basic
  16 constraints data, key purpose, key usage and subject alt name.
  17
  18 The GnuTLS package includes a command called ``certtool`` which can be
  19 used to easily generate certificates and keys in the required format
  20 with expected data present. Alternatively a certificate management
  21 service may be used.
  22
  23 At a minimum it is necessary to setup a certificate authority, and issue
  24 certificates to each server. If using x509 certificates for
  25 authentication, then each client will also need to be issued a
  26 certificate.
  27
  28 Assuming that the QEMU network services will only ever be exposed to
  29 clients on a private intranet, there is no need to use a commercial
  30 certificate authority to create certificates. A self-signed CA is
  31 sufficient, and in fact likely to be more secure since it removes the
  32 ability of malicious 3rd parties to trick the CA into mis-issuing certs
  33 for impersonating your services. The only likely exception where a
  34 commercial CA might be desirable is if enabling the VNC websockets
  35 server and exposing it directly to remote browser clients. In such a
  36 case it might be useful to use a commercial CA to avoid needing to
  37 install custom CA certs in the web browsers.
  38
  39 The recommendation is for the server to keep its certificates in either
  40 ``/etc/pki/qemu`` or for unprivileged users in ``$HOME/.pki/qemu``.
  41
  42 .. _tls_005fgenerate_005fca:
  43
  44 Setup the Certificate Authority
  45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 This step only needs to be performed once per organization /
  48 organizational unit. First the CA needs a private key. This key must be
  49 kept VERY secret and secure. If this key is compromised the entire trust
  50 chain of the certificates issued with it is lost.
  51
  52 ::
  53
  54    # certtool --generate-privkey > ca-key.pem
  55
  56 To generate a self-signed certificate requires one core piece of
  57 information, the name of the organization. A template file ``ca.info``
  58 should be populated with the desired data to avoid having to deal with
  59 interactive prompts from certtool::
  60
  61    # cat > ca.info <<EOF
  62    cn = Name of your organization
  63    ca
  64    cert_signing_key
  65    EOF
  66    # certtool --generate-self-signed \
  67               --load-privkey ca-key.pem \
  68               --template ca.info \
  69               --outfile ca-cert.pem
  70
  71 The ``ca`` keyword in the template sets the v3 basic constraints
  72 extension to indicate this certificate is for a CA, while
  73 ``cert_signing_key`` sets the key usage extension to indicate this will
  74 be used for signing other keys. The generated ``ca-cert.pem`` file
  75 should be copied to all servers and clients wishing to utilize TLS
  76 support in the VNC server. The ``ca-key.pem`` must not be
  77 disclosed/copied anywhere except the host responsible for issuing
  78 certificates.
  79
  80 .. _tls_005fgenerate_005fserver:
  81
  82 Issuing server certificates
  83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  84
  85 Each server (or host) needs to be issued with a key and certificate.
  86 When connecting the certificate is sent to the client which validates it
  87 against the CA certificate. The core pieces of information for a server
  88 certificate are the hostnames and/or IP addresses that will be used by
  89 clients when connecting. The hostname / IP address that the client
  90 specifies when connecting will be validated against the hostname(s) and
  91 IP address(es) recorded in the server certificate, and if no match is
  92 found the client will close the connection.
  93
  94 Thus it is recommended that the server certificate include both the
  95 fully qualified and unqualified hostnames. If the server will have
  96 permanently assigned IP address(es), and clients are likely to use them
  97 when connecting, they may also be included in the certificate. Both IPv4
  98 and IPv6 addresses are supported. Historically certificates only
  99 included 1 hostname in the ``CN`` field, however, usage of this field
 100 for validation is now deprecated. Instead modern TLS clients will
 101 validate against the Subject Alt Name extension data, which allows for
 102 multiple entries. In the future usage of the ``CN`` field may be
 103 discontinued entirely, so providing SAN extension data is strongly
 104 recommended.
 105
 106 On the host holding the CA, create template files containing the
 107 information for each server, and use it to issue server certificates.
 108
 109 ::
 110
 111    # cat > server-hostNNN.info <<EOF
 112    organization = Name  of your organization
 113    cn = hostNNN.foo.example.com
 114    dns_name = hostNNN
 115    dns_name = hostNNN.foo.example.com
 116    ip_address = 10.0.1.87
 117    ip_address = 192.8.0.92
 118    ip_address = 2620:0:cafe::87
 119    ip_address = 2001:24::92
 120    tls_www_server
 121    encryption_key
 122    signing_key
 123    EOF
 124    # certtool --generate-privkey > server-hostNNN-key.pem
 125    # certtool --generate-certificate \
 126               --load-ca-certificate ca-cert.pem \
 127               --load-ca-privkey ca-key.pem \
 128               --load-privkey server-hostNNN-key.pem \
 129               --template server-hostNNN.info \
 130               --outfile server-hostNNN-cert.pem
 131
 132 The ``dns_name`` and ``ip_address`` fields in the template are setting
 133 the subject alt name extension data. The ``tls_www_server`` keyword is
 134 the key purpose extension to indicate this certificate is intended for
 135 usage in a web server. Although QEMU network services are not in fact
 136 HTTP servers (except for VNC websockets), setting this key purpose is
 137 still recommended. The ``encryption_key`` and ``signing_key`` keyword is
 138 the key usage extension to indicate this certificate is intended for
 139 usage in the data session.
 140
 141 The ``server-hostNNN-key.pem`` and ``server-hostNNN-cert.pem`` files
 142 should now be securely copied to the server for which they were
 143 generated, and renamed to ``server-key.pem`` and ``server-cert.pem``
 144 when added to the ``/etc/pki/qemu`` directory on the target host. The
 145 ``server-key.pem`` file is security sensitive and should be kept
 146 protected with file mode 0600 to prevent disclosure.
 147
 148 .. _tls_005fgenerate_005fclient:
 149
 150 Issuing client certificates
 151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 152
 153 The QEMU x509 TLS credential setup defaults to enabling client
 154 verification using certificates, providing a simple authentication
 155 mechanism. If this default is used, each client also needs to be issued
 156 a certificate. The client certificate contains enough metadata to
 157 uniquely identify the client with the scope of the certificate
 158 authority. The client certificate would typically include fields for
 159 organization, state, city, building, etc.
 160
 161 Once again on the host holding the CA, create template files containing
 162 the information for each client, and use it to issue client
 163 certificates.
 164
 165 ::
 166
 167    # cat > client-hostNNN.info <<EOF
 168    country = GB
 169    state = London
 170    locality = City Of London
 171    organization = Name of your organization
 172    cn = hostNNN.foo.example.com
 173    tls_www_client
 174    encryption_key
 175    signing_key
 176    EOF
 177    # certtool --generate-privkey > client-hostNNN-key.pem
 178    # certtool --generate-certificate \
 179               --load-ca-certificate ca-cert.pem \
 180               --load-ca-privkey ca-key.pem \
 181               --load-privkey client-hostNNN-key.pem \
 182               --template client-hostNNN.info \
 183               --outfile client-hostNNN-cert.pem
 184
 185 The subject alt name extension data is not required for clients, so the
 186 the ``dns_name`` and ``ip_address`` fields are not included. The
 187 ``tls_www_client`` keyword is the key purpose extension to indicate this
 188 certificate is intended for usage in a web client. Although QEMU network
 189 clients are not in fact HTTP clients, setting this key purpose is still
 190 recommended. The ``encryption_key`` and ``signing_key`` keyword is the
 191 key usage extension to indicate this certificate is intended for usage
 192 in the data session.
 193
 194 The ``client-hostNNN-key.pem`` and ``client-hostNNN-cert.pem`` files
 195 should now be securely copied to the client for which they were
 196 generated, and renamed to ``client-key.pem`` and ``client-cert.pem``
 197 when added to the ``/etc/pki/qemu`` directory on the target host. The
 198 ``client-key.pem`` file is security sensitive and should be kept
 199 protected with file mode 0600 to prevent disclosure.
 200
 201 If a single host is going to be using TLS in both a client and server
 202 role, it is possible to create a single certificate to cover both roles.
 203 This would be quite common for the migration and NBD services, where a
 204 QEMU process will be started by accepting a TLS protected incoming
 205 migration, and later itself be migrated out to another host. To generate
 206 a single certificate, simply include the template data from both the
 207 client and server instructions in one.
 208
 209 ::
 210
 211    # cat > both-hostNNN.info <<EOF
 212    country = GB
 213    state = London
 214    locality = City Of London
 215    organization = Name of your organization
 216    cn = hostNNN.foo.example.com
 217    dns_name = hostNNN
 218    dns_name = hostNNN.foo.example.com
 219    ip_address = 10.0.1.87
 220    ip_address = 192.8.0.92
 221    ip_address = 2620:0:cafe::87
 222    ip_address = 2001:24::92
 223    tls_www_server
 224    tls_www_client
 225    encryption_key
 226    signing_key
 227    EOF
 228    # certtool --generate-privkey > both-hostNNN-key.pem
 229    # certtool --generate-certificate \
 230               --load-ca-certificate ca-cert.pem \
 231               --load-ca-privkey ca-key.pem \
 232               --load-privkey both-hostNNN-key.pem \
 233               --template both-hostNNN.info \
 234               --outfile both-hostNNN-cert.pem
 235
 236 When copying the PEM files to the target host, save them twice, once as
 237 ``server-cert.pem`` and ``server-key.pem``, and again as
 238 ``client-cert.pem`` and ``client-key.pem``.
 239
 240 .. _tls_005fcreds_005fsetup:
 241
 242 TLS x509 credential configuration
 243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 244
 245 QEMU has a standard mechanism for loading x509 credentials that will be
 246 used for network services and clients. It requires specifying the
 247 ``tls-creds-x509`` class name to the ``--object`` command line argument
 248 for the system emulators. Each set of credentials loaded should be given
 249 a unique string identifier via the ``id`` parameter. A single set of TLS
 250 credentials can be used for multiple network backends, so VNC,
 251 migration, NBD, character devices can all share the same credentials.
 252 Note, however, that credentials for use in a client endpoint must be
 253 loaded separately from those used in a server endpoint.
 254
 255 When specifying the object, the ``dir`` parameters specifies which
 256 directory contains the credential files. This directory is expected to
 257 contain files with the names mentioned previously, ``ca-cert.pem``,
 258 ``server-key.pem``, ``server-cert.pem``, ``client-key.pem`` and
 259 ``client-cert.pem`` as appropriate. It is also possible to include a set
 260 of pre-generated Diffie-Hellman (DH) parameters in a file
 261 ``dh-params.pem``, which can be created using the
 262 ``certtool --generate-dh-params`` command. If omitted, QEMU will
 263 dynamically generate DH parameters when loading the credentials.
 264
 265 The ``endpoint`` parameter indicates whether the credentials will be
 266 used for a network client or server, and determines which PEM files are
 267 loaded.
 268
 269 The ``verify`` parameter determines whether x509 certificate validation
 270 should be performed. This defaults to enabled, meaning clients will
 271 always validate the server hostname against the certificate subject alt
 272 name fields and/or CN field. It also means that servers will request
 273 that clients provide a certificate and validate them. Verification
 274 should never be turned off for client endpoints, however, it may be
 275 turned off for server endpoints if an alternative mechanism is used to
 276 authenticate clients. For example, the VNC server can use SASL to
 277 authenticate clients instead.
 278
 279 To load server credentials with client certificate validation enabled
 280
 281 .. parsed-literal::
 282
 283    |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
 284
 285 while to load client credentials use
 286
 287 .. parsed-literal::
 288
 289    |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
 290
 291 Network services which support TLS will all have a ``tls-creds``
 292 parameter which expects the ID of the TLS credentials object. For
 293 example with VNC:
 294
 295 .. parsed-literal::
 296
 297    |qemu_system| -vnc 0.0.0.0:0,tls-creds=tls0
 298
 299 .. _tls_005fpsk:
 300
 301 TLS Pre-Shared Keys (PSK)
 302 ~~~~~~~~~~~~~~~~~~~~~~~~~
 303
 304 Instead of using certificates, you may also use TLS Pre-Shared Keys
 305 (TLS-PSK). This can be simpler to set up than certificates but is less
 306 scalable.
 307
 308 Use the GnuTLS ``psktool`` program to generate a ``keys.psk`` file
 309 containing one or more usernames and random keys::
 310
 311    mkdir -m 0700 /tmp/keys
 312    psktool -u rich -p /tmp/keys/keys.psk
 313
 314 TLS-enabled servers such as qemu-nbd can use this directory like so::
 315
 316    qemu-nbd \
 317      -t -x / \
 318      --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
 319      --tls-creds tls0 \
 320      image.qcow2
 321
 322 When connecting from a qemu-based client you must specify the directory
 323 containing ``keys.psk`` and an optional username (defaults to "qemu")::
 324
 325    qemu-img info \
 326      --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
 327      --image-opts \
 328      file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/