xemu-project/xemu
1
0
Fork 0
mirror of https://github.com/xemu-project/xemu.git synced 2024-11-25 04:30:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

-----BEGIN PGP SIGNATURE-----

Browse Source 
iQIcBAABCAAGBQJax3YmAAoJEL6G67QVEE/fFXEQAK+6i7WYTmvX5WROLy9mTXi+
 Oykyz4RtoqWOvt8efpv81gyEFs8AJjewZWo37/zbllUhIORqqZAtuYp9Jq5K8Rw2
 1vM+wloGjXX1LDUe2ZSovcmBy29vJkSPModZGWKZyqg5CBEjmPegvUGQsq0wvLTc
 FhNO002EfFqAVH/63VjqQrfyz5VUaECUE5KUvx1+AWGvsMp5xPRYO1cskmQV4xIF
 Sq8QMqZP/1ar9DcYRz4vzeqoDY3k+zc3tYUei0RIXrXJFheT/+C317V+ALroJG21
 MK9kjTiqMkJBSi/5OLIRuWvE0mi8p7vuqttXydhCWumcq5SVERwncd/yAGNi5oQc
 jIhJ5IN+NRZjHbHs/qna1loJpwvr4c8JsDLZHxqiBBDHxT7ICwTquXwbGtSrowUR
 wcVBDNzzv9maKH7ycZnA0xB61V/Yu6KvxvCZFfH+ZMhFf46o2FYovVFHHNr4U03y
 qT08GLTB9KKnLq5u+pSrH4vnNVRIQu3nkyVSin6BqI81E3nXBGOXMwd0xvOmnZbe
 oF3ERo8LOD5TE+2H8oA5o08ryJjf6oHR7xdtV8frxc7iTkcuLR+eRV1BCuU2/u31
 HG9BQLsS8Lvyymov/nlKwJW8/Mluloe3dSzEcntCqsb/cOqZRh/tnlW0Yg8XkHbV
 PeWuIwHf6DprUQ4lO0MG
 =KVEs
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/berrange/tags/qcrypto-next-pull-request' into staging

# gpg: Signature made Fri 06 Apr 2018 14:29:10 BST
# gpg:                using RSA key BE86EBB415104FDF
# gpg: Good signature from "Daniel P. Berrange <dan@berrange.com>"
# gpg:                 aka "Daniel P. Berrange <berrange@redhat.com>"
# Primary key fingerprint: DAF3 A6FD B26B 6291 2D0E  8E3F BE86 EBB4 1510 4FDF

* remotes/berrange/tags/qcrypto-next-pull-request:
  crypto: ensure we use a predictable TLS priority setting
  docs: Document -object tls-creds-x509 priority=xxx
  docs: update information for TLS certificate management

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell 2018-04-06 17:51:20 +01:00
commit 08e173f294
4 changed files with 314 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

424
qemu-doc.texi
View File

