
/*
The contents of this file contain text and code describing and 
implementing the 'DES' encryption algorithm. Despite the fact 
that this information is freely available overseas, it remains 
a violation of ITAR and/or EAR to export this information 
from inside the US or Canada to outside the US or Canada, or 
to pass it to a non-US or non-Canadian citizen within the US 
or Canada. The US Government evidently defines 'Export' to 
include placing this information on a non-restricted FTP server 
or Web site. Please do not do so, and be sure that any person you
pass this on to is made aware of this restriction.
									Peter Trei
									ptrei@acm.org

 * THIS SOFTWARE IS PROVIDED BY PETER TREI ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.

This software is copyright (c) 1997 Peter Trei (ptrei@acm.org), except for
those portions written by Phil Karn, which retain their original ownership.

This software may be redistributed freely for use in the RSA DES Challenge,
but please obey the restrictions imposed by the US Government, and make
sure that anyone you pass it to is also aware of them.

This software may not be used for commercial purposes without the written
permission of Peter Trei and the other owners.

Please redistribute only as a complete, unmodified package, including 
source code, and ptrei@acm.org's PGP signature file and key.

 */

DES Key Recovery Software, version 0.3
Peter Trei
Sunday, 26 Jan 1997

This is a manual for the pre-release version of DESKR. I'm releasing
this version mainly so that I can announce at the RSA Data Security
Conference on Tuesday that 'hundreds of PCs are already working on
the DES Secret Key Challenge'.

This version will be followed soon after the conference by another, 
hopefully 1.0, which will have the actual challenge data built into
it, as well as a better manual, and perhaps, improved performance.

First, word of warning.

Since DESKR implements the DES algorithm, it is restricted by ITAR
and/or EAR. You cannot export this software from the US and Canada, nor
give it to a non-citizen of the US and/or Canada (foreign residents of
the US holding 'green cards' are ok, too). The Commerce Department's
definition-of-the-day of 'export' appears to include putting software on
a non-restricted ftp or web site, as well.

-----------------------

DESKR has been written initially for Intel PCs running Win95 or WinNT.
The compiled executable (deskr.exe) supplied with this distribution is
for these platforms. It can also be compiled to run on some varieties of
UNIX.

-----------------
Unpacking the distribution.

I distribute DESKR as a signed, nested zipfile, ala MIT's PGP
distribution.  Unpacking the distributed zip file produces another
zipfile, some warning and documentation files, a detached signature file
for the inner zipfile, and a PGP public key file.

