path: root/webclients/ssl/README

This directory contains a patched Java applet VNC viewer that is SSL
enabled.

The patches in the *.patch files are relative to the source tarball:

	tightvnc-1.3dev7_javasrc.tar.gz  

currently (4/06) available here:

   http://prdownloads.sourceforge.net/vnc-tight/tightvnc-1.3dev7_javasrc.tar.gz?download

It also includes some simple patches to:

	- fix richcursor colors

	- make the Java Applet cursor (not the cursor drawn to the canvas
	  framebuffer) invisible when it is inside the canvas.

	- allow Tab (and some other) keystrokes to be sent to the vnc
	  server instead of doing widget traversal.


This SSL applet should work with any VNC viewer that has an SSL tunnel in
front of it.  It has been tested on x11vnc and using the stunnel tunnel
to other VNC servers.

By default this Vnc Viewer will only do SSL.  To do unencrypted traffic
see the "DisableSSL" applet parameter (e.g. set it to Yes in index.vnc).

Proxies: they are a general problem with java socket applets (a socket
connection does not go through the proxy).  See the info in the proxy.vnc
file for a workaround.  It uses SignedVncViewer.jar which is simply
a signed version of VncViewer.jar.  The basic idea is the user clicks
"Yes" to trust the applet and then it can connect directly to the proxy
and issue a CONNECT request.

This applet has been tested on versions 1.4.2 and 1.5.0 of the Sun
Java plugin.  It may not work on older releases or different vendor VM's.
Send full Java Console output for failures.

---------------------------------------------------------------
Tips:

When doing single-port proxy connections (e.g. both VNC and HTTPS
thru port 5900) it helps to move through the 'do you trust this site'
dialogs quickly.   x11vnc has to wait to see if the traffic is VNC or
HTTP and this can cause timeouts if you don't move thru them quickly.

You may have to restart your browser completely if it gets into a
weird state.  For one case we saw the JVM requesting VncViewer.class
even when no such file exists.


---------------------------------------------------------------
Extras:

ss_vncviewer (not Java):

        Wrapper script for native VNC viewer to connect to x11vnc in
        SSL mode.  Script launches stunnel(8) and then connects to it
        via localhost which in turn is then redirected to x11vnc via an
        SSL tunnel.  stunnel(8) must be installed and available in PATH.


Running Java SSL VncViewer from the command line:

	From this directory:

	java -cp ./VncViewer.jar VncViewer HOST <thehost> PORT <theport>

	substitute <thehost> and <theport> with the actual values.
	You can add any other parameters, e.g.: ignoreProxy yes

---------------------------------------------------------------
UltraVNC:

The UltraVNC java viewer has also been patched to support SSL.  Various
bugs in the UltraVNC java viewer were also fixed.  This viewer can be
useful because is support UltraVNC filetransfer, and so it works on
Unix, etc.

UltraViewerSSL.jar
SignedUltraViewerSSL.jar
ultra.vnc
ultraproxy.vnc
ultravnc-102-JavaViewer-ssl-etc.patch

---------------------------------------------------------------
Applet Parameters:

Some additional applet parameters can be set via the URL, e.g.

	http://host:5800/?param=value
	http://host:5800/ultra.vnc?param=value
	https://host:5900/ultra.vnc?param=value

etc.  If running java from command line as show above, it comes
in as java ... VncViewer param value ... 

There is a limitation with libvncserver that param and value can
only be alphanumeric, underscore, "+" (for space), or "."

We have added some applet parameters to the stock VNC java
viewers.  Here are the applet parameters:

