docs/system/tls.rst

3 TLS setup for network services
4 ------------------------------
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
13 At a high level, QEMU requires certificates and private keys to be
23 At a minimum it is necessary to setup a certificate authority, and issue
28 Assuming that the QEMU network services will only ever be exposed to
30 certificate authority to create certificates. A self-signed CA is
32 ability of malicious 3rd parties to trick the CA into mis-issuing certs
40 ``/etc/pki/qemu`` or for unprivileged users in ``$HOME/.pki/qemu``.
44 Setup the Certificate Authority
54    # certtool --generate-privkey > ca-key.pem
56 To generate a self-signed certificate requires one core piece of
66    # certtool --generate-self-signed \
67               --load-privkey ca-key.pem \
68               --template ca.info \
69               --outfile ca-cert.pem
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
111    # cat > server-hostNNN.info <<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
135 usage in a web server. Although QEMU network services are not in fact
141 The ``server-hostNNN-key.pem`` and ``server-hostNNN-cert.pem`` files
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
153 The QEMU x509 TLS credential setup defaults to enabling client
167    # cat > client-hostNNN.info <<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
188 certificate is intended for usage in a web client. Although QEMU network
194 The ``client-hostNNN-key.pem`` and ``client-hostNNN-cert.pem`` files
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
204 QEMU process will be started by accepting a TLS protected incoming
211    # cat > both-hostNNN.info <<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
237 ``server-cert.pem`` and ``server-key.pem``, and again as
238 ``client-cert.pem`` and ``client-key.pem``.
245 QEMU has a standard mechanism for loading x509 credentials that will be
247 ``tls-creds-x509`` class name to the ``--object`` command line argument
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
281 .. parsed-literal::
283    |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
287 .. parsed-literal::
289    |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
291 Network services which support TLS will all have a ``tls-creds``
295 .. parsed-literal::
297    |qemu_system| -vnc 0.0.0.0:0,tls-creds=tls0
301 TLS Pre-Shared Keys (PSK)
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
311    mkdir -m 0700 /tmp/keys
312    psktool -u rich -p /tmp/keys/keys.psk
314 TLS-enabled servers such as ``qemu-nbd`` can use this directory like so::
316    qemu-nbd \
317      -t -x / \
318      --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
319      --tls-creds tls0 \
322 When connecting from a qemu-based client you must specify the directory
323 containing ``keys.psk`` and an optional username (defaults to "qemu")::
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=/