@ -140,6 +140,7 @@ accelerator is required to use more than one host CPU for emulation.
* direct_linux_boot:: Direct Linux Boot
* pcsys_usb:: USB emulation
* vnc_security:: VNC security
* network_tls:: TLS setup for network services
* gdb_usage:: GDB usage
* pcsys_os_specific:: Target OS specific information
@end menu
@ -1041,7 +1042,6 @@ considerations depending on the deployment scenarios.
* vnc_sec_certificate_pw::
* vnc_sec_sasl::
* vnc_sec_certificate_sasl::
* vnc_generate_cert::
* vnc_setup_sasl::
@end menu
@node vnc_sec_none
@ -1161,129 +1161,16 @@ with the aforementioned TLS + x509 options:
qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
@end example
@node vnc_generate_cert
@subsection Generating certificates for VNC
The GNU TLS packages provides a command called @code{certtool} which can
be used to generate certificates and keys in PEM format. At a minimum it
is necessary to setup a certificate authority, and issue certificates to
each server. If using certificates for authentication, then each client
will also need to be issued a certificate. The recommendation is for the
server to keep its certificates in either @code{/etc/pki/qemu} or for
unprivileged users in @code{$HOME/.pki/qemu}.
@menu
* vnc_generate_ca::
* vnc_generate_server::
* vnc_generate_client::
@end menu
@node vnc_generate_ca
@subsubsection Setup the Certificate Authority
This step only needs to be performed once per organization / organizational
unit. First the CA needs a private key. This key must be kept VERY secret
and secure. If this key is compromised the entire trust chain of the certificates
issued with it is lost.
@example
# certtool --generate-privkey > ca-key.pem
@end example
A CA needs to have a public certificate. For simplicity it can be a self-signed
certificate, or one issue by a commercial certificate issuing authority. To
generate a self-signed certificate requires one core piece of information, the
name of the organization.
@example
# cat > ca.info <<EOF
cn = Name of your organization
ca
cert_signing_key
EOF
# certtool --generate-self-signed \
--load-privkey ca-key.pem
--template ca.info \
--outfile ca-cert.pem
@end example
The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
@node vnc_generate_server
@subsubsection 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:
@example
# cat > server.info <<EOF
organization = Name of your organization
cn = server.foo.example.com
tls_www_server
encryption_key
signing_key
EOF
# certtool --generate-privkey > server-key.pem
# certtool --generate-certificate \
--load-ca-certificate ca-cert.pem \
--load-ca-privkey ca-key.pem \
--load-privkey server-key.pem \
--template server.info \
--outfile server-cert.pem
@end example
The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
to the server for which they were generated. The @code{server-key.pem} is security
sensitive and should be kept protected with file mode 0600 to prevent disclosure.
@node vnc_generate_client
@subsubsection Issuing client certificates
If the QEMU VNC server is to use the @code{x509verify} option to validate client
certificates as its authentication mechanism, each client also needs to be issued
a certificate. The client certificate contains enough metadata to uniquely identify
the client, typically organization, state, city, building, etc. On the host holding
the secure CA private key:
@example
# cat > client.info <<EOF
country = GB
state = London
locality = London
organization = Name of your organization
cn = client.foo.example.com
tls_www_client
encryption_key
signing_key
EOF
# certtool --generate-privkey > client-key.pem
# certtool --generate-certificate \
--load-ca-certificate ca-cert.pem \
--load-ca-privkey ca-key.pem \
--load-privkey client-key.pem \
--template client.info \
--outfile client-cert.pem
@end example
The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
copied to the client for which they were generated.
@node vnc_setup_sasl
@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
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.
Linux host, but the principles should apply to any other SASL implementation
or host. When SASL 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 file.
If the TLS option is enabled for VNC, then it will provide session encryption,
otherwise the SASL mechanism will have to provide encryption. In the latter
@ -1318,13 +1205,306 @@ mech_list: scram-sha-1
sasldb_path: /etc/qemu/passwd.db
@end example
The saslpasswd2 program can be used to populate the passwd.db file with
accounts.
The @code{saslpasswd2} program can be used to populate the @code{passwd.db}
file with accounts.
Other SASL configurations will be left as an exercise for the reader. Note that
all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
all mechanisms, except GSSAPI, should be combined with use of TLS to ensure a
secure data channel.
@node network_tls
@section TLS setup for network services
Almost all network services in QEMU have the ability to use TLS for
session data encryption, along with x509 certificates for simple
client authentication. What follows is a description of how to
generate certificates suitable for usage with QEMU, and applies to
the VNC server, character devices with the TCP backend, NBD server
and client, and migration server and client.
At a high level, QEMU requires certificates and private keys to be
provided in PEM format. Aside from the core fields, the certificates
should include various extension data sets, including v3 basic
constraints data, key purpose, key usage and subject alt name.
The GnuTLS package includes a command called @code{certtool} which can
be used to easily generate certificates and keys in the required format
with expected data present. Alternatively a certificate management
service may be used.
At a minimum it is necessary to setup a certificate authority, and
issue certificates to each server. If using x509 certificates for
authentication, then each client will also need to be issued a
certificate.
Assuming that the QEMU network services will only ever be exposed to
clients on a private intranet, there is no need to use a commercial
certificate authority to create certificates. A self-signed CA is
sufficient, and in fact likely to be more secure since it removes
the ability of malicious 3rd parties to trick the CA into mis-issuing
certs for impersonating your services. The only likely exception
where a commercial CA might be desirable is if enabling the VNC
websockets server and exposing it directly to remote browser clients.
In such a case it might be useful to use a commercial CA to avoid
needing to install custom CA certs in the web browsers.
The recommendation is for the server to keep its certificates in either
@code{/etc/pki/qemu} or for unprivileged users in @code{$HOME/.pki/qemu}.
@menu
* tls_generate_ca::
* tls_generate_server::
* tls_generate_client::
* tls_creds_setup::
@end menu
@node tls_generate_ca
@subsection Setup the Certificate Authority
This step only needs to be performed once per organization / organizational
unit. First the CA needs a private key. This key must be kept VERY secret
and secure. If this key is compromised the entire trust chain of the certificates
issued with it is lost.
@example
# certtool --generate-privkey > ca-key.pem
@end example
To generate a self-signed certificate requires one core piece of information,
the name of the organization. A template file @code{ca.info} should be
populated with the desired data to avoid having to deal with interactive
prompts from certtool:
@example
# cat > ca.info <<EOF
cn = Name of your organization
ca
cert_signing_key
EOF
# certtool --generate-self-signed \
--load-privkey ca-key.pem
--template ca.info \
--outfile ca-cert.pem
@end example
The @code{ca} keyword in the template sets the v3 basic constraints extension
to indicate this certificate is for a CA, while @code{cert_signing_key} sets
the key usage extension to indicate this will be used for signing other keys.
The generated @code{ca-cert.pem} file should be copied to all servers and
clients wishing to utilize TLS support in the VNC server. The @code{ca-key.pem}
must not be disclosed/copied anywhere except the host responsible for issuing
certificates.
@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 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 against the hostname(s)
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 qualified
and unqualified hostnames. If the server will have permanently assigned IP address(es),
and clients are likely to use them when connecting, they may also be included in the
certificate. Both IPv4 and IPv6 addresses are supported. Historically certificates
only included 1 hostname in the @code{CN} field, however, usage of this field for
validation is now deprecated. Instead modern TLS clients will validate against the
Subject Alt Name extension data, which allows for multiple entries. In the future
usage of the @code{CN} field may be discontinued entirely, so providing SAN
extension data is strongly recommended.
On the host holding the CA, create template files containing the information
for each server, and use it to issue server certificates.
@example
# cat > server-hostNNN.info <<EOF
organization = Name of your organization
cn = hostNNN.foo.example.com
dns_name = hostNNN
dns_name = hostNNN.foo.example.com
ip_address = 10.0.1.87
ip_address = 192.8.0.92
ip_address = 2620:0:cafe::87
ip_address = 2001:24::92
tls_www_server
encryption_key
signing_key
EOF
# certtool --generate-privkey > server-hostNNN-key.pem
# certtool --generate-certificate \
--load-ca-certificate ca-cert.pem \
--load-ca-privkey ca-key.pem \
--load-privkey server-hostNNN-key.pem \
--template server-hostNNN.info \
--outfile server-hostNNN-cert.pem
@end example
The @code{dns_name} and @code{ip_address} fields in the template are setting
the subject alt name extension data. The @code{tls_www_server} keyword is the
key purpose extension to indicate this certificate is intended for usage in
a web server. Although QEMU network services are not in fact HTTP servers
(except for VNC websockets), setting this key purpose is still recommended.
The @code{encryption_key} and @code{signing_key} keyword is the key usage
extension to indicate this certificate is intended for usage in the data
session.
The @code{server-hostNNN-key.pem} and @code{server-hostNNN-cert.pem} files
should now be securely copied to the server for which they were generated,
and renamed to @code{server-key.pem} and @code{server-cert.pem} when added
to the @code{/etc/pki/qemu} directory on the target host. The @code{server-key.pem}
file is security sensitive and should be kept protected with file mode 0600
to prevent disclosure.
@node tls_generate_client
@subsection Issuing client certificates
The QEMU x509 TLS credential setup defaults to enabling client verification
using certificates, providing a simple authentication mechanism. If this
default is used, each client also needs to be issued a certificate. The client
certificate contains enough metadata to uniquely identify the client with the
scope of the certificate authority. The client certificate would typically
include fields for organization, state, city, building, etc.
Once again on the host holding the CA, create template files containing the
information for each client, and use it to issue client certificates.
@example
# cat > client-hostNNN.info <<EOF
country = GB
state = London
locality = City Of London
organization = Name of your organization
cn = hostNNN.foo.example.com
tls_www_client
encryption_key
signing_key
EOF
# certtool --generate-privkey > client-hostNNN-key.pem
# certtool --generate-certificate \
--load-ca-certificate ca-cert.pem \
--load-ca-privkey ca-key.pem \
--load-privkey client-hostNNN-key.pem \
--template client-hostNNN.info \
--outfile client-hostNNN-cert.pem
@end example
The subject alt name extension data is not required for clients, so the
the @code{dns_name} and @code{ip_address} fields are not included.
The @code{tls_www_client} keyword is the key purpose extension to indicate
this certificate is intended for usage in a web client. Although QEMU
network clients are not in fact HTTP clients, setting this key purpose is
still recommended. The @code{encryption_key} and @code{signing_key} keyword
is the key usage extension to indicate this certificate is intended for
usage in the data session.
The @code{client-hostNNN-key.pem} and @code{client-hostNNN-cert.pem} files
should now be securely copied to the client for which they were generated,
and renamed to @code{client-key.pem} and @code{client-cert.pem} when added
to the @code{/etc/pki/qemu} directory on the target host. The @code{client-key.pem}
file is security sensitive and should be kept protected with file mode 0600
to prevent disclosure.
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 process will be started by accepting a TLS protected incoming migration,
and later 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.
@example
# cat > both-hostNNN.info <<EOF
country = GB
state = London
locality = City Of London
organization = Name of your organization
cn = hostNNN.foo.example.com
dns_name = hostNNN
dns_name = hostNNN.foo.example.com
ip_address = 10.0.1.87
ip_address = 192.8.0.92
ip_address = 2620:0:cafe::87
ip_address = 2001:24::92
tls_www_server
tls_www_client
encryption_key
signing_key
EOF
# certtool --generate-privkey > both-hostNNN-key.pem
# certtool --generate-certificate \
--load-ca-certificate ca-cert.pem \
--load-ca-privkey ca-key.pem \
--load-privkey both-hostNNN-key.pem \
--template both-hostNNN.info \
--outfile both-hostNNN-cert.pem
@end example
When copying the PEM files to the target host, save them twice,
once as @code{server-cert.pem} and @code{server-key.pem}, and
again as @code{client-cert.pem} and @code{client-key.pem}.
@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. 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 (DH) 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 generate DH parameters when loading the credentials.
The @code{endpoint} parameter indicates whether the credentials will
be used for a network client or server, and determines which PEM
files are loaded.
The @code{verify} parameter determines whether x509 certificate
validation should be performed. This defaults to enabled, meaning
clients will always validate the server hostname against the
certificate subject alt name fields and/or CN field. It also
means that servers will request that clients provide a certificate
and validate them. Verification should never be turned off for
client endpoints, however, it may be turned off for server endpoints
if an alternative mechanism is used to authenticate clients. For
example, the VNC server can use SASL to authenticate clients
instead.
To load server credentials with client certificate validation
enabled
@example
$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
@end example
while to load client credentials use
@example
$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
@end example
Network services which support TLS will all have a @code{tls-creds}
parameter which expects the ID of the TLS credentials object. For
example with VNC:
@example
$QEMU -vnc 0.0.0.0:0,tls-creds=tls0
@end example
@node gdb_usage
@section GDB usage

