THIS WAS A MACHINE TRANSLATION!
I HAVE NO TIME TO CORRECT IT - WHO CAN HELP, E-MAIL ME PLEASE!
----------------------------------------------------------------
Changes in the versions:

2.0c
  - minor improvements and bug-fixing. Sources available.

2.0b
  - ".c(1) not defined" error message has been appeared although you are not
using .c(1). Has been fixed. Passwords counter is now unsigned long long
for gcc compiler and double for others. Password printing in hex has been
added. Compiled with Pentium Pro/II optimizations.

2.0a
  - "5th line" bug fixed. Only password definitions greater than
4 lines have been affected. Thanks to Dmitry Lisiy.

2.0:
- Added: the support of different languages and encodings, charset
definition, new modifiers and their parameters, timing and benchmarking,
maximal password length now depends only by amount of free memory.
The sense of max_psw_len, min_psw_len parameters is changed.

1.1:
- The small bugs are corrected. The support of special character sets is
added.

1.0:
- First version released.
-----------------------------------------------------------------


           Password Cracking Library (PCL) v. 2.0c.

        (c) Copyright PSW-soft 1996-98 by P. Semjanov


THIS PROGRAM  IS DISTRIBUTED  "AS IS".  USE IT  AT YOUR OWN RISK.
PCL comes with ABSOLUTELY  NO WARRANTY. The AUTHOR  also DOES
NOT GUARANTEE releasing any future VERSIONS of the program.

PCL is FREE for non-commercial use, see license,txt


1. Purpose and characteristics.

The Password Cracking Library is designed for simplification of
writing password cracking applications and allows to facilitate
the following actions:
- Multifunctional dictionary attack;
- Brute force attack (with known characters);
- Recovering the incorrectly typed password and more.

The library is released in source form and should be compatible
with most DOS/Windows/UNIX C compilers. (You also need YACC to
build the library).


2. Password definition file (PDF).

The password definition file is a main control file. The parsing
and processing of PDF is purely the basic task of library PCL.
Its format  is independent  of the  application PCL is linked,
therefore this library can be used with any password cracking related
program.

2.1. Format of the password definition file.

Password definition file is a plain text file divided on two parts:
the description of the dictionaries and character sets and the description of
the password.
These parts are divided by '##' line:

[ <the description of the dictionaries and character sets> ]
##
<the description of the passwords>

The first part can be absent, then the file should begin with symbols '##'.
In any other place the symbol '#' is considered as the beginning of
the comment. The blanks and tabulation in a PDF file are
ignored and can divide any components.
For a convenience, at the beginning, let's consider the mechanism of
the description of the passwords and then description of character sets.

2.2. Description of the passwords.

It is a main part of a file, obligatory present in any password definition file
after "##' line. It consists of plain text lines, each  of
them describes the passwords sets and working mode. Each line is independent
and is processed separately, thus the total number of the checked passwords
is counted up. The basic components of the  password definition file  are:
character sets and words from  the dictionaries.  They describe one or
several symbols that will be place in the appropriate part of the password.

2.2.1. Character sets.

The character set (charset) is set of symbols, which can be on  a
actual place in the password  (but there is, naturally, only  one
of them). To can be the following:

 1) Simple single symbols (a, b, and etc.). It means that in  the
given  position  of  the  password  there  is just this symbol.

 2) Shielded symbols. The special symbols, if they are met in the
password should be shielded. The sense coincides with  previous.
They are:

  \$, \., \*, \?, \=     - "$", ".", "*", "?", "="
  \], \[, \ , \}, \(, \) - appropriate brackets
  \ (space)              - space
  \\                     - "\"
  \XX, where X is hex-digit - any symbol in hex-code
  \0 - empty symbol (absence of a symbol). Is usually applied  in
association with the "present" symbol (see examples below).

Basically, any symbols can be  shielded , if they are  not hex-digits.

  3) Symbol set macros.  These sets are
