One Hat Cyber Team
Your IP :
216.73.216.115
Server IP :
194.44.31.54
Server :
Linux zen.imath.kiev.ua 4.18.0-553.77.1.el8_10.x86_64 #1 SMP Fri Oct 3 14:30:23 UTC 2025 x86_64
Server Software :
Apache/2.4.37 (Rocky Linux) OpenSSL/1.1.1k
PHP Version :
5.6.40
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
doc
/
qemu-kvm
/
system
/
View File Name :
tls.html
<!DOCTYPE html> <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>TLS setup for network services — QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title> <link rel="shortcut icon" href="../_static/qemu_32x32.png"/> <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Providing secret data to QEMU" href="secrets.html" /> <link rel="prev" title="VNC security" href="vnc-security.html" /> <script src="../_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="../index.html" class="icon icon-home"> QEMU <img src="../_static/qemu_128x128.png" class="logo" alt="Logo"/> </a> <div class="version"> 6.2.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <p class="caption"><span class="caption-text">Contents:</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li> <li class="toctree-l1 current"><a class="reference internal" href="index.html">System Emulation</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick Start</a></li> <li class="toctree-l2"><a class="reference internal" href="invocation.html">Invocation</a></li> <li class="toctree-l2"><a class="reference internal" href="device-emulation.html">Device Emulation</a></li> <li class="toctree-l2"><a class="reference internal" href="keys.html">Keys in the graphical frontends</a></li> <li class="toctree-l2"><a class="reference internal" href="mux-chardev.html">Keys in the character backend multiplexer</a></li> <li class="toctree-l2"><a class="reference internal" href="monitor.html">QEMU Monitor</a></li> <li class="toctree-l2"><a class="reference internal" href="images.html">Disk Images</a></li> <li class="toctree-l2"><a class="reference internal" href="virtio-net-failover.html">QEMU virtio-net standby (net_failover)</a></li> <li class="toctree-l2"><a class="reference internal" href="linuxboot.html">Direct Linux Boot</a></li> <li class="toctree-l2"><a class="reference internal" href="generic-loader.html">Generic Loader</a></li> <li class="toctree-l2"><a class="reference internal" href="guest-loader.html">Guest Loader</a></li> <li class="toctree-l2"><a class="reference internal" href="barrier.html">QEMU Barrier Client</a></li> <li class="toctree-l2"><a class="reference internal" href="vnc-security.html">VNC security</a></li> <li class="toctree-l2 current"><a class="current reference internal" href="#">TLS setup for network services</a><ul> <li class="toctree-l3"><a class="reference internal" href="#setup-the-certificate-authority">Setup the Certificate Authority</a></li> <li class="toctree-l3"><a class="reference internal" href="#issuing-server-certificates">Issuing server certificates</a></li> <li class="toctree-l3"><a class="reference internal" href="#issuing-client-certificates">Issuing client certificates</a></li> <li class="toctree-l3"><a class="reference internal" href="#tls-x509-credential-configuration">TLS x509 credential configuration</a></li> <li class="toctree-l3"><a class="reference internal" href="#tls-pre-shared-keys-psk">TLS Pre-Shared Keys (PSK)</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="secrets.html">Providing secret data to QEMU</a></li> <li class="toctree-l2"><a class="reference internal" href="authz.html">Client authorization</a></li> <li class="toctree-l2"><a class="reference internal" href="gdb.html">GDB usage</a></li> <li class="toctree-l2"><a class="reference internal" href="managed-startup.html">Managed start up options</a></li> <li class="toctree-l2"><a class="reference internal" href="bootindex.html">Managing device boot order with bootindex properties</a></li> <li class="toctree-l2"><a class="reference internal" href="cpu-hotplug.html">Virtual CPU hotplug</a></li> <li class="toctree-l2"><a class="reference internal" href="pr-manager.html">Persistent reservation managers</a></li> <li class="toctree-l2"><a class="reference internal" href="targets.html">QEMU System Emulator Targets</a></li> <li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li> <li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li> <li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li> <li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></li> <li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li> <li class="toctree-l1"><a class="reference internal" href="../devel/index.html">Developer Information</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="../index.html">QEMU</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html">Docs</a> »</li> <li><a href="index.html">System Emulation</a> »</li> <li>TLS setup for network services</li> <li class="wy-breadcrumbs-aside"> <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/system/tls.rst" class="fa fa-gitlab"> Edit on GitLab</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="tls-setup-for-network-services"> <span id="network-005ftls"></span><h1>TLS setup for network services<a class="headerlink" href="#tls-setup-for-network-services" title="Permalink to this headline">¶</a></h1> <p>Almost all network services in QEMU have the ability to use TLS for session data encryption, along with x509 certificates for simple client authentication. What follows is a description of how to generate certificates suitable for usage with QEMU, and applies to the VNC server, character devices with the TCP backend, NBD server and client, and migration server and client.</p> <p>At a high level, QEMU requires certificates and private keys to be provided in PEM format. Aside from the core fields, the certificates should include various extension data sets, including v3 basic constraints data, key purpose, key usage and subject alt name.</p> <p>The GnuTLS package includes a command called <code class="docutils literal notranslate"><span class="pre">certtool</span></code> which can be used to easily generate certificates and keys in the required format with expected data present. Alternatively a certificate management service may be used.</p> <p>At a minimum it is necessary to setup a certificate authority, and issue certificates to each server. If using x509 certificates for authentication, then each client will also need to be issued a certificate.</p> <p>Assuming that the QEMU network services will only ever be exposed to clients on a private intranet, there is no need to use a commercial certificate authority to create certificates. A self-signed CA is sufficient, and in fact likely to be more secure since it removes the ability of malicious 3rd parties to trick the CA into mis-issuing certs for impersonating your services. The only likely exception where a commercial CA might be desirable is if enabling the VNC websockets server and exposing it directly to remote browser clients. In such a case it might be useful to use a commercial CA to avoid needing to install custom CA certs in the web browsers.</p> <p>The recommendation is for the server to keep its certificates in either <code class="docutils literal notranslate"><span class="pre">/etc/pki/qemu</span></code> or for unprivileged users in <code class="docutils literal notranslate"><span class="pre">$HOME/.pki/qemu</span></code>.</p> <div class="section" id="setup-the-certificate-authority"> <span id="tls-005fgenerate-005fca"></span><h2>Setup the Certificate Authority<a class="headerlink" href="#setup-the-certificate-authority" title="Permalink to this headline">¶</a></h2> <p>This step only needs to be performed once per organization / organizational unit. First the CA needs a private key. This key must be kept VERY secret and secure. If this key is compromised the entire trust chain of the certificates issued with it is lost.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># certtool --generate-privkey > ca-key.pem</span> </pre></div> </div> <p>To generate a self-signed certificate requires one core piece of information, the name of the organization. A template file <code class="docutils literal notranslate"><span class="pre">ca.info</span></code> should be populated with the desired data to avoid having to deal with interactive prompts from certtool:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># cat > ca.info <<EOF</span> <span class="n">cn</span> <span class="o">=</span> <span class="n">Name</span> <span class="n">of</span> <span class="n">your</span> <span class="n">organization</span> <span class="n">ca</span> <span class="n">cert_signing_key</span> <span class="n">EOF</span> <span class="c1"># certtool --generate-self-signed \</span> <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">privkey</span> <span class="n">ca</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">template</span> <span class="n">ca</span><span class="o">.</span><span class="n">info</span> \ <span class="o">--</span><span class="n">outfile</span> <span class="n">ca</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">ca</span></code> keyword in the template sets the v3 basic constraints extension to indicate this certificate is for a CA, while <code class="docutils literal notranslate"><span class="pre">cert_signing_key</span></code> sets the key usage extension to indicate this will be used for signing other keys. The generated <code class="docutils literal notranslate"><span class="pre">ca-cert.pem</span></code> file should be copied to all servers and clients wishing to utilize TLS support in the VNC server. The <code class="docutils literal notranslate"><span class="pre">ca-key.pem</span></code> must not be disclosed/copied anywhere except the host responsible for issuing certificates.</p> </div> <div class="section" id="issuing-server-certificates"> <span id="tls-005fgenerate-005fserver"></span><h2>Issuing server certificates<a class="headerlink" href="#issuing-server-certificates" title="Permalink to this headline">¶</a></h2> <p>Each server (or host) needs to be issued with a key and certificate. When connecting the certificate is sent to the client which validates it against the CA certificate. The core pieces of information for a server certificate are the hostnames and/or IP addresses that will be used by clients when connecting. The hostname / IP address that the client specifies when connecting will be validated against the hostname(s) and IP address(es) recorded in the server certificate, and if no match is found the client will close the connection.</p> <p>Thus it is recommended that the server certificate include both the fully qualified and unqualified hostnames. If the server will have permanently assigned IP address(es), and clients are likely to use them when connecting, they may also be included in the certificate. Both IPv4 and IPv6 addresses are supported. Historically certificates only included 1 hostname in the <code class="docutils literal notranslate"><span class="pre">CN</span></code> field, however, usage of this field for validation is now deprecated. Instead modern TLS clients will validate against the Subject Alt Name extension data, which allows for multiple entries. In the future usage of the <code class="docutils literal notranslate"><span class="pre">CN</span></code> field may be discontinued entirely, so providing SAN extension data is strongly recommended.</p> <p>On the host holding the CA, create template files containing the information for each server, and use it to issue server certificates.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># cat > server-hostNNN.info <<EOF</span> <span class="n">organization</span> <span class="o">=</span> <span class="n">Name</span> <span class="n">of</span> <span class="n">your</span> <span class="n">organization</span> <span class="n">cn</span> <span class="o">=</span> <span class="n">hostNNN</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="n">dns_name</span> <span class="o">=</span> <span class="n">hostNNN</span> <span class="n">dns_name</span> <span class="o">=</span> <span class="n">hostNNN</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mf">10.0</span><span class="o">.</span><span class="mf">1.87</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mf">192.8</span><span class="o">.</span><span class="mf">0.92</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mi">2620</span><span class="p">:</span><span class="mi">0</span><span class="p">:</span><span class="n">cafe</span><span class="p">::</span><span class="mi">87</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mi">2001</span><span class="p">:</span><span class="mi">24</span><span class="p">::</span><span class="mi">92</span> <span class="n">tls_www_server</span> <span class="n">encryption_key</span> <span class="n">signing_key</span> <span class="n">EOF</span> <span class="c1"># certtool --generate-privkey > server-hostNNN-key.pem</span> <span class="c1"># certtool --generate-certificate \</span> <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">certificate</span> <span class="n">ca</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">privkey</span> <span class="n">ca</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">privkey</span> <span class="n">server</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">template</span> <span class="n">server</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">.</span><span class="n">info</span> \ <span class="o">--</span><span class="n">outfile</span> <span class="n">server</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">dns_name</span></code> and <code class="docutils literal notranslate"><span class="pre">ip_address</span></code> fields in the template are setting the subject alt name extension data. The <code class="docutils literal notranslate"><span class="pre">tls_www_server</span></code> keyword is the key purpose extension to indicate this certificate is intended for usage in a web server. Although QEMU network services are not in fact HTTP servers (except for VNC websockets), setting this key purpose is still recommended. The <code class="docutils literal notranslate"><span class="pre">encryption_key</span></code> and <code class="docutils literal notranslate"><span class="pre">signing_key</span></code> keyword is the key usage extension to indicate this certificate is intended for usage in the data session.</p> <p>The <code class="docutils literal notranslate"><span class="pre">server-hostNNN-key.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">server-hostNNN-cert.pem</span></code> files should now be securely copied to the server for which they were generated, and renamed to <code class="docutils literal notranslate"><span class="pre">server-key.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">server-cert.pem</span></code> when added to the <code class="docutils literal notranslate"><span class="pre">/etc/pki/qemu</span></code> directory on the target host. The <code class="docutils literal notranslate"><span class="pre">server-key.pem</span></code> file is security sensitive and should be kept protected with file mode 0600 to prevent disclosure.</p> </div> <div class="section" id="issuing-client-certificates"> <span id="tls-005fgenerate-005fclient"></span><h2>Issuing client certificates<a class="headerlink" href="#issuing-client-certificates" title="Permalink to this headline">¶</a></h2> <p>The QEMU x509 TLS credential setup defaults to enabling client verification using certificates, providing a simple authentication mechanism. If this default is used, each client also needs to be issued a certificate. The client certificate contains enough metadata to uniquely identify the client with the scope of the certificate authority. The client certificate would typically include fields for organization, state, city, building, etc.</p> <p>Once again on the host holding the CA, create template files containing the information for each client, and use it to issue client certificates.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># cat > client-hostNNN.info <<EOF</span> <span class="n">country</span> <span class="o">=</span> <span class="n">GB</span> <span class="n">state</span> <span class="o">=</span> <span class="n">London</span> <span class="n">locality</span> <span class="o">=</span> <span class="n">City</span> <span class="n">Of</span> <span class="n">London</span> <span class="n">organization</span> <span class="o">=</span> <span class="n">Name</span> <span class="n">of</span> <span class="n">your</span> <span class="n">organization</span> <span class="n">cn</span> <span class="o">=</span> <span class="n">hostNNN</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="n">tls_www_client</span> <span class="n">encryption_key</span> <span class="n">signing_key</span> <span class="n">EOF</span> <span class="c1"># certtool --generate-privkey > client-hostNNN-key.pem</span> <span class="c1"># certtool --generate-certificate \</span> <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">certificate</span> <span class="n">ca</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">privkey</span> <span class="n">ca</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">privkey</span> <span class="n">client</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">template</span> <span class="n">client</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">.</span><span class="n">info</span> \ <span class="o">--</span><span class="n">outfile</span> <span class="n">client</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> </pre></div> </div> <p>The subject alt name extension data is not required for clients, so the the <code class="docutils literal notranslate"><span class="pre">dns_name</span></code> and <code class="docutils literal notranslate"><span class="pre">ip_address</span></code> fields are not included. The <code class="docutils literal notranslate"><span class="pre">tls_www_client</span></code> keyword is the key purpose extension to indicate this certificate is intended for usage in a web client. Although QEMU network clients are not in fact HTTP clients, setting this key purpose is still recommended. The <code class="docutils literal notranslate"><span class="pre">encryption_key</span></code> and <code class="docutils literal notranslate"><span class="pre">signing_key</span></code> keyword is the key usage extension to indicate this certificate is intended for usage in the data session.</p> <p>The <code class="docutils literal notranslate"><span class="pre">client-hostNNN-key.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">client-hostNNN-cert.pem</span></code> files should now be securely copied to the client for which they were generated, and renamed to <code class="docutils literal notranslate"><span class="pre">client-key.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">client-cert.pem</span></code> when added to the <code class="docutils literal notranslate"><span class="pre">/etc/pki/qemu</span></code> directory on the target host. The <code class="docutils literal notranslate"><span class="pre">client-key.pem</span></code> file is security sensitive and should be kept protected with file mode 0600 to prevent disclosure.</p> <p>If a single host is going to be using TLS in both a client and server role, it is possible to create a single certificate to cover both roles. This would be quite common for the migration and NBD services, where a QEMU process will be started by accepting a TLS protected incoming migration, and later itself be migrated out to another host. To generate a single certificate, simply include the template data from both the client and server instructions in one.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># cat > both-hostNNN.info <<EOF</span> <span class="n">country</span> <span class="o">=</span> <span class="n">GB</span> <span class="n">state</span> <span class="o">=</span> <span class="n">London</span> <span class="n">locality</span> <span class="o">=</span> <span class="n">City</span> <span class="n">Of</span> <span class="n">London</span> <span class="n">organization</span> <span class="o">=</span> <span class="n">Name</span> <span class="n">of</span> <span class="n">your</span> <span class="n">organization</span> <span class="n">cn</span> <span class="o">=</span> <span class="n">hostNNN</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="n">dns_name</span> <span class="o">=</span> <span class="n">hostNNN</span> <span class="n">dns_name</span> <span class="o">=</span> <span class="n">hostNNN</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mf">10.0</span><span class="o">.</span><span class="mf">1.87</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mf">192.8</span><span class="o">.</span><span class="mf">0.92</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mi">2620</span><span class="p">:</span><span class="mi">0</span><span class="p">:</span><span class="n">cafe</span><span class="p">::</span><span class="mi">87</span> <span class="n">ip_address</span> <span class="o">=</span> <span class="mi">2001</span><span class="p">:</span><span class="mi">24</span><span class="p">::</span><span class="mi">92</span> <span class="n">tls_www_server</span> <span class="n">tls_www_client</span> <span class="n">encryption_key</span> <span class="n">signing_key</span> <span class="n">EOF</span> <span class="c1"># certtool --generate-privkey > both-hostNNN-key.pem</span> <span class="c1"># certtool --generate-certificate \</span> <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">certificate</span> <span class="n">ca</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">privkey</span> <span class="n">ca</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">load</span><span class="o">-</span><span class="n">privkey</span> <span class="n">both</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">key</span><span class="o">.</span><span class="n">pem</span> \ <span class="o">--</span><span class="n">template</span> <span class="n">both</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">.</span><span class="n">info</span> \ <span class="o">--</span><span class="n">outfile</span> <span class="n">both</span><span class="o">-</span><span class="n">hostNNN</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span> </pre></div> </div> <p>When copying the PEM files to the target host, save them twice, once as <code class="docutils literal notranslate"><span class="pre">server-cert.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">server-key.pem</span></code>, and again as <code class="docutils literal notranslate"><span class="pre">client-cert.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">client-key.pem</span></code>.</p> </div> <div class="section" id="tls-x509-credential-configuration"> <span id="tls-005fcreds-005fsetup"></span><h2>TLS x509 credential configuration<a class="headerlink" href="#tls-x509-credential-configuration" title="Permalink to this headline">¶</a></h2> <p>QEMU has a standard mechanism for loading x509 credentials that will be used for network services and clients. It requires specifying the <code class="docutils literal notranslate"><span class="pre">tls-creds-x509</span></code> class name to the <code class="docutils literal notranslate"><span class="pre">--object</span></code> command line argument for the system emulators. Each set of credentials loaded should be given a unique string identifier via the <code class="docutils literal notranslate"><span class="pre">id</span></code> parameter. A single set of TLS credentials can be used for multiple network backends, so VNC, migration, NBD, character devices can all share the same credentials. Note, however, that credentials for use in a client endpoint must be loaded separately from those used in a server endpoint.</p> <p>When specifying the object, the <code class="docutils literal notranslate"><span class="pre">dir</span></code> parameters specifies which directory contains the credential files. This directory is expected to contain files with the names mentioned previously, <code class="docutils literal notranslate"><span class="pre">ca-cert.pem</span></code>, <code class="docutils literal notranslate"><span class="pre">server-key.pem</span></code>, <code class="docutils literal notranslate"><span class="pre">server-cert.pem</span></code>, <code class="docutils literal notranslate"><span class="pre">client-key.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">client-cert.pem</span></code> as appropriate. It is also possible to include a set of pre-generated Diffie-Hellman (DH) parameters in a file <code class="docutils literal notranslate"><span class="pre">dh-params.pem</span></code>, which can be created using the <code class="docutils literal notranslate"><span class="pre">certtool</span> <span class="pre">--generate-dh-params</span></code> command. If omitted, QEMU will dynamically generate DH parameters when loading the credentials.</p> <p>The <code class="docutils literal notranslate"><span class="pre">endpoint</span></code> parameter indicates whether the credentials will be used for a network client or server, and determines which PEM files are loaded.</p> <p>The <code class="docutils literal notranslate"><span class="pre">verify</span></code> parameter determines whether x509 certificate validation should be performed. This defaults to enabled, meaning clients will always validate the server hostname against the certificate subject alt name fields and/or CN field. It also means that servers will request that clients provide a certificate and validate them. Verification should never be turned off for client endpoints, however, it may be turned off for server endpoints if an alternative mechanism is used to authenticate clients. For example, the VNC server can use SASL to authenticate clients instead.</p> <p>To load server credentials with client certificate validation enabled</p> <pre class="literal-block"> qemu-kvm -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server </pre> <p>while to load client credentials use</p> <pre class="literal-block"> qemu-kvm -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client </pre> <p>Network services which support TLS will all have a <code class="docutils literal notranslate"><span class="pre">tls-creds</span></code> parameter which expects the ID of the TLS credentials object. For example with VNC:</p> <pre class="literal-block"> qemu-kvm -vnc 0.0.0.0:0,tls-creds=tls0 </pre> </div> <div class="section" id="tls-pre-shared-keys-psk"> <span id="tls-005fpsk"></span><h2>TLS Pre-Shared Keys (PSK)<a class="headerlink" href="#tls-pre-shared-keys-psk" title="Permalink to this headline">¶</a></h2> <p>Instead of using certificates, you may also use TLS Pre-Shared Keys (TLS-PSK). This can be simpler to set up than certificates but is less scalable.</p> <p>Use the GnuTLS <code class="docutils literal notranslate"><span class="pre">psktool</span></code> program to generate a <code class="docutils literal notranslate"><span class="pre">keys.psk</span></code> file containing one or more usernames and random keys:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="o">-</span><span class="n">m</span> <span class="mi">0700</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">keys</span> <span class="n">psktool</span> <span class="o">-</span><span class="n">u</span> <span class="n">rich</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">keys</span><span class="o">/</span><span class="n">keys</span><span class="o">.</span><span class="n">psk</span> </pre></div> </div> <p>TLS-enabled servers such as <code class="docutils literal notranslate"><span class="pre">qemu-nbd</span></code> can use this directory like so:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">qemu</span><span class="o">-</span><span class="n">nbd</span> \ <span class="o">-</span><span class="n">t</span> <span class="o">-</span><span class="n">x</span> <span class="o">/</span> \ <span class="o">--</span><span class="nb">object</span> <span class="n">tls</span><span class="o">-</span><span class="n">creds</span><span class="o">-</span><span class="n">psk</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">tls0</span><span class="p">,</span><span class="n">endpoint</span><span class="o">=</span><span class="n">server</span><span class="p">,</span><span class="nb">dir</span><span class="o">=/</span><span class="n">tmp</span><span class="o">/</span><span class="n">keys</span> \ <span class="o">--</span><span class="n">tls</span><span class="o">-</span><span class="n">creds</span> <span class="n">tls0</span> \ <span class="n">image</span><span class="o">.</span><span class="n">qcow2</span> </pre></div> </div> <p>When connecting from a qemu-based client you must specify the directory containing <code class="docutils literal notranslate"><span class="pre">keys.psk</span></code> and an optional username (defaults to “qemu”):</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">qemu</span><span class="o">-</span><span class="n">img</span> <span class="n">info</span> \ <span class="o">--</span><span class="nb">object</span> <span class="n">tls</span><span class="o">-</span><span class="n">creds</span><span class="o">-</span><span class="n">psk</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">tls0</span><span class="p">,</span><span class="nb">dir</span><span class="o">=/</span><span class="n">tmp</span><span class="o">/</span><span class="n">keys</span><span class="p">,</span><span class="n">username</span><span class="o">=</span><span class="n">rich</span><span class="p">,</span><span class="n">endpoint</span><span class="o">=</span><span class="n">client</span> \ <span class="o">--</span><span class="n">image</span><span class="o">-</span><span class="n">opts</span> \ <span class="n">file</span><span class="o">.</span><span class="n">driver</span><span class="o">=</span><span class="n">nbd</span><span class="p">,</span><span class="n">file</span><span class="o">.</span><span class="n">host</span><span class="o">=</span><span class="n">localhost</span><span class="p">,</span><span class="n">file</span><span class="o">.</span><span class="n">port</span><span class="o">=</span><span class="mi">10809</span><span class="p">,</span><span class="n">file</span><span class="o">.</span><span class="n">tls</span><span class="o">-</span><span class="n">creds</span><span class="o">=</span><span class="n">tls0</span><span class="p">,</span><span class="n">file</span><span class="o">.</span><span class="n">export</span><span class="o">=/</span> </pre></div> </div> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="secrets.html" class="btn btn-neutral float-right" title="Providing secret data to QEMU" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a> <a href="vnc-security.html" class="btn btn-neutral" title="VNC security" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p> © Copyright 2021, The QEMU Project Developers. </p> </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. <!-- Empty para to force a blank line after "Built with Sphinx ..." --> <p></p> <p>This documentation is for QEMU version 6.2.0.</p> <p><a href="../about/license.html">QEMU and this manual are released under the GNU General Public License, version 2.</a></p> </footer> </div> </div> </section> </div> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT:'../', VERSION:'qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4', LANGUAGE:'None', COLLAPSE_INDEX:false, FILE_SUFFIX:'.html', HAS_SOURCE: false, SOURCELINK_SUFFIX: '.txt' }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/js/theme.js"></script> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>