From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1IFxRA-0002Y2-4V for qemu-devel@nongnu.org; Tue, 31 Jul 2007 15:31:20 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1IFxR7-0002XJ-Oc for qemu-devel@nongnu.org; Tue, 31 Jul 2007 15:31:19 -0400 Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IFxR7-0002XC-Fl for qemu-devel@nongnu.org; Tue, 31 Jul 2007 15:31:17 -0400 Received: from mx1.redhat.com ([66.187.233.31]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1IFxQz-00012u-Ar for qemu-devel@nongnu.org; Tue, 31 Jul 2007 15:31:11 -0400 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.13.1/8.13.1) with ESMTP id l6VJUd63017842 for ; Tue, 31 Jul 2007 15:30:39 -0400 Received: from file.surrey.redhat.com (file.fab.redhat.com [10.33.63.6]) by int-mx1.corp.redhat.com (8.13.1/8.13.1) with ESMTP id l6VJUcLA017581 for ; Tue, 31 Jul 2007 15:30:39 -0400 Received: (from berrange@localhost) by file.surrey.redhat.com (8.13.1/8.13.1/Submit) id l6VJUcNk032188 for qemu-devel@nongnu.org; Tue, 31 Jul 2007 20:30:38 +0100 Date: Tue, 31 Jul 2007 20:30:38 +0100 From: "Daniel P. Berrange" Subject: Re: [Qemu-devel] PATCH 8/8: document all VNC authentication options Message-ID: <20070731193038.GQ18730@redhat.com> References: <20070731192316.GI18730@redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20070731192316.GI18730@redhat.com> Reply-To: "Daniel P. Berrange" , qemu-devel@nongnu.org List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel 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 diff -r 9e499876ee0e qemu-doc.texi --- a/qemu-doc.texi Tue Jul 31 11:47:13 2007 -0400 +++ b/qemu-doc.texi Tue Jul 31 14:43:50 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. +@item -audio-help + +Will show the audio subsystem help: list of drivers, tunable +parameters. + +@item -soundhw card1,card2,... or -soundhw all + +Enable audio and selected sound hardware. Use ? to print all +available sound hardware. + +@example +qemu -soundhw sb16,adlib hda +qemu -soundhw es1370 hda +qemu -soundhw all hda +qemu -soundhw ? +@end example + +@item -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. + +@item -pidfile file +Store the QEMU process PID in @var{file}. It is useful if you launch QEMU +from a script. + +@item -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. + +@item -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). + +@item -option-rom file +Load the contents of file as an option ROM. This option is useful to load +things like EtherBoot. + +@item -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 + +Display options: +@table @option + @item -nographic Normally, QEMU uses SDL to display the VGA output. With this option, @@ -257,21 +308,69 @@ available screen space. This makes the u available screen space. This makes the using QEMU in a dedicated desktop workspace more convenient. -@item -vnc display +@item -full-screen +Start in full screen. + +@item -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. - -@var{display} may be in the form @var{interface:d}, in which case connections -will only be allowed from @var{interface} on display @var{d}. Optionally, -@var{interface} can be omitted. @var{display} can also be in the form -@var{unix:path} where @var{path} is the location of a unix socket to listen for -connections on. - +option to set the keyboard layout if you are not using en-us. Available +options for @var{display} are + +@table @code + +@item @var{interface:d} + +TCP connections will only be allowed from @var{interface} on display @var{d}. +By convention the TCP port is 5900+@var{d}. Optionally, @var{interface} can +be omitted in which case the server will bind to all interfaces. + +@item @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. + +@item @var{none} + +VNC is initialized by not started. The monitor @code{change} command can be used +to later start the VNC server. + +@end table + +Following the @var{display} value there may be one or more @var{option} flags +separated by commas. Valid options are + +@table @code + +@item @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 +@var{x509} or @var{x509verify} options. + +@item @var{x509} + +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. + +@item @var{x509verify} + +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. + +@end table @item -k language @@ -290,53 +389,32 @@ de en-us fi fr-be hr it lv nl- The default is @code{en-us}. -@item -audio-help - -Will show the audio subsystem help: list of drivers, tunable -parameters. - -@item -soundhw card1,card2,... or -soundhw all - -Enable audio and selected sound hardware. Use ? to print all -available sound hardware. - -@example -qemu -soundhw sb16,adlib hda -qemu -soundhw es1370 hda -qemu -soundhw all hda -qemu -soundhw ? -@end example - -@item -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. - -@item -full-screen -Start in full screen. - -@item -pidfile file -Store the QEMU process PID in @var{file}. It is useful if you launch QEMU -from a script. - -@item -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. - -@item -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). - -@item -option-rom file -Load the contents of file as an option ROM. This option is useful to load -things like EtherBoot. - -@item -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. +@item -x509cacert filename + +Specify the path to the CA certificate stored in PEM format. This +parameter is mandatory if using the @var{x509} or @var{x509} options +with the VNC server. See the @ref{vnc_security} section for details +on generating certificates. + +@item -x509cacrl filename + +Specify the path to the CA certificate revocation list stored in PEM +format. This parameter is optional. See the @ref{vnc_security} section +for details on generating certificates. + +@item -x509cert filename + +Specify the path to the server certificate stored in PEM format.. +This parameter is mandatory if using the @var{x509} or @var{x509} +options with the VNC server. See the @ref{vnc_security} section +for details on generating certificates. + +@item -x509key filename + +Specify the path to the server private key stored in PEM format. +This parameter is mandatory if using the @var{x509} or @var{x509} +options with the VNC server. See the @ref{vnc_security} section +for details on generating certificates. @end table @@ -862,8 +940,23 @@ Quit the emulator. @item eject [-f] device Eject a removable medium (use -f to force it). -@item change device filename -Change a removable medium. +@item change device setting + +Change the configuration of a device + +@table @option +@item change diskdevice filename +Change the medium for a removable disk device to point to @var{filename} + +@item change vnc display,options +Change the configuration of the VNC server. The valid syntax for @var{display} +and @var{options} are described at @ref{sec_invocation}. When using this command +it will prompt for a password to be entered. This is the password that clients +will use to authenticate with the VNC server. If no passwd is desired, simply +hit 'enter' without typing any characters. VNC passwords are only significant +upto 8 letters. + +@end table @item screendump filename Save screen into PPM image @var{filename}. @@ -1421,6 +1514,222 @@ 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). +@node vnc_security +@section 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. + +@menu +* vnc_sec_none:: +* vnc_sec_password:: +* vnc_sec_certificate:: +* vnc_sec_certificate_verify:: +* vnc_sec_certificate_pw:: +* vnc_generate_cert:: +@end menu +@node vnc_sec_none +@subsection 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 + +@example +qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc +@end 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. + +@node vnc_sec_password +@subsection 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. The password can be set by passing '-vnc none' on the +command line and then using the QEMU monitor: + +@example +qemu [...OPTIONS...] -vnc none -monitor stdio +(qemu) change vnc :1 +Password: ******** +(qemu) +@end example + +@node vnc_sec_certificate +@subsection 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. + +@example +qemu [...OPTIONS...] -vnc :1,tls,x509 -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem +@end example + +In the above example @code{/etc/pki} can be replaced with @code{$HOME/.pki} +if running as a non-root user. NB the @code{serverkey.pem} should be protected +to only be readable by the user owning it. + +@node vnc_sec_certificate_verify +@subsection 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. + +@example +qemu [...OPTIONS...] -vnc tls,x509verify -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem +@end example + + +@node vnc_sec_certificate_pw +@subsection 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. + +@example +qemu [...OPTIONS...] -vnc none -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem +(qemu) change vnc,tls,x509verify :1 +Password: ******** +(qemu) +@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 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. + +@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 > cakey.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 < server.info < serverkey.pem +# certtool --generate-certificate \ + --load-ca-certificate cacert.pem \ + --load-ca-privkey cakey.pem \ + --load-privkey server serverkey.pem \ + --template server.info \ + --outfile servercert.pem +@end example + +The @code{serverkey.pem} and @code{servercert.pem} files should now be securely copied +to the server for which they were generated. By convention they are kept in +@code{/etc/pki/qemu/servercert.pem} and @code{/etc/pki/qemu/private/serverkey.pem}, or +the equivalent per user directory @code{$HOME/.pki}. + +@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 < clientkey.pem +# certtool --generate-certificate \ + --load-ca-certificate cacert.pem \ + --load-ca-privkey cakey.pem \ + --load-privkey server clientkey.pem \ + --template client.info \ + --outfile clientcert.pem +@end example + +The @code{clientkey.pem} and @code{clientcert.pem} files should now be securely copied +to the client for which they were generated. By convention they are kept in +@code{/etc/pki/qemu/clientcert.pem} and @code{/etc/pki/qemu/private/clientkey.pem}, or +the equivalent per user directory @code{$HOME/.pki}. + + @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 -=|