defined in the first part of a PDF file (see 2.3.2). It means that in
a current  position of the  password may be any  symbols, determined
by following macros:

  $a - lower Latin letters (if not redefined, in total 26 possibilities);
  $A - upper Latin letters (if not redefined, in total 26 possibilities);
  $! - special symbols (if not redefined,  32 possibilities);
  $1 - digits (if not redefined,  10 possibilities);
  $i - lower national letters;
  $I - upper national letters;
  $o - User's set;
  ?  - Any symbol, i.e. all chars included in these macros.

Note: $v and $p (see 2.3.4) could not be used to generate passwords.

4) The combination of any of the symbols mentioned above. Is described
using square brackets. The sense coincides  with previous.

Examples (`"` used only for convince, don't include it in real PDF file) :

"[$a $A]"                - any Latin letter;
"[abc]"                  -  a, or b, or c;
"[$1 abcdef]"            - hex-digit;
"[s \0]"                 - s or nothing;
"[$a $A $1 $! $i $I $o]" - is equivalent to ?

5) Regular symbol of recurrence "*". Means that the previous character
set needs to be repeated 0 or more time in the appropriate
positions of the password. Examples:

"$a *"      - password of any length from the small Latin letters;
"[ab] *"    - will produce empty password, a, b, aa, ab, ba, bb, aaa...
"[$a $A] [$a $A $1] *" - "identifier" (a sequence of the letters and
digits with first letter).

Let's note, that the password with zero length has the certain
physical sense, and not always is equivalent to absence of the password.
Length of recurrence is calculated automatically on the basis of given maximal
and minimal length of the password by a call of the basic function of library
parse_rules_file(). (Look at prototype of this function in PCL.H file).

Let's note, that these parameters affect only length of the
passwords generated using the '*' symbol and are ignored if the password
consists only of words or static symbols.

It is recommended to use "*" as often if possible due to the fact  that
it will create the most effective brute force attack.

Current restriction - "*" can only be the last element of a line.

2.2.2. Words from the dictionaries and their modifiers.

Contrary to a character set, the word set uses not one but a several
symbols of the password continuously. The PCL  library supports
two dictionaries: the basic one (where regular words are usually stored)
and user one (where is the specific information such as names or dates).
The dictionary is a text file consisting of  words, divided by end of a
line (EOL) symbols. Files such as DOS- (CR/LF), and UNIX-format (LF)
can be used. It is  desirable (for example, for brute force speed) to have
all words in one (lower) case.

  Thus, two macros exist:

$w - the word from the basic dictionary
$u - the word from the user dictionary.

So, the simplest dictionary attack can be written as PDF line
"$w".

Also as the words  can be described special sets, since they  can have
any length. They are marked as $s(1), $s(2),... and are determined
to be specific to an application.

Using of special charsets it is meaningful only in the certain place. Let's
assume, that $s(1) determines the first two symbols of the password,
and $s(2) - third. Then only following examples make sense:

"$s(1) $s(2)"
"$s(1) ?"
"?? $s(2)"

Is well known the passwords often are altered (modified) words. Therefore
for describing such  passwords the set of modifiers are introduced.
You can use the following word modifiers :

.u (upper) - convert to uppercase;
.l (lower) - convert to lowercase;
.t (truncate) - truncate at given length;
.c (convert) - transform the word;
.j (joke) - convert to uppercase some letters;
.r (reverse) - reverse the word;
.s (shrink) -  shrink the word;
.d (duplicate) - repeat the word 2 times.

The modifiers can have parameters which are written down in parentheses. If
modifier can be used with single character, it is possible to set position of
this character as parameter; the absence of parameter or zero parameter means
"the whole word". Further,  character positions can be set both from a
beginning of a word, and from the end. The end of a word is designated by a
'-' symbol.

