
  distributed.net's RC5DES client

  Copyright distributed.net 1997-1999 - All Rights Reserved
  For use in distributed.net projects only.
  Any other distribution violates copyright.

  Use of the distributed.net client implies agreement with
  the prize terms listed on http://www.distributed.net/rc5/ and
  http://www.distributed.net/des/


 Index ---------------------------------------------------------------

    1.0  Introduction   
    2.0  General system requirements 
         refer to platform specific readme.s for details
    3.0  Getting and starting the client
         refer to platform specific readme.s for details
    4.0  Upgrading from a client older than the 2.7xxx
    5.0  Fetching and flushing blocks
         5.1 through a firewall
         5.2 via e-mail
    6.0  Help!


 This document's revision history ------------------------------------

    Dec 20. 1997 The original (v2.6401) version of this document was 
                 created by Daniel "dbaker" Baker, assisted by 
                 Alex "kiddo" Wong
    Feb 13. 1998 Mike "Silby" Silbersack <silby@silby.com> updated and 
                 expanded this document.
                 Paul Gentle <gentleps@muohio.edu> converted this document 
                 to a Windows help file.
    May 13. 1998 Mike "Silby" Silbersack <silby@silby.com> updated this 
                 document and added information about specific platforms.
    Jun 26. 1998 Mike "Silby" Silbersack <silby@silby.com> slightly 
                 updated this document for 2.7100
    Nov 08. 1998 Mike "Silby" Silbersack <silby@silby.com> gutted the 
                 options sections for 2.7102
    Nov 13. 1998 Cyrus Patel <cyp@fb14.uni-mainz.de> moved platform
                 specific information to separate readmes, replaced a 
                 great deal with references to documentation available
                 online or built-in to the client, cleaned up and
                 reorganized the file.

                                                                     
 1.0  Introduction ---------------------------------------------------

    Congratulations! This distributed.net client will make your computer 
    a part of the world's largest computer, distributed.net. The client 
    you have downloaded is capable of working on two of Distributed.Net's
    ongoing projects: The brute-force decryption of a RC5-64 message, and
    the brute force decryption of a DES message. The RC5-64 contest is a
    long-term contest, which may take a couple of years to solve. The DES
    contests, run twice a year, are short (refer to the DES contest 
    documentation for details). As a result, this client will work on DES 
    during DES contests, and switch back to RC5-64 when no DES contest is 
    running. No user intervention is required for this switchover.

    If you'd like more information on our current project status, you 
    should visit the RC5-64 and DES homepages.  RC5-64 may be found at
    http://www.distributed.net/rc5/ , and DES may be found at
    http://www.distributed.net/des/. In the next few months, 
    distributed.net will begin working on other (non-encryption related) 
    projects. For information on other projects, please look at
    http://www.distributed.net/projects/.


 2.0  General system requirements ------------------------------------

    The system requirements for the client vary from platform to platform
    and are detailed in the readme.* you should have received when you
    downloaded the client.

    In general, all that is required is:
    - a 32-bit processor
    - one megabyte of free memory
    - a TCP/IP internet connection or another method of sharing files 
      with another computer that is also running the client.
    - less than a megabyte of disk space (optional if TCP/IP is available)

    The most important requirement for running the distributed.net client,
    of course, is authorization to run the client on the computer that it
    is installed on. This is not an issue with your home computer, but 
    many companies and schools have policies against running outside 
    programs on their computers. In cases where such a policy exists, ask 
    your system administrator BEFORE attempting to install the client. 
    It is very possible that he/she will like the idea, and choose to 
    install the client on all computers at that site. However, if the 
    answer is a 'no', do not push the issue. RSA's contest rules stipulate 
    that all clients must be run on authorized systems. The only support 
    we will give to unauthorized installations is help in uninstalling 
    them.

    Although there are a number of platforms that meet these requirements,
    distributed.net cannot create or maintain clients for them all. The
    prerequisites for creating a client for a platform are: 
    - a C++ compiler is available for that platform
    - the compiler 'understands' 64bit quanta ('long long', 'wide' etc)
    - distributed.net must have access to such a machine

    If you know of a platform that fulfills these requirements, and would
    like to have a client for the platform, you can request it at
    http://www.distributed.net/porting/

                                                                     
 3.0  Getting and starting the client --------------------------------

    Clients are (barring a few exceptions) *only* available from 
    http://www.distributed.net/clients/ or from ftp servers linked from 
    that page. They are occasionally available directly from distributed.net 
    coders in the #distributed channel on EFNet IRC. FreeBSD clients are 
    also available on FreeBSD Distribution CDs. 

    Once you have downloaded the client, it is a simple matter of getting
    going. Simply unpack/unzip/unarc the archive you downloaded and fire 
    it up. 
    
    If you have never run the client before, it will initiate the
    menu-driven configuration. Save and quit when done, the 
    configuration file will be saved in the same directory as the 
    client. Then, simply restart the client. From that point on it will 
    use the saved configuration.
    
    Each configuration option is accompanied by a description that will
    assist you in making the right decisions. Most default values can be
    accepted as-is. Refer to the Help! section at the end of this document
    for sources of assistance.

    A "Complete Step-by-Step Guide to Running Your First Client" is 
    available from http://distributed.net/faq/

    The client's configuration may be adjusted at any time by starting 
    the client with the -config switch. A list of other command line 
    options can be obtained by starting the client with -help.


 4.0  Upgrading from a client older than the 2.7xxx ------------------

     If you are upgrading from a version of the client older than the 
     2.7xxx series, please stop the existing client, flush its buffers, 
     delete all of its files before installing the new client. Buffer 
     files formats have changed, and this will help prevent compatibility 
     problems. If you are sharing buffer files between multiple clients, 
     please make sure that the clients have compatible buffer formats.

                                                                     
 5.0  Fetching and flushing blocks -----------------------------------
 
     For network communications, the distributed.net RC5DES client uses 
     a proprietary communications method to talk to a network of 
     keyservers using TCP/IP protocols. 
   
  5.1  Connecting through a firewall -------
     
     If you are connected through a strict firewall, port 2064 will 
     probably be blocked by default. There are four primary methods to 
     communicating through a firewall:
     1. Run a personal proxy on the machine that runs the firewall.  
        A personal proxy will receive connections from the client, buffer 
        them, and then communicate with the main proxy network to send/
        receive blocks. The setup of this is simple and reliable; all 
        you must do is download a personal proxy available at 
        http://www.distributed.net/rc5/proxies.html and set it up to run 
        on the machine that functions as the firewall. Then set up all 
        clients behind the firewall to connect to that machine to receive 
        blocks. (The name/address of the proxy may be entered in the 
        configuration in the "keyserver" field under "Network options")
        Naturally, you need to be authorized to run the personal proxy on
        that machine...
     3. The most reliable option for sending/receiving blocks through 
        the firewall if you are unable to directly modify the firewall's
        configuration is to use SOCKS support (if your firewall supports 
        it, of course.)  To configure SOCKS, enter the "Network Options" 
        menu and select "Firewall Communications Mode". If you are using 
        a SOCKS4 proxy, choose "SOCKS4", or choose "SOCKS5" if you know 
        the firewall supports SOCKS5. If you are unsure as to which 
        version of SOCKS you are using, select SOCKS4. Now, edit the
        Proxy address and port and ensuring that they point to the SOCKS 
        proxy you will be communicating through. If you must use a SOCKS 
        userid/password, enter it in the appropriate field as well.
     3. The next most reliable option is to set the firewall to allow
        connections through to port 2064 (the port the client uses for
        communication to the keyservers) either directly, through a 
        "datapipe" or if you are using WinGate or Internet Gate, via 
        "direct port mapping". All of these are require administrative 
        access to the firewall host.
     4. The most compatible firewall communications method is to use the
        http proxy support of the client. Enter "Network Options", select
        "Firewall Communications Mode" and set "HTTP encoding". Next,
        enter the name/address of the HTTP proxy in the "HTTP/SOCKS proxy 
        address" field and the port number of the HTTP proxy in the 
        "HTTP/SOCKS proxy port" field. If you have problems with "HTTP
        encoding", you may wish to try "HTTP+UUE encoding" instead.

     Firewall software Known to work with the distributed.net client.

     Software              Platform    Method       Download from
     --------------------- ----------- ------------ -------------------
     Squid                 Unix        HTTP Proxy   http://squid.nlanr.net
     Internet Gate         OS/2        Port Mapping
     MS Proxy Server       WinNT       HTTP Proxy
     Novell BorderManager  NetWare     HTTP Proxy
     Purveyor HTTP Proxy   VMS/NetWare HTTP Proxy
     Wingate 2.x           Win32       HTTP Proxy,  http://www.wingate.com
                                       Port Mapping,
                                       SOCKS, telnet
     AltaVista 97 proxy    Unix/Win32  HTTP

  5.2  Flushing and fetching via e-mail ----

     If you can not get your client to flush/fetch directly (due to a 
     very stringent firewall), or are running a networkless client, 
     such as the MS-DOS client, there is one last way for you two 
     receive blocks to process: e-mail.

     1. Send a message to fetch@distributed.net; an auto-responder 
        will reply with information on the proper options to use.
     2. Once you know the correct format, send a correctly formatted 
        message in. You should quickly receive a message back with 
        the specified number/size of blocks attached as "buff-in.rc5".
     3. Stop the client. 
     4. Save the file to the directory from which you are running the 
        client. 
     5. Restart the client.

     Once your client has completed the blocks provided to it, you may 
     send in the completed blocks via e-mail as follows:

     1. Create a message to flush@distributed.net with the file 
        "buff-out.rc5" attached as a MIME64 encoded file. You will 
        be send a "receipt" of the proper flushing within a few 
        minutes.
     2. Delete the buff-out.rc5 file so that you do not accidently 
        send part of its contents twice.

                                                                     
 6.0  Help! ----------------------------------------------------------

     If you've having a problem with the client, the first place you 
     should visit is http://www.distributed.net/des/clients.html to 
     see if a newer version is available. It is likely that a given 
     bug you have been experiencing will be fixed by the new version.

     If you are still having problems, here are a few places you can 
     find help (in order of responsiveness).

     - The quickest way to get question(s) answered about the operation 
       and setup of the client is to connect to an EFNet IRC server and 
       join the channel #distributed. Although there are dozens of EFNet
       servers world-wide, the following should give you a starting point:
       In the U.S: irc.cs.cmu.edu:6667, ingenue.eecs.berkeley.edu:6667,
       piglet.cc.utexas.edu:6667. In Europe: irc.ec-lille.fr:6667, 
       irc.nijenrode.nl:6667, or efnet.demon.co.uk:6667 

     - If you need further assistance with client use or operation, refer 
       to the the list of "Frequently asked Questions" (FAQs) available 
       online at http://www.distributed.net/faq/  Documents cover every 
       aspect of running a client including "The Complete Step by Step 
       Guide to Running Your First Client", "How To Join A Team", and 
       the popular "Statistics Server FAQ".

     - If you don't mind your mailbox receiving a few messages a day, 
       you may consider subscribing to the general RC5DES mailing list
       at <rc5@lists.distributed.net> (To subscribe to the mailing list, 
       send a message to <majordomo@lists.distributed.net> with 
       "subscribe rc5" as the message text).

     - A public database of known problems and incompatibilities is 
       available at http://www.distributed.net/cgi/buglist.cgi

     - More user support is available from <rc5help@distributed.net> 
       as well as from our regional support representatives listed at 
       http://www.distributed.net/regional/index.html
    
     - If you believe you have found a bug in the client or would like 
       to make a suggestion, please send a message to the coders at 
       <coders@lists.distributed.net>. Don't forget to specify which 
       platform you are running the client on. 
    
     - If you believe you have found a bug specific to this port, or 
       would like to make a suggestion specific to this port, send a 
       message to the port maintainer as listed at 
       http://www.distributed.net/credits.html
       Don't fret if you don't get a response right away - porters are
       usually very busy and it may take weeks before they get around 
       to answering your message.
       
