NuKVM/libvirt
3
0
Fork 0
mirror of https://github.com/libvirt/libvirt.git synced 2026-08-02 09:29:35 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: describe support for multiple certs & PQC config

Browse Source 
This describes the new index based certificate naming scheme, and
how to create & deploy certificates for post-quantum cryptography.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Daniel P. Berrangé
2025-11-24 15:05:09 +00:00
parent 59a65f4987
commit dac28c6185
1 changed files with 88 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/kbase/tlscerts.rst
+88
View File
@@ -75,6 +75,25 @@ in the path specified, otherwise the connection will fail with a fatal error. If
- For the root user, the global default locations will always be used.
Multiple parallel certificate identities
----------------------------------------
Any scenario that requires a certificate identify (``servercert.pem`` /
``serverkey.pem`` and ``clientcert.pem`` / ``clientkey.pem``) can optionally
provide multiple parallel identities via a new indexed file naming
scheme. The new filenames are ``servercertNN.pem`` / ``serverkeyNN.pem``
and ``clientcertNN.pem`` / ``clientkeyNN.pem``, for values of ``NN`` between
0 and 3 inclusive.
The new naming can be used instead of the old naming, or concurrently
with the old naming. The old file names will be loaded first (if
present), followed by the indexed file names. Loading will stop at
the first missing index value. ie if ``servercert1.pem`` is not present,
then no attempt will be made to load ``servercert2.pem`` or ``servercert3.pem``.
If multiple CA certificates are required they must all be concatenated
into the single ``cacert.pem`` file.
Background to TLS certificates
------------------------------
@@ -326,6 +345,75 @@ briefly cover the steps.
cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
cp clientcert.pem /etc/pki/libvirt/clientcert.pem
Configuring for Post-Quantum Cryptography
-----------------------------------------
Given a new enough gnutls release, suitably integrated & configured with the
operating system crypto policies, libvirt is able to support post-quantum
crytography on TLS enabled services, either exclusively or in a hybrid mode.
In exclusive mode, only a single set of certificates need to be configured
for libvirt, with PQC compliant algorithms. Such a libvirt configuration will
only be able to interoperate with other libvirt daemons that also have PQC
enabled. This can result in compatibility concerns during the period of
transition over to PQC compliant algorithms.
In hybrid mode, multiple sets of certificates need to be configured for libvirt,
at least one set with traditional (non-PQC compliant) algorithms, and at least
one other set with modern (PQC compliant) algorithms. At time of the TLS
handshake, the GNUTLS algorithm priorities should ensure that PQC compliant
algorithms are negotiated if both sides of the connection support PQC. If one
side lacks PQC, the TLS handshake should fallback to the non-PQC algorithms.
This can assist with interoperability during the transition to PQC, but has a
potential weakness wrt downgrade attacks forcing use of non-PQC algorithms.
Exclusive PQC mode should be preferred where both peers in the TLS connections
are known to support PQC.
Key generation parameters
^^^^^^^^^^^^^^^^^^^^^^^^^
To create certificates with PQC compliant algorithms, the ``--key-type``
argument must be passed to ``certtool`` when creating private keys. No
extra arguments are required for the other ``certtool`` commands, as
their behaviour will be determined by the private key type.
The typical PQC compliant algorithms to use are ``ML-DSA-44``, ``ML-DSA-65``
and ``ML-DSA-87``, with ``ML-DSA-65`` being a suitable default choice in
the absence of explicit requirements.
Taking the example earlier, for creating a key for a client certificate,
to use ``ML-DSA-65`` the command line would be modified to look like::
# certtool --generate-privkey --key-type=mldsa65 > clientkey.pem
The equivalent modification applies to the creation of the private keys
used for server certs, or root/intermediate CA certs.
For hybrid mode, the additional indexed certificate naming must be used.
If multiple configured certificates are compatible with the mutually
supported crypto algorithms between the client and server, then the
first matching certificate will be used.
IOW, to ensure that PQC certificates are preferred, they must use a
non-index based filename, or use an index that is smaller than any
non-PQC certificates. ie, ``servercert.pem`` for PQC and ``servercert0.pem``
for non-PQC, or ``servercert0.pem`` for PQC and ``servercert1.pem`` for
non-PQC.
Force disabling PQC via crypto priority
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the OS configuration for system crypto algorithm priorities has
enabled PQC, this can (optionally) be overriden in libvirt server
configuration. To disable use of PQC set the ``tls_priority``
parameter in the ``libvirtd.conf`` / ``virtproxyd.conf`` files:
tls_priority = "@SYSTEM:-SIGN-ML-DSA-65:-SIGN-ML-DSA-44:-SIGN-ML-DSA-87:-GROUP-X25519-MLKEM768:-GROUP-SECP256R1-MLKEM768:-GROUP-SECP384R1-MLKEM1024"
On the client side this can be overriden using the ``tls_priority``
URI parameter in the libvirt connection address.
Troubleshooting TLS certificate problems
----------------------------------------