stubs: Move qemu_timer_notify_cb() and remove qemu_notify_event() stub
[qemu.git] / 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=/