Both TightVNC and UltraVNC Java viewers:

  HOST
	string, default: none.
	The Hostname to connect to.
	
  PORT
	number, default: 0
	The VNC server port to connect to.

  Open New Window
	yes/no, default: no
	Run applet in separate frame.

  Show Controls
	yes/no, default: yes
	Show Controls button panel.

  Show Offline Desktop
	yes/no, default: no
	Do we continue showing desktop on remote disconnect?

  Defer screen updates
	number, default: 20
	Milliseconds delay

  Defer cursor updates
	number, default: 10
	Milliseconds delay

  Defer update requests
	number, default: 50
	Milliseconds delay

  PASSWORD
	string, default: none
	VNC session password in plain text.

  ENCPASSWORD
	string, default: none
	VNC session password in encrypted in DES with KNOWN FIXED
	key.  It is a hex string.  This is like the ~/.vnc/passwd format.
  
  
  The following are added by x11vnc and/or ssvnc project
  
  VNCSERVERPORT
	number, default: 0
	Like PORT, but if there is a firewall this is the Actual VNC
	server port.  PORT might be a redir port on the firewall.

  DisableSSL
	yes/no, default: no
	Do unencrypted connection, no SSL. 

  httpsPort
	number, default: none
	When checking for proxy, use this at the url port number.

  CONNECT
	string, default: none
	Sets to host:port for the CONNECT line to a Web proxy. 
	The Web proxy should connect us to it.

  GET
	yes/no, default: no
	Set to do a special HTTP GET (/request.https.vnc.connection)
	to the vnc server that will cause it to switch to VNC instead.
	This is to speedup/make more robust, the single port HTTPS and VNC
	mode of x11vnc (e.g. both services thru port 5900, etc) 
	
  urlPrefix
	string, default: none
	set to a string that will be prefixed to all URL's when contacting
	the VNC server.  Idea is a special proxy will use this to indicate
	internal hostname, etc.

  oneTimeKey
	string, default: none
	set a special hex "key" to correspond to an SSL X.509 cert+key.
	See the 'onetimekey' helper script.  Can also be PROMPT to prompt
	the user to paste the hex key string in.

	This provides a Client-Side cert+key that the client will use to
	authenticate itself by SSL To the VNC Server.

	This is to try to work around the problem that the Java applet
	cannot keep an SSL keystore on disk, etc.  E.g. if they log
	into an HTTPS website via password they are authenticated and
	encrypted, then the website can safely put oneTimeKey=... on the
	URL.  The Vncviewer authenticates the VNC server with this key.

	Note that there is currently a problem in that if x11vnc requires
	Client Certificates the user cannot download the index.vnc HTML
	and VncViewer.jar from the same x11vnc.  Those need to come from
	a different x11vnc or from a web server.

	Note that the HTTPS website can also put the VNC Password
	(e.g. a temporary/one-time one) in the parameter PASSWORD.
	The Java Applet will automatically supply this VNC password
	instead of prompting.

  serverCert
	string, default: none
	set a special hex "cert" to correspond to an SSL X.509 cert
	See the 'onetimekey -certonly' helper script.

	This provides a Server-Side cert that the client will authenticate
	the VNC Server against by SSL.

	This is to try to work around the problem that the Java applet
	cannot keep an SSL keystore on disk, etc.  E.g. if they log
	into an HTTPS website via password they are authenticated and
	encrypted, then the website can safely put serverCert=... on the
	URL.

	Of course the VNC Server is sending this string to the Java
	Applet, so this is only reasonable security if the VNC Viewer
	already trusts the HTTPS retrieval of the URL + serverCert param
	that it gets.  This should be done over HTTPS not HTTP.

  proxyHost
	string, default: none
	Do not try to guess the proxy's hostname, use the value in
	proxyHost.  Does not imply forceProxy (below.)

  proxyPort
	string, default: none
	Do not try to guess the proxy's port number, use the value in
	proxyPort.  Does not imply forceProxy (below.)

  forceProxy
	yes/no, default: no
	Assume there is a proxy and force its use.

	If a string other than "yes" or "no" is given, it implies "yes"
	and uses the string for proxyHost and proxyPort (see above).
	In this case the string must be of the form "hostname+port".
	Note that it is "+" and not ":" before the port number.

  ignoreProxy
	yes/no, default: no
	Don't check for a proxy, assume there is none.

  trustAllVncCerts
	yes/no, default: no
	Automatically trust any cert received from the VNC server
	(obviously this could be dangerous and lead to man in the
	middle attack).  Do not ask the user to verify any of these
	certs from the VNC server.

  trustUrlVncCert
	yes/no, default: no
	Automatically trust any cert that the web browsers has accepted.
	E.g. the user said "Yes" or "Continue" to a web browser dialog
	regarding a certificate.  If we get the same cert (chain) from
	the VNC server we trust it without prompting the user.

  debugCerts
	yes/no, default: no
	Print out every cert in the Server, TrustUrl, TrustAll chains.


TightVNC Java viewer only:

  Offer Relogin
	yes/no, default: yes
	"Offer Relogin" set to "No" disables "Login again" 

  SocketFactory
	string, default: none
	set Java Socket class factory.

UltraVNC Java viewer only:

  None.

  The following are added by x11vnc and/or ssvnc project
  
  ftpDropDown
	string, default: none
	Sets the file transfer "drives" dropdown to the "." separated
	list.  Use "+" for space. The default is

		My+Documents.Desktop.Home

	for 3 entries in the dropdown in addition to the "drives"
	(e.g. C:\)  These items should be expanded properly by the VNC
	Server.  x11vnc will prepend $HOME to them, which is normally
	what one wants.  To include a "/" use "_2F_".  Another example:

		Home.Desktop.bin_2F_linux

	If an item is prefixed with "TOP_" then the item is inserted at
	the top of the drop down rather than being appended to the end.
	E.g. to try to initially load the user homedir instead of /:

		TOP_Home.My+Documents.Desktop

	If ftpDropDown is set to the empty string, "", then no special
	locations, [Desktop] etc., are placed in the drop down.  Only the
	ultravnc "drives" will appear.

  ftpOnly
	yes/no, default: no
	The VNC viewer only shows the filetransfer panel, no desktop
	is displayed.

  graftFtp
	yes/no, default: no
	As ftpOnly, the VNC viewer only shows the filetransfer panel,
	no desktop is displayed, however it is "grafted" onto an existing
	SSVNC unix vncviewer.  The special SSVNC vncviewer merges the two
	channels.

  dsmActive
	yes/no, default: no
	Special usage mode with the SSVNC unix vncviewer.  The UltraVNC
	DSM encryption is active.  Foolishly, UltraVNC DSM encryption
	*MODIFIES* the VNC protocol when active (it is not a pure tunnel).
	This option indicates to modify the VNC protocol to make this work. 
	Usually only used with graftFtp and SSVNC unix vncviewer.

  delayAuthPanel
	yes/no, default: no
	This is another special usage mode with the SSVNC unix vncviewer.
	A login panel is delayed (not shown at startup.)  Could be useful
	for non SSVNC usage too.

  ignoreMSLogonCheck
	yes/no, default: no
	Similar to delayAuthPanel, do not put up a popup asking for
	Windows username, etc.