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

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 4799 bytes --]

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/

> +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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]