John the Ripper v1.4
   ----------------------

==========================
 What is John the Ripper?
==========================

John the Ripper is a UNIX password cracker, currently available for UNIX
(tested with Linux x86, FreeBSD x86, Solaris 2.x SPARC, OSF/1 Alpha), DOS,
WinNT/Win95.

I assume that you have already used some UNIX password crackers, so I'll
only describe the things specific to John.

==============================
 What's new since version 1.3
==============================

- MD5 based password files support;
- SPARC V8 assembly version;
- a lot of bugfixes.

==========
 Overview
==========

John the Ripper is designed to be both powerful and fast. It combines
several cracking modes in one program, and is fully configurable for your
particular needs (you can even code a custom cracking mode using the built
in C compiler). Also, John is available for several different platforms,
which enables you to use the same cracker everywhere (for example even
continue a cracking session that you started on another platform).

John's crypt() routine is highly optimized for faster operation, which
makes John run much faster than other crackers. This applies to both the
assembly versions, and the portable pure C one.

John the Ripper supports the following cracking modes:
- wordlist with or without rules;
- "single crack", makes use of the login/GECOS information;
- incremental, tries all character combinations;
- external, allows you to define your own cracking mode.

================
 How to install
================

With binary distributions, just copy all the files to a separate directory.
Then extract the common files there (supplied in a separate archive). You
might also need a 'chmod +x john' depending on the archive type used.

To compile the sources, just enter the directory you extracted them to, and
type 'make'. You'll get a list of systems supported. Select one of those,
or try 'make generic' if your system is not listed. Be sure to use GCC and
GNU make (you might have to type the full path to 'make', since '/bin/make'
is often also present and is not what you need).

============
 How to use
============

I intentionally made John's command line interface be a lot like Cracker
Jack's so that it's easier to start using John for those who have used
Cracker Jack before. Anyway, here's a short description of John's features
including those that are the same as Cracker Jack's.

To use John the Ripper, you need to supply it some password files, and a
cracking mode. Cracked passwords will be printed on the screen and saved
in file called ~/john.pot (in this text '~' means John's "home directory",
i.e. the directory you put John's binary in). This file is also used not
to load the accounts you already cracked if you run John again on the same
password file. To retrieve the cracked passwords from ~/john.pot, use the
'-show' option.

While cracking, you can press the Enter key for status, or Ctrl+C to abort
the session, saving point information to a file (~/restore by default).
By the way, if you press Ctrl+C twice John will abort immediately without
saving. The point information is also saved every 10 minutes in case of a
crash.

 Command line options
----------------------

You can specify some of the following options on John's command line (all
of them are case sensitive, and can be abbreviated):

       -pwfile:[,..]     specify passwd file(s) (wildcards allowed)

This option is used to specify the password files to be cracked (actually,
anything on the command line that is not starting with a dash will be used
as a password file name).

       -wordfile: -stdin wordlist mode, read words from  or stdin

These are used to enable the wordlist mode.

       -rules                  enable rules for wordlist mode

Enables rules (like in Crack by Alec Muffett). The rules are stored in
~/john.ini, in section [List.Rules:Wordlist].

       -incremental[:]   incremental mode [using john.ini entry ]

Enables the incremental mode, using the specified ~/john.ini definition
(section [Incremental:], where  is what you specify on the
command line, [Incremental:All] by default).

       -single                 single crack mode

Enables the "single crack" mode, using rules from [List.Rules:Single].

       -external:        external mode, using john.ini entry 

Enables an external mode, using external functions defined in ~/john.ini's
[List.External:].

       -restore[:]       restore session [from ]

Continues an interrupted cracking session, reading point information from
the specified file (~/restore by default).

       -makechars:       make a charset,  will be overwritten

Generates a charset file, based on character frequencies from ~/john.pot,
for use with the incremental mode. The entire ~/john.pot will be used for
the charset file unless you specify some password files. You can also use
an external filter() routine with this option.

       -show                   show cracked passwords

Shows the cracked passwords in a convenient form. You should also specify
the password files.

       -test                   perform a benchmark

Benchmarks the performance critical routines and prints a table of estimated
cracking speed values for different number of accounts and salts.

For those unfamiliar with password crackers internals: xform1() and xform2()
are the actual encryption routines, called for each key/salt pair, while
setkey() is called for each word only, meaning that xform1() or xform2()
(depending on the cracking mode used) are the only routines that will affect
cracking speed if there're enough salts loaded. By the way, setkey() is
benchmarked assuming that words differ by 1 character in length, and 1 more
character replaced -- when using with xform2(), and that passwords are 8
characters long and are totally different (no matching characters) -- when
using with xform1(). When cracking MD5 based password files, md5crypt() is
used instead of all the other routines.

       -users:[,..] crack this (these) user(s) only

Allows you to filter a few accounts for cracking, or for '-show'.

       -shells:[!][,..] crack users with this (these) shell(s) only

This option is useful to crack/show accounts with the required shell only,
or not to crack/show accounts with a bad shell ('!' before a shell name
means 'not'). You can omit the path before a shell name, so '-shells:csh'
will match both '/bin/csh' and '/usr/bin/csh', while '-shells:/bin/csh' will
only match '/bin/csh'.

       -salts:[!]       crack salts with at least  accounts only

This feature sometimes allows to achieve better performance. For example
you can crack only some salts using '-salts:2' faster, and then crack the
rest using '-salts:!2'. Total cracking time will be about the same, but
you will get some accounts cracked earlier, and may not need the rest.

       -lamesalts              assume cleartext passwords were used as salts

Don't use this option unless you know what you're doing.

       -timeout: