docs/system/tls.rst

6 Almost all network services in QEMU have the ability to use TLS for
9 certificates suitable for usage with QEMU, and applies to the VNC
10 server, character devices with the TCP backend, NBD server and client,
14 provided in PEM format. Aside from the core fields, the certificates
18 The GnuTLS package includes a command called ``certtool`` which can be
19 used to easily generate certificates and keys in the required format
28 Assuming that the QEMU network services will only ever be exposed to
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
37 install custom CA certs in the web browsers.
39 The recommendation is for the server to keep its certificates in either
44 Setup the Certificate Authority
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.
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
71 The ``ca`` keyword in the template sets the v3 basic constraints
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
76 support in the VNC server. The ``ca-key.pem`` must not be
77 disclosed/copied anywhere except the host responsible for issuing
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.
94 Thus it is recommended that the server certificate include both the
95 fully qualified and unqualified hostnames. If the server will have
97 when connecting, they may also be included in the certificate. Both IPv4
99 included 1 hostname in the ``CN`` field, however, usage of this field
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
106 On the host holding the CA, create template files containing the
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
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.
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
144 when added to the ``/etc/pki/qemu`` directory on the target host. The
153 The QEMU x509 TLS credential setup defaults to enabling client
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
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
185 The subject alt name extension data is not required for clients, so
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
190 recommended. The ``encryption_key`` and ``signing_key`` keyword is the
192 in the data session.
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
197 when added to the ``/etc/pki/qemu`` directory on the target host. The
203 This would be quite common for the migration and NBD services, where a
206 a single certificate, simply include the template data from both the
236 When copying the PEM files to the target host, save them twice, once as
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
251 migration, NBD, character devices can all share the same credentials.
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``,
261 ``dh-params.pem``, which can be created using the
263 dynamically generate DH parameters when loading the credentials.
265 The ``endpoint`` parameter indicates whether the credentials will be
269 The ``verify`` parameter determines whether x509 certificate validation
271 always validate the server hostname against the certificate subject alt
276 authenticate clients. For example, the VNC server can use SASL to
292 parameter which expects the ID of the TLS credentials object. For
308 Use the GnuTLS ``psktool`` program to generate a ``keys.psk`` file
322 When connecting from a qemu-based client you must specify the directory