Now there are only 3 of such modifiers: .u, .l, .t.
So, (let's assume modifiers are used with 'password' word):

.u or .u(0)   - uppercase the whole word (PASSWORD);
.u(1), .u(2)  - uppercase only first (second) letter (Password, pAssword);
.u(-), .u(-1) - uppercase last (last but one) letter (passworD, passwoRd);
.t(-1)        - cut off last letter in a word (passwor).

Other modifiers work only with the whole words and parameter sets a conversion
mode. Now the following parameters to modifiers are legal:

.j(0) or .j  - uppercase the odd letters (PaSsWoRd);
.j(1)        - uppercase the even letters (pAsSwOrD):
.j(2)        - uppercase the vowels (pAsswOrd);
.j(3)        - uppercase the consonants (PaSSWoRD);
.r(0) or .r  - reverse a word (drowssap);
.s(0) or .s  - reduce a word by removing vowels, if it is not the first
               (password - > psswrd, offset - > offst);
.d(0) or .d  - duplicate a word (passwordpassword);
.d(1)        - add the reversed word (passworddrowssap);
.c(<number>) - convert all letters in a word according to the
conversion string (see item 2.3.3).

All modifiers will correctly work both with latin, and with the national
letters, if national character  are set correctly.

Certainly, that the modifier can be not unique (restriction of their
number in succession is 30 minimum, which is hardly possible to exceed).
The examples:

$w.u(1).u(-) - PassworD
$w.s.t(4) - pssw
$w.t(4).s - pss


2.2.3.  Permutation brackets.

Often the user remembers his password, but it does not  match.
Probably, he was mistaken when he typed it. For recovery of  such
passwords, the program has very powerful algorithm . It considers that
the errors in typing can be following:
- two letters are swapped (psasword),
- one letter is removed (pasword),
- extra letter is inserted (passweord) or
- one is replaced with other (passwird).

Let's name such changes of the password as "permutations".
To indicate the start and end of a possible permutation the
permutation brackets '{' and  '}' are applied . '}' is
followed  by  the  permutation  number  (1 by  default), separated by '.'
or in parentheses. Physical sense of permutation number is a
quantity of simultaneously allowed mistakes. Examples:


{abc} - will produce 182 (different) passwords, such as:
  bac, acb - 2 swaps;
  bc, ac, bc - 3 removals;
  aabc, babc... - 4 * 26 - 3 inserts;
  bbc, cbc... - 3 * 25 replacements;
  abc - and the word itself;

{Password}.2 or {Password}(2) - will generate all words "password" with
2 error such as: "psswrod", "passwdro" and "paasswor";

{$w} - all words with one error from the basic dictionary.

Notes:
1) It is normal, that some passwords will not be produced at  on-
ce, and, the higher the permutation number is, the more recurrences
there will be. Efforts on reduction of recurrences were
made in the program, but they are purely empirical and are untrusted
on permutation numbers greater than 2. Or else, for large numbers
there is no complete reliance, that any password will not be wrongly
throw out.

2) It is necessary to know (for insert and replacement)  which
set of symbols to insert. If this set is not defined (see 2.3.4),
this program defines it automatically, inserting the association of
the standard sets the password characters belong to (i.e. for {password}
should be inserted $a, for {Password} - [$a $A]). For words the similar
operation must  be carried  out on  the first  word from the dictionary,
and modifiers are also used.

3)  Current restriction is: the symbol  '{' should  be first
in a line. The expressions as "good_{password}" are not supported,
but "{good}_password" are welcome.

2.3. Description of the dictionaries and character sets.

All descriptions make in the beginning of a password definition file
above to symbols '##'.

2.3.1. Description of the dictionaries.

In the beginning are usually described the basic and user dictionary (see
2.2.2). It is necessary  only if password description will use words
from the dictionaries, i.e. $w or $ u.

The dictionaries are set as follows:

$w = "<dictionary_filename>"  # the basic dictionary
$u = "c:\\dict\\user.dic"     # additional
Is it necessary to quote the filenames, and to shield the path symbols.

2.3.2. Definition of used character sets.

Used character sets further are usually defined. They are divided
on predefined and set by the user. Predefined consist from:

$a - small latin letters, only 26 chars;
$A - large latin letters, only 26 chars;
$! - special symbols ( {}:"<>?[];\',./~!@#$%^&*()_+`-=\| )  - 32 chars;
$1 - digits, 10 chars.

User-defined sets consist of:

$i - lowercase letters of the national alphabet;
$I - uppercase letters of the national alphabet;
$o - additional set (for example, any non-typed on keyboard symbols).

The definition of sets occurs using the following format:

$<set> = [< single symbols or character sets >]

In other words, the character set are described using the combination
of symbols mechanism (see item 2.2.1), for example:

$o = [$! $1 \FF]

NOTES:
1) You may define any character sets, including predefined. For example,
it is possible to add in $! set additional symbols, such as a blank or \FF.

