On Fri, Dec 08, 2017 at 10:16:50AM -0600, Eric Blake wrote:
> 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/
This is just a moved block of pre-existing text, and since expanding the
abbrev would cause reformatting of line breaks, I'll not change this.
> > +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.
Since the QEMU -help text only mentions the single dash format, I'll
stick with that.
Perhaps though, we should change the -help text (and all docs) to always
use double dash format so we're consistent across QEMU codebase, and more
normal CLI arg syntax for long options ?
>
> > +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/
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
