                             brutessl version 1.03
                              User Documentation


Copyright (C) 1995 Andrew Roos
All Rights Reserved


1.  Introduction

brutessl  uses  exhaustive  searching  to  attack SSL messages which have been
encrypted using RC4 in 40-bit "export" mode.  It  is  intended  to  illustrate
that  a  40-bit  key  size is inadequate. brutessl was written in South Africa
and is freely available both within and outside the United States.

This program is licensed for academic and educational use only. It may not  be
used  for  any  commercial purpose. You may modify the program if you wish to,
provided that the original copyright  notice  and  license  restrictions   are
retained,  and  that  you  include a notice stating that you have modified the
program and giving details of the changes that you have made. This program  is
distributed  without  any  warranty including, but not limited to, the implied 
warranty of merchantability or fitness for a particular purpose.  


2.  Installation

brutessl  is distributed as three C source files: "brutessl.c", "search.c" and 
"assembly.c", a header file "brutessl.h" and this file "brutessl.txt".  Please 
note  that  "search.c" and "assembly.c" contain the same functions, and one or
the other, but not both, should be used. "search.c" contains the time-critical
search  routines  written  in  ANSI standard C. "assembly.c" contains the same 
routines written in Intel 386/486 assembly language using the inline  assembly
syntax  supported by 32-bit Microsoft Visual C++. The C source has been tested
on several platforms and is the "reference" implementation  of  brutessl.  The
assembler routines have only been tested using Visual C++ 1.1 under Windows NT
and are provided for those who wish to get their hands dirty in  exchange  for
a 20% performance improvement.

Before  compiling  either  version,  you  may  need  to change "brutessl.h" to 
specify the type which represents a 32-bit unsigned word on your platform. The
default  is  "unsigned int". If you are using the C version of "search.c", and
your platform provides a native funtion to rotate 32-bit words left, then  you
can set the macro "rotate_left" in "brutessl.h" to this function. If you don't
specify a rotate_left macro, a generic macro will be used which should work on 
all platforms but which is slightly slower than a native function would be. 

To  compile  the  straight  C  version  of brutessl, you require "brutessl.c",  
"search.c"  and  "brutessl.h".  These  files  should  be  compiled  with  full 
optimization. A typical UNIX command would be:

    cc -O2 -o brutessl brutessl.c search.c

You  can  compile  the  hybrid C and assembler version under 32-bit Visual C++
from the IDE  by  creating  a  project  file  "brutessl.mak"  with  the  files 
"brutessl.c" and "assembly.c" and selecting "Release" as the build mode. 

Once  you  have  successfully compiled brutessl, you should run a self test to 
ensure that everything is working correctly and to find out how fast  brutessl 
runs on your hardware:

    brutessl -t

This  should  take between 3 and 60 seconds and will report the number of keys 
searched per second. On a 486 DX2/66 running Windows NT I  get  the  following
speeds when the system is otherwise inactive:

    C version with no rotate_left macro:      14100 keys/sec
    C version with __rotl() as rotate_left:   15000 keys/sec
    Hybrid C and assembly version:            18000 keys/sec

Your  results will depend on a number of factors: most importantly, SSL uses a 
lot of 32-bit arithmetic, so if you are using a hardware platform or  compiler  
which  does  not  support  native 32-bit operations, it will proceed at a much 
more leisurely pace. 

If  you  get an error message complaining about type "word", then consult your
compiler documentation to ensure that the type defined as "word" in brutessl.h
is indeed an unsigned 32-bit integer. If you get error messages  objecting  to
your  platform's  byte  ordering,  or  saying  that time is going backwards or 
standing still, then drop me an email with details and I'll try to help.


3.  Operation

brutessl reads details about the message to be attacked from a parameter file,
which  is  just  a  text file which follows a particular format. The format of 
parameter files is dicussed later but one  called  test.pf  is  included  with 
brutessl. In  order  to  facilitate  the  search process, brutessl divides the 
40-bit key space into 65536 segments of 24 bits  each.  That's  about  sixteen  
million  keys  per segment. Each segment is identified by a 4-digit hex number 
from 0000 to FFFF. Segment numbers and other hex data  can  be  entered  using 
either upper or lower case letters, but leading zeros must not be omitted.

In  order  to search a keyspace, you need to specify the name of the parameter 
file, a checksum for the parameter file, the starting segment for  the  search  
and the number of segments to search. For example:

    brutessl test.pf 29de 38ac 2

This  tells  brutessl  to search for the keys for the SSL message described in 
test.pf, which has the checksum 29de, starting at segment 38ac  and  searching 
two  segments. Try it if you like, the key should be found at the start of the 
second segment searched. (If you're in a hurry, then of course you could  just 
start at segment 38ad).

After running the self test brutessl will report how long the search is likely
to  take.  As  each  segment  is  searched, it will display the segment number 
followed by a slowly growing row of dots. Each dot represents 2^18 bits of key
space,  or  about  260 000  keys  searched,  so  64 dots are printed for every 
segment searched. When  the  key  is  found,  brutessl  displays  the  message 
"Eureka!"  followed by the encrypted  portion  of  the SSL master key. For the 
example given above, you should see something like:

------------------------------------------------------------------------------
                                brutessl 1.03

Self test... OK

18 minutes and 40 seconds per segment, 15000 keys per second.
This will take about 19 minutes.