2) The definition of sets $i and $I automatically determines
rules of upper/lowercase conversion. Therefore it is
important, that the letters in these sets is in the same order.

Only after all character sets are defined, the complete set of
symbols '?' will be formed, consisting of [$a $A $1 $! $i $I $o],
and just in such order (it is important for the following).

2.3.3. Definition of convert modifiers.

Convert modifiers .c (see  2.2.2) should be placed in PDF file
after the character set definitions, because they reference
to complete set of symbols '?'. It could be done using the lines
with format:

?.c(<number>) = " < conversion string > "

Each symbol available in complete set will be converted in appropriate
symbol in conversion string (in the same position). For
example, if

?      = [1234567890], then
?.c(0) = "!@#$%^&*()"

sets shift-conversion.

In the conversion string it is necessary to shield symbols '\' and '"".
Parameters at convert modifiers can be from 0 up to 255.

2.3.4. Definition of special character sets

To special character sets concern:

$v - the set of vowels (in all alphabets, English and national)
is required only, if the modifiers .s and .j are used.
$p - the set for insert with permutation brackets is
required only if for automatic reception of this set can't be used
(see 2.2.3).

They are described similar to other character sets.


2.4. Useful examples of password descriptions.

1) Let me  give a  fragment from the  documentation of the
ZEXPL2L program:  "I  assume, that  you have  archive with  a
password, similar to " Heaven!!!", but you have forgotten, how
many '!' were at the end  of a word, and which -  lower/upper
case vowels were used".

This  password would  be written  down in  PCL language as:
"He [aA] v [eE] n! * "

We shall assume  in addition, that  you were mistaken in the
basic part of the password. Then it is necessary to
try the following:
  "{He [aA]  v [eE]  n} ! *"

2) Another citation : "Let's assume you have two variants of a line
of the password:  "myprog", "MyProg","my_prog" and  "My_Prog".
It should be written down as:

  "[mM] y [_ \0] [pP] rog".

3) Often passwords consist of two regular words, separated
by some sign. The appropriate description:

 "$w [$1 $!] $w" or
 "$w.u(1) [$1 $!] $w.u(1)"

It is important to note, that both $w are not equal here , and
will generate a total of (if there are 20000 words in the dictionary):
20000 * 42 * 20000 = 1.68E10 passwords.

Accordingly, two simple words will be cracked in 42 times faster.

4) You remember that your password was "MyVeryLongGoodPassword",
but it  does not match for some reason.  Try these
combinations:

  "{MyVeryLongGoodPassword}" - 2382 passwords
  "{MyVeryLongGoodPassword}.2" - 2836413 passwords

5) You know that the password consists of an regular word,
inside which digit is inserted in any position (like "pas2sword").
The description is:

$p = [$1]  # let define non-standard insert set
##
{$w}

7) Attack on syllables. Create the user dictionary of allowable syllables
of your language, and then it is possible to generate all
intelligent-sounding word as follows:

$u      # all one-syllable word
$u$u    # two-syllables
$u$u$u  #etc.
$u$u$u$u
...

8) To distribute the work on 2 computers running in parallel, set them
the following descriptions:

"[abcdefghijklm] $a *" - to first computer
"[nopqrstuvwxyz] $a *" - to second one.

Similarly do for n computers.


3. Interface with the application.

Is rather simple and is described in a file PCL.H. The example
of PCL using is in PROTO.C file.


4. How to contact to the author.

Only by e-mail.

e-mail: psw@ssl.stu.neva.ru?subject=PCL
WWW: http://www.ssl.stu.neva.ru/psw/pcl.html
     http://www.password-crackers.com/pcl.html (mirror)

Some applications which implement PCL (currently are YACC and cRARk)
can be found at:

     http://www.password-crackers.com/crack.html


5. Thanks to.

Solar Designer and Alec Muffett - for ideas of some modifiers.
Eric Young - for timing function  from libdes.
John Vandermeersch for correcting this docs.

