[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] PATCH 8/8: document all VNC authentication options
From: |
Daniel P. Berrange |
Subject: |
Re: [Qemu-devel] PATCH 8/8: document all VNC authentication options |
Date: |
Mon, 13 Aug 2007 20:51:09 +0100 |
User-agent: |
Mutt/1.4.1i |
This patch updates the user documentation to detail the new syntax
options for VNC server configuration. It moves all the display
related options into a combined logical section for clarity. It
documents the different deployment secenarios possible with the
new VNC server capabilities and their security. It also provides
a guide for setting up a certificate authority and issuing clients
and server with their certificates
Signed-off-by: Daniel P. Berrange <address@hidden>
diff -r e5ce3da5ebb1 qemu-doc.texi
--- a/qemu-doc.texi Mon Aug 13 11:57:58 2007 -0400
+++ b/qemu-doc.texi Mon Aug 13 12:05:16 2007 -0400
@@ -129,6 +129,7 @@ Download the experimental binary install
* pcsys_network:: Network emulation
* direct_linux_boot:: Direct Linux Boot
* pcsys_usb:: USB emulation
+* vnc_security:: VNC security
* gdb_usage:: GDB usage
* pcsys_os_specific:: Target OS specific information
@end menu
@@ -243,6 +244,56 @@ Simulate an SMP system with @var{n} CPUs
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
CPUs are supported.
address@hidden -audio-help
+
+Will show the audio subsystem help: list of drivers, tunable
+parameters.
+
address@hidden -soundhw card1,card2,... or -soundhw all
+
+Enable audio and selected sound hardware. Use ? to print all
+available sound hardware.
+
address@hidden
+qemu -soundhw sb16,adlib hda
+qemu -soundhw es1370 hda
+qemu -soundhw all hda
+qemu -soundhw ?
address@hidden example
+
address@hidden -localtime
+Set the real time clock to local time (the default is to UTC
+time). This option is needed to have correct date in MS-DOS or
+Windows.
+
address@hidden -pidfile file
+Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
+from a script.
+
address@hidden -daemonize
+Daemonize the QEMU process after initialization. QEMU will not detach from
+standard IO until it is ready to receive connections on any of its devices.
+This option is a useful way for external programs to launch QEMU without having
+to cope with initialization race conditions.
+
address@hidden -win2k-hack
+Use it when installing Windows 2000 to avoid a disk full bug. After
+Windows 2000 is installed, you no longer need this option (this option
+slows down the IDE transfers).
+
address@hidden -option-rom file
+Load the contents of file as an option ROM. This option is useful to load
+things like EtherBoot.
+
address@hidden -name string
+Sets the name of the guest. This name will be display in the SDL window
+caption. The name will also be used for the VNC server.
+
address@hidden table
+
+Display options:
address@hidden @option
+
@item -nographic
Normally, QEMU uses SDL to display the VGA output. With this option,
@@ -257,21 +308,80 @@ available screen space. This makes the u
available screen space. This makes the using QEMU in a dedicated desktop
workspace more convenient.
address@hidden -vnc display
address@hidden -full-screen
+Start in full screen.
+
address@hidden -vnc display[,option[,option[,...]]]
Normally, QEMU uses SDL to display the VGA output. With this option,
you can have QEMU listen on VNC display @var{display} and redirect the VGA
display over the VNC session. It is very useful to enable the usb
tablet device when using this option (option @option{-usbdevice
tablet}). When using the VNC display, you must use the @option{-k}
-option to set the keyboard layout if you are not using en-us.
-
address@hidden may be in the form @var{interface:d}, in which case connections
-will only be allowed from @var{interface} on display @var{d}. Optionally,
address@hidden can be omitted. @var{display} can also be in the form
address@hidden:path} where @var{path} is the location of a unix socket to
listen for
-connections on.
-
+parameter to set the keyboard layout if you are not using en-us. Valid
+syntax for the @var{display} is
+
address@hidden @code
+
address@hidden @var{interface:d}
+
+TCP connections will only be allowed from @var{interface} on display @var{d}.
+By convention the TCP port is address@hidden Optionally, @var{interface} can
+be omitted in which case the server will bind to all interfaces.
+
address@hidden @var{unix:path}
+
+Connections will be allowed over UNIX domain sockets where @var{path} is the
+location of a unix socket to listen for connections on.
+
address@hidden @var{none}
+
+VNC is initialized by not started. The monitor @code{change} command can be
used
+to later start the VNC server.
+
address@hidden table
+
+Following the @var{display} value there may be one or more @var{option} flags
+separated by commas. Valid options are
+
address@hidden @code
+
address@hidden @var{password}
+
+Require that password based authentication is used for client connections.
+The password must be set separately using the @code{change} command in the
address@hidden
+
address@hidden @var{tls}
+
+Require that client use TLS when communicating with the VNC server. This
+uses anonymous TLS credentials so is susceptible to a man-in-the-middle
+attack. It is recommended that this option be combined with either the
address@hidden or @var{x509verify} options.
+
address@hidden @var{x509=/path/to/certificate/dir}
+
+Valid if @var{tls} is specified. Require that x509 credentials are used
+for negotiating the TLS session. The server will send its x509 certificate
+to the client. It is recommended that a password be set on the VNC server
+to provide authentication of the client when this is used. The path following
+this option specifies where the x509 certificates are to be loaded from.
+See the @ref{vnc_security} section for details on generating certificates.
+
address@hidden @var{x509verify=/path/to/certificate/dir}
+
+Valid if @var{tls} is specified. Require that x509 credentials are used
+for negotiating the TLS session. The server will send its x509 certificate
+to the client, and request that the client send its own x509 certificate.
+The server will validate the client's certificate against the CA certificate,
+and reject clients when validation fails. If the certificate authority is
+trusted, this is a sufficient authentication mechanism. You may still wish
+to set a password on the VNC server as a second authentication layer. The
+path following this option specifies where the x509 certificates are to
+be loaded from. See the @ref{vnc_security} section for details on generating
+certificates.
+
address@hidden table
@item -k language
@@ -289,54 +399,6 @@ de en-us fi fr-be hr it lv nl-
@end example
The default is @code{en-us}.
-
address@hidden -audio-help
-
-Will show the audio subsystem help: list of drivers, tunable
-parameters.
-
address@hidden -soundhw card1,card2,... or -soundhw all
-
-Enable audio and selected sound hardware. Use ? to print all
-available sound hardware.
-
address@hidden
-qemu -soundhw sb16,adlib hda
-qemu -soundhw es1370 hda
-qemu -soundhw all hda
-qemu -soundhw ?
address@hidden example
-
address@hidden -localtime
-Set the real time clock to local time (the default is to UTC
-time). This option is needed to have correct date in MS-DOS or
-Windows.
-
address@hidden -full-screen
-Start in full screen.
-
address@hidden -pidfile file
-Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
-from a script.
-
address@hidden -daemonize
-Daemonize the QEMU process after initialization. QEMU will not detach from
-standard IO until it is ready to receive connections on any of its devices.
-This option is a useful way for external programs to launch QEMU without having
-to cope with initialization race conditions.
-
address@hidden -win2k-hack
-Use it when installing Windows 2000 to avoid a disk full bug. After
-Windows 2000 is installed, you no longer need this option (this option
-slows down the IDE transfers).
-
address@hidden -option-rom file
-Load the contents of file as an option ROM. This option is useful to load
-things like EtherBoot.
-
address@hidden -name string
-Sets the name of the guest. This name will be display in the SDL window
-caption. The name will also be used for the VNC server.
@end table
@@ -862,8 +924,38 @@ Quit the emulator.
@item eject [-f] device
Eject a removable medium (use -f to force it).
address@hidden change device filename
-Change a removable medium.
address@hidden change device setting
+
+Change the configuration of a device
+
address@hidden @option
address@hidden change @var{diskdevice} @var{filename}
+Change the medium for a removable disk device to point to @var{filename}. eg
+
address@hidden
+(qemu) change cdrom /path/to/some.iso
address@hidden example
+
address@hidden change vnc @var{display,options}
+Change the configuration of the VNC server. The valid syntax for @var{display}
+and @var{options} are described at @ref{sec_invocation}. eg
+
address@hidden
+(qemu) change vnc localhost:1
address@hidden example
+
address@hidden change vnc password
+
+Change the password associated with the VNC server. The monitor will prompt for
+the new password to be entered. VNC passwords are only significant upto 8
letters.
+eg.
+
address@hidden
+(qemu) change vnc password
+Password: ********
address@hidden example
+
address@hidden table
@item screendump filename
Save screen into PPM image @var{filename}.
@@ -1421,6 +1513,213 @@ When relaunching QEMU, you may have to u
When relaunching QEMU, you may have to unplug and plug again the USB
device to make it work again (this is a bug).
address@hidden vnc_security
address@hidden VNC security
+
+The VNC server capability provides access to the graphical console
+of the guest VM across the network. This has a number of security
+considerations depending on the deployment scenarios.
+
address@hidden
+* vnc_sec_none::
+* vnc_sec_password::
+* vnc_sec_certificate::
+* vnc_sec_certificate_verify::
+* vnc_sec_certificate_pw::
+* vnc_generate_cert::
address@hidden menu
address@hidden vnc_sec_none
address@hidden Without passwords
+
+The simplest VNC server setup does not include any form of authentication.
+For this setup it is recommended to restrict it to listen on a UNIX domain
+socket only. For example
+
address@hidden
+qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
address@hidden example
+
+This ensures that only users on local box with read/write access to that
+path can access the VNC server. To securely access the VNC server from a
+remote machine, a combination of netcat+ssh can be used to provide a secure
+tunnel.
+
address@hidden vnc_sec_password
address@hidden With passwords
+
+The VNC protocol has limited support for password based authentication. Since
+the protocol limits passwords to 8 characters it should not be considered
+to provide high security. The password can be fairly easily brute-forced by
+a client making repeat connections. For this reason, a VNC server using
password
+authentication should be restricted to only listen on the loopback interface
+or UNIX domain sockets. Password ayuthentication is requested with the
@code{password}
+option, and then once QEMU is running the password is set with the monitor.
Until
+the monitor is used to set the password all clients will be rejected.
+
address@hidden
+qemu [...OPTIONS...] -vnc :1,password -monitor stdio
+(qemu) change vnc password
+Password: ********
+(qemu)
address@hidden example
+
address@hidden vnc_sec_certificate
address@hidden With x509 certificates
+
+The QEMU VNC server also implements the VeNCrypt extension allowing use of
+TLS for encryption of the session, and x509 certificates for authentication.
+The use of x509 certificates is strongly recommended, because TLS on its
+own is susceptible to man-in-the-middle attacks. Basic x509 certificate
+support provides a secure session, but no authentication. This allows any
+client to connect, and provides an encrypted session.
+
address@hidden
+qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
address@hidden example
+
+In the above example @code{/etc/pki/qemu} should contain at least three files,
address@hidden, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
+users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
+NB the @code{server-key.pem} file should be protected with file mode 0600 to
+only be readable by the user owning it.
+
address@hidden vnc_sec_certificate_verify
address@hidden With x509 certificates and client verification
+
+Certificates can also provide a means to authenticate the client connecting.
+The server will request that the client provide a certificate, which it will
+then validate against the CA certificate. This is a good choice if deploying
+in an environment with a private internal certificate authority.
+
address@hidden
+qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
address@hidden example
+
+
address@hidden vnc_sec_certificate_pw
address@hidden With x509 certificates, client verification and passwords
+
+Finally, the previous method can be combined with VNC password authentication
+to provide two layers of authentication for clients.
+
address@hidden
+qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor
stdio
+(qemu) change vnc password
+Password: ********
+(qemu)
address@hidden example
+
address@hidden vnc_generate_cert
address@hidden 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 neccessary 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}.
+
address@hidden
+* vnc_generate_ca::
+* vnc_generate_server::
+* vnc_generate_client::
address@hidden menu
address@hidden vnc_generate_ca
address@hidden 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.
+
address@hidden
+# certtool --generate-privkey > ca-key.pem
address@hidden 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.
+
address@hidden
+# 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
address@hidden 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.
+
address@hidden vnc_generate_server
address@hidden 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:
+
address@hidden
+# 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 server-key.pem \
+ --template server.info \
+ --outfile server-cert.pem
address@hidden 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.
+
address@hidden vnc_generate_client
address@hidden 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:
+
address@hidden
+# cat > client.info <<EOF
+country = GB
+state = London
+locality = London
+organiazation = 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
address@hidden 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 gdb_usage
@section GDB usage
--
|=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=|
|=- Perl modules: http://search.cpan.org/~danberr/ -=|
|=- Projects: http://freshmeat.net/~danielpb/ -=|
|=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|
- [Qemu-devel] PATCH 0/8: Authentication support for the VNC server, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 1/8: Refactor VNC server setup API, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 2/8: Extend monitor 'change' command for VNC, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 3/8: VNC password authentication, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 4/8: VeNCrypt basic TLS support, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 5/8: x509 certificate for server, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 6/8: x509 client certificate verification, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 7/8: custom location for x509 cert paths, Daniel P. Berrange, 2007/08/13
- Re: [Qemu-devel] PATCH 8/8: document all VNC authentication options,
Daniel P. Berrange <=
- Re: [Qemu-devel] PATCH 0/8: Authentication support for the VNC server, Anthony Liguori, 2007/08/15