Re: [Qemu-devel] [PATCH] docs: update information for TLS certificate management

["Daniel P. Berrange" <berrange@redhat.com>]

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 <berrange@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 :|