I reccomend that you check the supplied key against that at my webpage,
(http://www.ziplink.net/users/trei/crypto.html), then use it to verify
the detached signature on the inner zipfile. This will give a high
degree of assurance that the code you received is that same as that I
sent.

Unpacking the inner zipfile produces source files, support files, and
a Win95/NT executable.

----------------
DESKR reads and writes a number of files:

testchal.txt, deskr.inp

testchal.txt - Test challenge data, cut and pasted from RSA's web page.
deskr.inp - real challenge data, cut and pasted from RSA's web page.
	Any given version of DESKR will read only one of these files. 
0.3 looks for testchal.txt. Later versions, once the 'real' challenge
data is available, will look for deskr.inp. If the sought-after file
cannot be found, DESKR falls back to working on challenge data built
into the program itself. A file input mode is included for two reasons:
1. To allow people to start working on the real challenge data the
moment it becomes available.
2. To allow people to provide their own challenge data, in case they
wish to verify the program's operation.

desident.txt 
     A short, single-line identifier of the searcher. example: "Peter
Trei ptrei@acm.org". This is put into the results file so that the
person who did the work can be identified. If this file cannot be found
'Unknown' is used (this feature may dissapear in later versions).

chkpnt.des, chkpnt.tmp.

    These files are used to 'checkpoint' the program's status. Every 10
minutes, DESKR writes a status file. If the program is interrupted, on
re-start it will read the most recent checkpoint file, and restart at
the point where it wrote that file. Thus, interrupting the program and
restarting loses at most 10 minutes work.

deskr.out, lockfile.txt

    Each time DESKR finishes a 'chunk' (2^32 keys) of keyspace, it 
appends an entry to deskr.out. This specifies the results of the
search, including the version of the software used, the output format,
the 'checksum' and 'halfmatches' (used to make sabotage more difficult),
the identity of the searcher, the chunk searched, and the result of the
search. If a shared disk is used, with many programs writing to the same
file, a lockfile is used to prevent simultaneous updates.

solution.txt

If you're lucky enough to find the key, DESKR writes an output file to
be emailed to RSA. This requires some editing by hand before it's sent.
If deskr starts up and finds that solution.txt already exists,  it will
not run. A bogus solution.txt file will be created if you run DESKR in
such a way that it 'finds'  a key for the challenge data.


----------------
Installation.

DESKR is a console app - it runs in a 'DOS box' under Windows. It is
designed to be run in background, any time the computer is switched on.
Set up properly, it will use any spare cycles the computer has, yet not
interfere in normal operations. This is even more effective than the
screen saver many people have discussed, since it reaps spare cycles
even when a screen saver is not active.

I envisage two main ways it will be used: a LAN environment with shared
disk servers, and on standalone, non-networked computers. In the LAN
situation, many different computers can run the same copy, 

DESKR learns about the mode in which it is being used by checking for
the existance and content of two environment variables: DESKRLOCAL and
DESKRSHARE.

DESKRSHARE, if it exists, points to a directory for shared files, such
as the challenge data, the results file, the solution file, and possibly
the searcher identity file. This directory must be readable and writable
by all the systems on which DESKRSHARE is defined.

DESKRLOCAL, if it exists, points to a directory for files specific to
DESKR running on a single machine. These are the checkpoint related
files, possibly the searcher identity file, and if DESKRSHARE is not
defined, the files that would have been in it as well.

If neither DESKRSHARE or DESKRLOCAL is defined, then for files which are
read-only, the directory in which the DESKR executable exists is checked
first, followed by the connected directory. For files which will be
created, only the DESKR program directory is checked.

Therefore, to set up DESKR:

LAN environment:

Create a world readable/writable directory on the server, and have all
machines define the environment variable DESKRSHARE to point to it. The
DESKR executable can be put in this or another directory on the server.
DESKRSHARE also holds the file (testchal.txt or deskr.inp, depending on
DESKR version), which contains the challenge data to work on. It can
optionally contain the searcher identity file. DESKRLOCAL can also be
defined, and should point to a directory on  each machine's local disks.
This will hold checkpoint data for this machine. Add lines to the
autoexec.bat of each machine to set DESKRSHARE and DESKRLOCAL, and
to start up DESKR at system startup time:

set DESKRSHARE=z:\serverdisk\deskr
set DESKRLOCAL=c:\localdisk\deskr
start /low /min %DESKRSHARE%\deskr (for windows NT only)
start /min %DESKRSHARE%\deskr (for windows 95 only)

Standalone environment.

You can set up DESKRSHARE and DESKRLOCAL if you want to control where
files will go, or just stick all the files in the same dir. Add a line
to autoexec.bat to start off the program at system startup, as shown
above.

-------------------------
Command line switches:

DESKR has a number of command line switches.

 -h 
	Help. Prints a brief usage message.

 -t
	Test. Runs a self-check of the correctness of the DES algorithm,
	and a speed test.

 -q	
	quiet. Suppresses the annoying banner. Can be combined with
	other switches.

 -i	
	Info. Turns on verbose mode, in which it indicates where it is
	looking for files, the challenge data it is using, and while
	searching gives a running count of its progress through each
	chunk. Can be combined with other switches.

 -c xxxxxx
	Chunk. Start searching at the specified hexadecimal 'chunk'.
        Continue to the next chunk when this one is finished.

 -k xxxxxxxxxxxx 
	Key. Try the specified hexidecimal key against the challenge
        data. DESKR will report success or failure, and the decrypted
	message if found. It will also put an entry into deskr.out, and
        write a solution.txt file.

If DESKR is started without any switches, it will look for a checkpoint
file. If found, it will use the data therein to continue it's work. If
no checkpoint file can be found, it will pick a random chunk at which
to start (and checkpoint that information for future use).

----------------
Theory of operation. 

The RSA challenge consists of an encrypted message, the first few bytes
of which are known. We need to find what key decrypts the first few
bytes of the encrypted message to the expected plaintext. We can then
use this key to decrypt the entire message.	

DESKR works by sucessively testing all the possible keys against the
challenge data. Keys are grouped into 'chunks' of 2^32 keys. This is the
minimum number of keys which will be checked before an entry is added to
deskr.out, unless the target key is found.

For a variety of performance reasons, keys are not searched in numerical
order. The 'chunk' number does not directly reflect the upper 24 bits of
the key, either - there's a minor reshuffle involved. Within a given
'chunk', the keys are tested in a modified Gray code order. Any given
key exists only in one chunk - there is no overlap.

-------------------
Known bugs in this distribution.

DESKR.OUT does not indent half-matches.

The version string does not change when compiled with generic 'C'
vs the assembly language. This may effect the checking of the
checksum and the halfmatches.