Segment 38ac: ................................................................
Segment 38ad: ..

Eureka!

Encrypted Master Key: 38ad47bb06
------------------------------------------------------------------------------

Search  parameters  can  also be read from standard input by giving "-" as the
name of the parameter file.

If  like  me you don't like to waste CPU cycles but can't be bothered to enter 
the starting segment and number of segments to search, try the "random search" 
option:

    brutessl -r test.pf

This will search segments at random until a solution is found or you get tired
of watching dots crawl across the screen. Just for completeness you  can  also
specify the number of randomly chosen segments to search, for example:

    brutessl -r test.pf 10

This will search ten segments at random. 

brutessl  can  help  you determine how many segments you can search in a given 
time, which is particularly useful when you are collaborating with  others  to
search a key space and need to know how many segments you should be allocated.
If you want a search which will take about twelve hours, you can type:

    brutessl -t 12

As  well as the usual test results, brutessl will report how many segments can
be searched in the given time. The display should be something like:

------------------------------------------------------------------------------
                                brutessl 1.03

Self test... OK

18 minutes and 40 seconds per segment, 15000 keys per second.
38 segments will take about 11 hours 49 minutes.
------------------------------------------------------------------------------

Note that brutessl is conservative and will suggest a number of segments which
should take less than the specified time. However due to the resolution of the 
system timer and changing system load, there is no guarantee that  the  search  
will  complete  within  the  time allocated, so if this is critical you should 
allow some time for overrun. You can specify the time in  hours  and  minutes, 
for example "brutessl -t 11:30".


4.  Batch Programming

All  the  brutessl  commands can be preceded by the "-q" flag which suppresses
extraneous output, printing only  results  (and  error  messages  on  standard 
error).  The  results  are  formatted  in  a  way which is intended for use by 
automated search systems. In each case a single line  is  printed,  containing 
zero  or  more  fields  with a  single  space  between fields. Hex numbers are 
output using lower case letters,  without  any  embedded  spaces.  The  output 
formats and exit status with the "-q" option are as follows:

    brutessl -q <file> <checksum> <start seg> <no of segs>

The  string "brutessl" is printed, followed by the version number (eg. "1.03"), 
followed by the file checksum (4-digit  hex), the  completed-search  checksum 
(4-digit hex), the starting segment (4-digit hex) and the number of  segments  
searched  (decimal  integer). If the search was successful then the encrypted 
portion of the master key is printed (10-digit hex) and  the  program's  exit  
status  is 0, otherwise the string "no" is printed and exit status is 1. Exit 
status is 2 on error. The completed-search checksum is just the file checksum
added to the start segment and number of segments searched (mod 65536).

    brutessl -q -r <file> <start seg> [<no of segs>]

If  the  master  key was found then the encrypted portion of the master key is 
printed as a 32-digit hex number, otherwise nothing is printed. Exit status is 
0 if the master key was found, 1 if the search was unsuccessful, 2 on error.

    brutessl -q -t [<time>]

The  number  of seconds per segment is printed as a decimal integer. If a time 
was given this is followed by the recommended number of segments. If the  time 
given is less than the time required for a single segment, this field will  be  
zero. Exit status is 0 on normal termination, 2 on error.

    brutessl -q

The  brutessl  version number is printed as a decimal value "major.minor" in a 
single field. Exit status is 0.


5.  Parameter File Format
    
Parameter files are text files which give brutessl information about a search.
Each  line  of  the file consists of a keyword and a value, separated by white
space. Keywords are not case sensitive.  Values  are  either  decimal  or  hex 
integers,  depending  on  the keyword. Hex integers are written using upper or
lower case letters but should  not  contain  embedded  spaces.  The  following 
parameters are recognised:

clear-master      11 bytes hex.  This is the unencrypted portion of the master 
                  key, which is found in the SSL CLIENT-MASTER-KEY message.

challenge         16  bytes hex. This is the challenge data sent by the client 
                  to the server in the CLIENT-HELLO message.

connection-id     16 bytes hex. This is the connection ID sent from the server 
                  to the client in the SERVER-HELLO message.

server-verify     8  bytes  hex.  This  is  bytes  16-23  of the SERVER-VERIFY 
                  message,  in  other  words  the  first eight bytes following 
                  the MAC. The first byte is the message, SSL_MT_SERVER_VERIFY  
                  encrypted  using  the  client read   key.  The  remaining  7 
                  bytes are the first 7 bytes of the CHALLENGE, also encrypted 
                  using the client read key.

client-finished   8  bytes  hex.  This  is  bytes 16-23 of the CLIENT-FINISHED 
                  message, in other words the first eight bytes following  the 
                  MAC.  The  first byte is the message, SSL_MT_CLIENT_FINISHED 
                  encrypted using the client write key. The remaining 7  bytes 
                  are  the  first 7 bytes of the CONNECTION-ID, also encrypted 
                  using the client write key.

comment           Text following the "comment" keyword is ignored, although it
                  is used to calculate the checksum. 

brutessl  uses  the SERVER-VERIFY or CLIENT-FINISHED parameters to calculate a
known RC4 output stream, which is tested against the output streams  generated 
by the keys it tries. One of these parameters must be specified but not both.


Andrew Roos <andrewr@vironix.co.za>                               PO Box 50494
July 1995                                                         Waterfront
                                                                  8002
Privacy is feared only by tyranny.                                South Africa
