SSVNC:   SSL/SSH VNC viewer: Proxy support.

Proxies allow one to reach servers that are otherwise unreachable. In SSVNC, the proxy acts as a relay of the encrypted VNC packets.

SSVNC supports Web proxies, SOCKS proxies, and the UltraVNC repeater proxy. In SSH mode, a similar thing can be achieved by going through a Gateway machine.

SSVNC can chain together up to 3 Proxies to get to very difficult to reach VNC servers. A typical example of 2 Proxies would be to use a company's Web proxy to get out of the company's firewall, and then use the UltraVNC repeater or Apache SSL portal to go inside another firewall (another company or your home) to reach VNC server(s) running on machines there. In SSVNC one specifies chained proxies by separating them by commas:

      Proxy/Gateway:    http://webproxy.west:8080,repeater://23.45.67.89+ID:1234
 

Here is the text about Proxies from the SSVNC Help panel:

 
                             SSVNC version: 1.0.29

 Here are a number of long sections on all sorts of proxies, Web, SOCKS,
 SSH tunnels/gateways, UltraVNC, Single Click, etc., etc.


 Proxies/Gateways:

    If an intermediate proxy is needed to make the SSL connection
    (e.g. a web gateway out of a firewall) enter it in the "Proxy/Gateway"
    entry box:

           VNC Host-Display:   host:number
           Proxy/Gateway:      proxy-host:port
    e.g.:
           VNC Host-Display:   far-away.east:0
           Proxy/Gateway:      myproxy.west:8080


    If the "double proxy" case is required (e.g. coming out of a web
    proxied firewall environment and then INTO a 2nd proxy to ultimately
    reach the VNC server), separate them via a comma, e.g.:

           VNC Host-Display:   far-away:0
           Proxy/Gateway:      myproxy.west:8080,myhome.net:443

    So it goes: viewer -> myproxy.west -> myhome.net -> far-away (VNC)

    The proxies are assumed to be Web proxies.  To use SOCKS proxies:

           VNC Host-Display:   far-away.east:0
           Proxy/Gateway:      socks://mysocks.west:1080

    Use socks5:// to force the SOCKS5 proxy protocol (e.g. for ssh -D).

    You can prefix web proxies with http:// in SSL mode but it doesn't matter
    since that is the default for a proxy.  (NOTE that in SSH or SSH+SSL
    mode you MUST supply the http:// prefix for web proxies because in those
    modes an SSH tunnel is the default proxy type: see the next section.)

    Note that Web proxies are often configured to ONLY allow outgoing
    connections to ports 443 (HTTPS) and 563 (SNEWS), so you might
    have run the VNC server (or router port redirector) on those ports.
    SOCKS proxies usually have no restrictions on port number.

    You can chain up to 3 proxies (any combination of web (http://) and
    socks://) by separating them with commas (i.e. first,second,third).

    Proxies also work for un-encrypted connections ("None" or vnc://, Tip 5)

    See the ss_vncviewer description and x11vnc FAQ for info on proxies:

        http://www.karlrunge.com/x11vnc/faq.html#ss_vncviewer
        http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-java-viewer-proxy


 SSH Proxies/Gateways:

    Proxy/Gateway also applies to SSH mode, it is a usually a gateway SSH
    machine to log into via ssh that is not the workstation running the
    VNC server.  However, Web and SOCKS proxies can also be used (see below).

    For example if a company had a central login server: "ssh.company.com"
    (accessible from the internet) and the internal workstation with VNC was
    named "joes-pc", then to create an SSH tunnel one could put this in:

           VNC Host:Display:   joes-pc:0
           Proxy/Gateway:      ssh.company.com

    It is OK if the hostname "joes-pc" only resolves inside the firewall.

    The 2nd leg, from ssh.company.com -> joes-pc is done by a ssh -L
    redir and is not encrypted (but the viewer -> ssh.company.com 1st leg is
    an encrypted tunnel). 

    To SSH encrypt BOTH legs, try the "double SSH gateway" method using
    the "comma" notation:

           VNC Host:Display:   localhost:0
           Proxy/Gateway:      ssh.company.com,joes-pc

    this requires an SSH server also running on joes-pc.  So an initial SSH
    login is done to ssh.company.com, then a 2nd SSH is performed (through
    port a redirection of the first) to login straight to joes-pc where
    the VNC server is running.

    Use username@host (e.g. joe@joes-pc  jsmith@ssh.company.com) if the
    user names differ between the various machines.  

    NOTE: On Windows you MUST always supply the username@ because putty's
    plink requires it.


    NON-STANDARD SSH PORT: To use a non-standard ssh port (i.e. a port other
    than 22) you need to use the Proxy/Gateways as well.  E.g. something
    like this for port 2222:

           VNC Host:Display:   localhost:0
           Proxy/Gateway:      joe@far-away.east:2222

    On Unix/MacOSX the username@ is not needed if it is the same as on
    the client.  This will also work going to a different internal machine,
    e.g. "joes-pc:0" instead of "localhost:0", as in the first example.


    A Web or SOCKS proxy can also be used with SSH.  Use this if you are
    inside a firewall that prohibits direct connections to remote SSH servers.

           VNC Host:Display:   joe@far-away.east:0
           Proxy/Gateway:      http://myproxy.west:8080

    or for SOCKS:

           VNC Host:Display:   joe@far-away.east:0
           Proxy/Gateway:      socks://mysocks.west:1080

    Use socks5://... to force the SOCKS5 version.  Note that the http://
    prefix is REQUIRED for web proxies in SSH or SSH+SSL modes (but it is
    the default proxy type in SSL mode.)

    You can chain up to 3 proxies (any combination of http://, socks://
    and ssh) by separating them with commas (i.e. first,second,third).

    Note: the Web and/or SOCKS proxies must come before any SSH gateways.

    For a non-standard SSH port and a Web or SOCKS proxy try:

           VNC Host:Display:   localhost:0
           Proxy/Gateway:      http://myproxy.west:8080,joe@far-away.east:2222

    Even the "double SSH gateway" method (2 SSH encrypted legs) described
    above works with an initial Web or SOCKS proxy, e.g.:

           VNC Host:Display:   localhost:0
           Proxy/Gateway:      socks://mysocks.west:1080,ssh.company.com,joes-pc



    Some Notes on SSH localhost tunnelling with SSH options
      NoHostAuthenticationForLocalhost=yes and UserKnownHostsFile=file:

    Warning:  Note that for proxy use with ssh(1), tunnels going through
    'localhost' are used.  This means ssh(1) thinks the remote hostname is
    'localhost', which may cause collisions and confusion when storing
    and checking SSH keys.

    By default on Unix when a 'localhost' ssh host is involved the
    ssh option -o NoHostAuthenticationForLocalhost=yes is applied (see
    ssh_config(1) for details.)  This avoids the warnings and ssh refusing
    to connect, but it reduces security.  A man in the middle attack may
    be possible.  SSVNC prints out a warning in the terminal every time
    the NoHostAuthenticationForLocalhost option is used.

    On Unix to disable the use of NoHostAuthenticationForLocalhost set the env.
    variable SSVNC_SSH_LOCALHOST_AUTH=1. This may induce extra ssh(1) dialogs.

    On Unix a MUCH SAFER and more convenient way to proceed is to set the
    known hosts option in Options -> Advanced -> 'Private SSH KnownHosts file'
    Then, only for the host in the current profile, a private known_hosts
    file will be used and so there will be no 'localhost' collisions.
    This method is secure (assuming you verify the SSH key fingerprint)
    and avoids the man in the middle attack.

    On Windows, Putty/Plink is used and does not have the UserKnownHosts
    or NoHostAuthenticationForLocalhost features.  Keys are stored in
    the registry as localhost:port pairs and so it is possible to use the
    'Port Slot' option to keep the keys separate to avoid the dialogs and
    also maintain good security.

    Note that for the "double SSH gateway" method the risk from using
    NoHostAuthenticationForLocalhost is significantly less because the first
    ssh connection does not use the option (it connects directly to the remote
    host) and the second one is only exposed for the leg inside the first
    gateway (but is still vulnerable there when NoHostAuthenticationForLocalhost
    is used.)

    As with a username that contains a space, use %SPACE (or %TAB) to
    indicate it in the SSH proxies, e.g. john%SPACEsmith@ssh.company.com

 UltraVNC Proxies/Gateways:

    UltraVNC has a "repeater" tool (http://www.uvnc.com/addons/repeater.html
    and http://koti.mbnet.fi/jtko/) that acts as a VNC proxy.  SSVNC can
    work with both mode I and mode II schemes of this repeater.

    For Unix and MacOS X there is another re-implementation of the
    UltraVNC repeater:

        http://www.karlrunge.com/x11vnc/ultravnc_repeater.pl

    So one does not need to run the repeater on a Windows machine.

    Note that even though the UltraVNC repeater tool is NOT SSL enabled,
    it can nevertheless act as a proxy for SSVNC SSL connections.
    This is because, just as with a Web proxy, the proxy negotiations
    occur before the SSL traffic starts.  (There is a separate UltraVNC
    tool, repeater_SSL.exe, that is SSL enabled and is discussed below.)

    Note: it seems only SSL SSVNC connections make sense with the
    UltraVNC repeater.  SSH connections (previous section) do not seem to
    and so are not enabled to (let us know if you find a way to use it.)

    Unencrypted (aka Direct) SSVNC VNC connections (Vnc:// prefix in
    'VNC Host:Display'; see Tip 5) also work with the UltraVNC repeater.

    MODE I REPEATER:

    For the mode I UltraVNC repeater the Viewer initiates the connection
    and passes a string that is the VNC server's IP address (or hostname)
    and port or display to the repeater (the repeater then makes the
    connection to the server host and then exchanges data back and forth.)
    To do this in SSVNC:

           VNC Host:Display:   :0
           Proxy/Gateway:      repeater://myuvncrep.west:5900+joes-pc:1

    Where "myuvncrep.west" is running the UltraVNC repeater and 
    "joes-pc:1" is the VNC server the repeater will connect us to.

    Note here that the VNC Host:Display can be anything because it is
    not used; we choose :0.  You cannot leave VNC Host:Display empty.

    The Proxy/Gateway format is repeater://proxy:port+vncserver:display.
    The string after the "+" sign is passed to the repeater server for
    it to interpret (and so does not have to be the UltraVNC repeater;
    you could create your own if you wanted to.)  For this example,
    instead of joes-pc:1 it could be joes-pc:5901 or 192.168.1.4:1,
    192.168.1.4:5901, etc.

    If you do not supply a proxy port, then the default 5900 is assumed,
    e.g. use repeater://myuvncrep.west+joes-pc:1 for port 5900 on
    myuvncrep.west then connecting to port 5901 on joes-pc.

    X11VNC: For mode I operation the VNC server x11vnc simply runs as
    a normal SSL/VNC server:

       x11vnc -ssl SAVE

    because the repeater will connect to it as a VNC client would.
    For mode II operation additional options are needed (see below.)


    MODE II REPEATER:

    For the mode II repeater both the VNC viewer and VNC server initiate
    TCP connections to the repeater proxy.  In this case they pass a string
    that identifies their mutual connection via "ID:NNNN", for example:

           VNC Host:Display:   :0
           Proxy/Gateway:      repeater://myuvncrep.west:5900+ID:2345

    again, the default proxy port is 5900 if not supplied.  And we need
    to supply a placeholder display ":0".

    The fact that BOTH the VNC viewer and VNC server initiate outgoing
    TCP connections to the repeater makes some things tricky, especially
    for the SSL aspect.  In SSL one side takes the 'client' role and
    the other side must take the 'server' role.  These roles must be
    coordinated correctly or otherwise the SSL handshake will fail.

    We now describe two scenarios: 1) SSVNC in Listening mode with STUNNEL
    in 'SSL server' role; and 2) SSVNC in Forward mode with STUNNEL in
    'SSL client' role.  For both cases we show how the corresponding
    VNC server x11vnc would be run.

    SSVNC Listening mode / STUNNEL 'SSL server' role:

      By default, when using SSL over a reverse connection the x11vnc VNC
      server will take the 'SSL client' role.  This way it can connect to a
      standard STUNNEL (SSL server) redirecting connections to a VNC viewer
      in Listen mode.  This is how SSVNC with SSL is normally intended to
      be used for reverse connections (i.e. without the UltraVNC Repeater.)

      To do it this way with the mode II UltraVNC Repeater; you set
      Options -> Reverse VNC Connection, i.e. a "Listening Connection".
      You should disable 'Verify All Certs' unless you have already
      saved the VNC Server's certificate to Accepted Certs.  Or you can
      set ServerCert to the saved certificate.  Then click 'Listen'.
      In this case an outgoing connection is made to the UltraVNC
      repeater, but everything else is as for a Reverse connection.

      Note that in Listening SSL mode you must supply a MyCert or use the
      "listen.pem" one you are prompted by SSVNC to create.

      X11VNC command:

        x11vnc -ssl -connect_or_exit repeater://myuvncrep.west+ID:2345


    SSVNC Forward mode / STUNNEL 'SSL client' role:

      x11vnc 0.9.10 and later can act in the 'SSL server' role for Reverse
      connections (i.e. as it does for forward connections.)  Set these
      x11vnc options: '-env X11VNC_DISABLE_SSL_CLIENT_MODE=1 -sslonly'

      The -sslonly option is to prevent x11vnc from thinking the delay in
      connection implies VeNCrypt instead of VNC over SSL.  With x11vnc
      in X11VNC_DISABLE_SSL_CLIENT_MODE mode, you can then have SSVNC make
      a regular forward connection to the UltraVNC repeater.

      Note that SSVNC may attempt to do a 'Fetch Cert' action in forward
      connection mode to either retrieve the certificate or probe for
      VeNCrypt and/or ANONDH.  After that 'Fetch Cert' is done the
      connection to the UltraVNC repeater will be dropped.  This is a
      problem for the subsequent real VNC connection.  You can disable
      'Verify All Certs' AND also set 'Do not Probe for VeNCrypt'
      to avoid the 'Fetch Cert' action.  Or, perhaps better, add to
      x11vnc command line '-connect_or_exit repeater://... -loop300,2'
      (in addition to the options in the previous paragraphs.)  That way
      x11vnc will reconnect once to the Repeater after the 'Fetch Cert'
      action.  Then things should act pretty much as a normal forward
      SSL connection.

      X11VNC 0.9.10 command (split into two lines):

        x11vnc -ssl -connect_or_exit repeater://myuvncrep.west+ID:2345 \ 
             -env X11VNC_DISABLE_SSL_CLIENT_MODE=1 -loop300,2 -sslonly

    We recommend using "SSVNC Forward mode / STUNNEL 'SSL client' role"
    if you are connecting to x11vnc 0.9.10 or later.  Since this does
    not use Listen mode it should be less error prone and less confusing
    and more compatible with other features.  Be sure to use all of
    the x11vnc options in the above command line.  To enable VeNCrypt,
    replace '-sslonly' with '-vencrypt force'.  If you do not indicate
    them explicitly to SSVNC, SSVNC may have to probe multiple times for
    VeNCrypt and/or ANONDH.  So you may need '-loop300,4' on the x11vnc
    cmdline so it will reconnect to the UltraVNC repeater 3 times.


    Note that for UNENCRYPTED (i.e. direct) SSVNC connections (see vnc://
    in Tip 5) using the UltraVNC Repeater mode II there is no need to
    use a reverse "Listening connection" and so you might as well use
    a forward connection.

    For Listening connections, on Windows after the VNC connection you
    MUST manually terminate the listening VNC Viewer (and connect again
    if desired.)  Do this by going to the System Tray and terminating
    the Listening VNC Viewer.  Subsequent connection attempts using the
    repeater will fail unless you do this and restart the Listen.

    On Unix and MacOS X after the VNC connection the UltraVNC repeater
    proxy script will automatically restart and reconnect to the repeater
    for another connection.  So you do not need to manually restart it.
    To stop the listening, kill the listening VNC Viewer with Ctrl-C.

    In the previous sections it was mentioned one can chain up to 3
    proxies together by separating them with commas: proxy1,proxy2,proxy3.
    Except where explicitly noted below this should work for "repeater://..."
    as the final proxy.  E.g. you could use a web proxy to get out of a
    firewall, and then connect to a remote repeater.

    The UltraVNC SSL enabled repeater_SSL.exe is discussed below.


 UltraVNC Single Click:

    UltraVNC has Single Click (SC) Windows VNC servers that allow naive
    users to get them running very easily (a EXE download and a few
    mouse clicks).  See http://sc.uvnc.com/ for details on how to create
    these binaries.  Also there is a how-to here:
    http://www.simply-postcode-lookup.com/SingleClickUltraVNC/SingleClickVNC.htm

    The SC EXE is a VNC *server* that starts up a Reverse VNC connection
    to a Listening Viewer (e.g. the viewer address/port/ID is hardwired
    into the SC EXE).  So SC is not really a proxy, but it can be used
    with UltraVNC repeater proxies and so we describe it here.

    One important point for SC III binary creation: do NOT include 
    "-id N" in the helpdesk.txt config file.  This is because the with
    SSVNC the Ultra VNC repeater IS NOT USED (see below for how to
    use it).  Use something like for helpdesk.txt:

       [TITLE]
       My UltraVNC SC III

       [HOST]
       Internet Support XYZ
       -sslproxy -connect xx.xx.xx.xx:5500 -noregistry

    (replace xx.xx.xx.xx with IP address or hostname of the SSVNC machine.)

    The Unix SSVNC vncviewer supports the both the unencrypted "SC I"
    mode and the SSL encrypted "SC III" mode.  For both cases SSVNC
    must be run in Listening mode (Options -> Reverse VNC Connection)

    For SC I, enable Reverse VNC Connection and put Vnc://0 (see Tip 5
    below) in the VNC Host:Display to disable encryption (use a different
    number if you are not using the default listening port 5500).
    Then click on the "Listen" button and finally have the user run your
    Single Click I EXE.

    BTW, we used this for a SC I helpdesk.txt:

       [TITLE]
       My UltraVNC SC I

       [HOST]
       Internet Support XYZ
       -connect xx.xx.xx.xx:5500 -noregistry

    For SC III (SSL), enable Reverse VNC Connection and then UNSET "Verify
    All Certs" (this is required).  Let the VNC Host:Display be ":0"
    (use a different number if you are not using the default listening
    port 5500).  Then click on the "Listen" button and finally have the
    user run your Single Click III EXE.

    Note that in Listening SSL mode you MUST supply a MyCert or use the 
    "listen.pem" one you are prompted by SSVNC to create.


 UltraVNC repeater_SSL.exe proxy:

    For repeater_SSL.exe SSL usage, with Single Click III or otherwise
    (available at http://www.uvnc.com/pchelpware/SCIII/index.html)
    it helps to realize that the ENTIRE connection is SSL encrypted,
    even the proxy host:port/ID:NNNN negotiation, and so a different
    approach needs to be taken from that described above in 'UltraVNC
    Proxies/Gateways'.  In this case do something like this:

           VNC Host:Display:   :0
           Proxy/Gateway:      sslrepeater://myuvncrep.west:443+ID:2345

    The sslrepeater:// part indicates the entire ID:XYZ negotiation must
    occur inside the SSL tunnel.  Listening mode is not required in this
    case: a forward VNC connection works fine (and is recommended).
    As before, the ":0" is simply a placeholder and is not used.
    Note that the UltraVNC repeater_SSL.exe listens on port 443 (HTTPS),
    (it is not clear that it can be modified to use another port.)

    Non-ID connections sslrepeater://myuvncrep.west:443+host:disp also
    work, but the 2nd leg repeater <-> host:disp must be unencrypted.
    The first leg SSVNC <-> repeater is, however, SSL encrypted.

    sslrepeater:// only works on Unix or MacOSX using the provided
    SSVNC vncviewer.  The modified viewer is needed; stock VNC viewers
    will not work.  Also, proxy chaining (bouncing off of more than one
    proxy) currently does not work for repeater_SSL.exe.


 VeNCrypt is treated as a proxy:

    SSVNC supports the VeNCrypt VNC security type.  You will find out more
    about this security type in the other parts of the Help documentation.
    In short, it does a bit of plain-text VNC protocol negotiation before
    switching to SSL/TLS encryption and authentication.

    SSVNC implements its VeNCrypt support as final proxy in a chain
    of proxies.  You don't need to know this or specify anything, but
    it is good to know since it uses up one of the 3 proxies you are
    allowed to chain together.  If you watch the command output you will
    see the vencrypt:// proxy item.

    You can specify that a VNC server uses VeNCrypt (Options -> Advanced)
    or you can let SSVNC try to autodetect VeNCrypt.


 IPv6 can be treated as a proxy for UN-ENCRYPTED connections:

    Read Tip 20 about SSVNC's IPv6 (128 bit IP addresses) support.
    In short, because stunnel and ssh support IPv6 hostnames and
    addresses, SSVNC does too without you needing to do anything.

    However, in some rare usage modes you will need to specify the IPv6
    server destination in the Proxy/Gateway entry box.  The only case
    this appears to be needed is when making an un-encrypted connection
    to an IPv6 VNC server.  In this case neither stunnel nor ssh are
    used and you need to specify something like this:

              VNC Host:Display:       localhost:0
              Proxy/Gateway:          ipv6://2001:4860:b009::68:5900

    and then select 'None' as the encryption type.  Note that the above
    'localhost:0' setting can be anything; it is basically ignored.

    Note that on Unix, MacOSX, and Windows un-encrypted ipv6 connections
    are AUTODETECTED and so you likely NEVER need to supply ipv6://
    Only try it if you encounter problems.  Also note that the ipv6://
    proxy type does not work on Windows, so only the autodetection is
    available there.

    Note that if there is some other proxy, e.g. SOCKS or HTTP and that
    proxy server is an IPv6 host (or will connect you to one) then any
    sort of connection through that proxy will work OK: un-encrypted as
    well as SSL or SSH connections, etc.

    Unencrypted connection is the only special case where you may need
    to specify an ipv6:// proxy.  If you find another use let us know.

    See Tip 20 for more info.