11
qemu-options.hx
View File

@ -4112,7 +4112,7 @@ expensive operation that consumes random pool entropy, so it is
recommended that a persistent set of parameters be generated
upfront and saved.
@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id}
@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id}
Creates a TLS anonymous credentials object, which can be used to provide
TLS support on network backends. The @option{id} parameter is a unique
@ -4145,6 +4145,15 @@ version by providing the @var{passwordid} parameter. This provides
the ID of a previously created @code{secret} object containing the
password for decryption.
The @var{priority} parameter allows to override the global default
priority used by gnutls. This can be useful if the system administrator
needs to use a weaker set of crypto priorities for QEMU without
potentially forcing the weakness onto all applications. Or conversely
if one wants wants a stronger default for QEMU than for all other
applications, they can do this through this parameter. Its format is
a gnutls priority string as described at
@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
Interval @var{t} can't be 0, this filter batches the packet delivery: all

1
tests/test-crypto-tlssession.c
View File

@ -75,6 +75,7 @@ static QCryptoTLSCreds *test_tls_creds_create(QCryptoTLSCredsEndpoint endpoint,
"server" : "client"),
"dir", certdir,
"verify-peer", "yes",
"priority", "NORMAL",
/* We skip initial sanity checks here because we
* want to make sure that problems are being
* detected at the TLS session validation stage,

1
tests/test-io-channel-tls.c
View File

@ -78,6 +78,7 @@ static QCryptoTLSCreds *test_tls_creds_create(QCryptoTLSCredsEndpoint endpoint,
"server" : "client"),
"dir", certdir,
"verify-peer", "yes",
"priority", "NORMAL",
/* We skip initial sanity checks here because we
* want to make sure that problems are being
* detected at the TLS session validation stage,