On 12/08/2017 05:58 AM, Daniel P. Berrange wrote: > The current docs for TLS assume only VNC is using TLS. Some of the information > is also outdated (ie lacking subject alt name info for certs). Rewrite it to > more accurately reflect the current situation. > > Signed-off-by: Daniel P. Berrange <berra...@redhat.com> > --- > qemu-doc.texi | 368 > +++++++++++++++++++++++++++++++++++++++++++--------------- > 1 file changed, 275 insertions(+), 93 deletions(-) >
> +@subsection Configuring SASL mechanisms
> +
> +The following documentation assumes use of the Cyrus SASL implementation on a
> +Linux host, but the principals should apply to any other SASL impl. When SASL
s/impl/implementation/
> +is enabled, the mechanism configuration will be loaded from system default
> +SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
> +unprivileged user, an environment variable SASL_CONF_PATH can be used
> +to make it search alternate locations for the service config.
> +
> +@node tls_generate_server
> +@subsection Issuing server certificates
>
> 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 piece of information for a server certificate is the hostname. This
> should
> -be the fully qualified hostname that the client will connect with, since the
> client
> -will typically also verify the hostname in the certificate. On the host
> holding the
> -secure CA private key:
> +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 aganist the
> hostname(s)
s/aganist/against/
> +and IP address(es) recorded in the server certificate, and if no match is
> found
> +the client will close the connection.
> +
> +Thus it is recommended that the server certificate include both the fully
> qualfied
s/qualfied/qualified/
> +
> +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 be start by accepting a TLS protected incoming migration, and later
s/QEMU be start/QEMU process will be started/
> +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.
>
>
> -When not using TLS the recommended configuration is
> +When copying the PEM files to the target host, save them twice
> +once as @code{server-cert.pem} and @code{server-key.pem}, and
s/twice/twice,/
> +against as @code{client-cert.pem} and @code{client-key.pem}.
s/against/again/
> +
> +@node tls_creds_setup
> +@subsection TLS x509 credential configuration
> +
> +QEMU has a standard mechanism for loading x509 credentials that will be
> +used for network services and clients. It requires specifying the
> +@code{tls-creds-x509} class name to the @code{-object} command line
> +argument for the system emulators. This also works for the helper tools
> +like @code{qemu-nbd} and @code{qemu-img}, but is named @code{--object}.
You can use '--object' with qemu as well (getopt_long_only() accepts
double-dash form in addition to single dash). If it makes it any easier
to only document the double-dash form, then go for it.
> +Each set of credentials loaded should be given a unique string identifier
> +via the @code{id} 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.
> +
> +When specifying the object, the @code{dir} parameters specifies which
> +directory contains the credential files. This directory is expected to
> +contain files with the names mentioned previously, @code{ca-cert.pem},
> +@code{server-key.pem}, @code{server-cert.pem}, @code{client-key.pem}
> +and @code{client-cert.pem} as appropriate. It is also possible to
> +include a set of pre-generated diffie-hellman parameters in a file
> +@code{dh-params.pem}, which can be created using the
> +@code{certtool --generate-dh-params} command. If omitted, QEMU will
> +dynamically generated DH parameters when loading the credentials.
s/generated/generate/
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
signature.asc
Description: OpenPGP digital signature
