hc_cry: The Manual
===================

Syntax
-------
./hc_cry [options...] < cryptogram

Options
-------
a) General
-h 
	Displays the options and their meanings.

-D
	Enters DEBUG mode.

-Z x 
	Number of times HC_Outer is executed (Shutgun). By default,
 	HC_Outer is executed only once!

-C seed
    The seed initialiazes the pseudo Random number Generation 
    (allows for the reproducibility of examples).

b) Fitness
-M method 
	The Fitness method used. By default, UNI (unigram or
 	monogram). IC, BIG, TRI, QUA, and ADE (known plaintext attack)
 	can also be used.

-m file 
	The file containing the probabilities associated with the
 	method used. By default, m209.uni for the UNI method. It
 	corresponds to the English name with Z as a space.

-T threshold 
	Displays the key only if the fitness function has a score
 	greater than the threshold. By default, the threshold is very
 	high (on the order of 10**10).

c) Simulated Annealing
-z 
	The temperature is zero. Default is 0.003.

-F 	
	The cooling factor. Default is 0.3.

-i 	
	The number of iterations of the SA_inner() procedure.

d) Specify part of the key and the searches performed.
-P pins 
	Specifies the Pins, most often used to search for LUGS. Pins
 	is a 131-character string composed of a sequence of 0s and 1s.

-L lugs 
	Specifies the Lugs, most often used to search for Pins. Lugs
 	is a sequence of 21 integers separated by colons. If there are
 	no overlaps, only the first 6 values ​​can be specified.

-A list 
	Specifies the transformations applied to a Pin configuration.
 	Default is "TE,SI,SO,IW" (see below).

-B list 
	Specifies the transformations applied to a Lug configuration.
 	Default is "TA" (see below).

-A ST 
	No Pin lookup is performed. The lookup provided by the -P
 	option is used.

-B ST 
	No Lug lookup is performed. The lookup provided by the -L
 	option is used.

-R man 
	Specifies the version of the manual that a Lug configuration
 	must conform to ("1942", ...). By default, there is no restriction.
    The "1" value allows to initialize only Lugs (without overlaps).

The academic representation of LUGs
------------------------------------
The LUGS argument indicates the active lugs for each type of bar:
a) Bars that contain only one active lug. This type of bars 
correspond to the first 6 values.

b) Bars that contain two active lugs (these are the bars that cause 
Overlaps). 

O[7]: Bars having a lug opposite the 1st and 2nd wheel. 
O[8]: … 1st and 3rd wheel 
O[9]: … 1st and 4th wheel 
O[10]: … 1st and 5th wheel 
O[11]: … 1st and 6th wheel 
O[12]: …2nd and 3rd wheel 
O[13]: …2nd and 4th wheel 
O[14]: …2nd and 5th wheel 
O[15]: …2nd and 6th wheel 
O[16]: … 3rd and 4th wheel 
O[17]: … 3rd and 5th wheel 
O[18]: … 3rd and 6th wheel 
O[19]: …4th and 5th wheel 
O[20]: …4th and 6th wheel 
O[21]: …5th and 6th wheel

Example: 3:2:5:0:10:1:0:1:3:0:0:0:0:0:0:0:0:0:1:1
- There are 3 bars with 1 active lug in front of the 1st wheel.
- There are 2 bars with 1 active lug in front of the 2nd wheel.
- There are 5 bars with 1 active lug in front of the 3rd wheel.
- There is no bar that has only one active lug in front of the 4th wheel.
- There are 10 bars with 1 active lug in front of the 5th wheel.
- There is 1 bar with 1 active lug in front of the 6th wheel.
- There is 1 bar with 2 active lugs, one opposite the 1st wheel and the 
other opposite the 3rd wheel.
- There are 3 bars with 2 active lugs, one opposite the 1st wheel 
and the other opposite the 4th wheel.
- There is 1 bar with 2 active lugs, one opposite the 4th wheel and 
the other opposite the 6th wheel.
- There is 1 bar with 2 active lugs, one opposite the 5th wheel and 
the other opposite the 6th wheel.

The transformations
-------------------
a) Transformations of a configuration of Pins. 
	"TE": Toogle Each Pin: one by one, 
	"SI": Swap Pins Inside a Wheel, 
	"SO": Swap Pins Outside a Wheel, 
	"IW": Reverse all the Pins of a Wheel, 
	"IA": Reverse All Pins in a single operation, 
	"ST": Same Thing (see below),

b) Transformations of a Lugs configuration. 
	"TA": Toogle All Lugs (with or without overlap), 
	"TL": Toogle Each Lug without Overlap, 
    "TO": Toogle only the Overlaps,
    "KP": Known Plaintext Attack (the transformation used in HC_KPA)
	"ST": Same Thing (see below),

Note: The ST (Same Thing) special transformation does nothing. 
It returns the configuration passed as a parameter. This 
allows you to skip the search for Pins and/or Lugs.

The SA (Simulated Annealing)
----------------------------
I created the DEBUG option primarily to study the SA_inner() 
procedure and, more specifically, the workings of Simulated 
Annealing (SA). Enabling this option allows you to follow 
each iteration (there are 5 by default). For each iteration, 
you can see the evolution of the score, the plaintext, and 
the SA/ACC ratio. The "ACC" value counts the total number of 
keys accepted during the iteration. The "SA" value counts 
the number of keys accepted solely due to SA. Remember that 
in each iteration, all transformations of the selected Pins 
are tested.

Some Examples
-------------
1 – Display the available options
$ ./hc_cry -h

2 – Search for the key that generated the cryptogram crypto.cry. 
The almost infinite value of the Shutgun parameter (-Z) means 
the search can take forever ;-).
$ ./hc_cry -Z 100000 < MSGS/crypto.cry

Note: in theory, this is the usage that should allow you to find 
the key of a message without prior knowledge (except for the 
language). So far, I haven't had any luck :-(

3 – Same, but we display all keys that produce a score greater 
than 0.6. By default, the program constantly displays the 
highest score (and its associated key).
$ ./hc_cry -Z 100000 -T 0.6 < MSGS/crypto.cry

4 - Search for PINS, given the known LUGS.
$ ./hc_cry -L 8:1:11:2:3:2:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \
    -D -B ST < MSGS/crypto.cry

5 - Search for LUGs, given the known PINS.
Note: In this example, the LUG configuration used does not 
contain any Overlap.
$ ./hc_cry92 -P \ 00101100110000011001001001101100101010100\
00100100110110100110110101100011111000110010110110001110111\
0100001010110011101111011010101 -Z 100 < MSGS/crypto.cry

6 – Search for Pins (with known LUGS). The transformations 
performed at each iteration are specified.

$ ./hc_cry -L 8:1:11:2:3:2:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 -D\
 -B ST -A IA,IW,TE,SI,SO,TE < MSGS/crypto.cry

7 – Use a different Fitness function (for example Bigrams).

$ ./hc_cry95 -M BIG -m m209 -L 2:1:4:3:7:10 -B ST -Z 1000 \
    < MSGS/crypto.cry

Signals
-------
It is possible to send the INT signal to the program 
(for example with Ctrl-C). As a result, a file 
(lugsXXXX.txt, XXXX = PID of the process) is generated 
containing the LUGS configurations already tested. A 
configuration may have been tested multiple times.

Possible program improvements
-----------------------------
a) The hc_score package contains the fitness functions. 
   It is easy to add more. Data files can also be added 
   to the STATS directory. For example, the file 
   m209.uni contains the probabilities of letters in 
   the English language with Z as the word separator. 
   Other files corresponding to other languages be added.

b) Adding transformation methods (Pins or Lugs). It is 
   also possible to add different transformation lists 
   for each iteration of the SA_inner() procedure.

c) Adding methods that validate Lug configurations. My 
   program currently only offers compliance (or non-
   compliance) with the 1942 manual.

d) Do not use a previously studied Lugs configuration. 
   Instead, configurations could be stored in a hash. This 
   hash could be initialized from a file.

e) The functions that initialize the Lugs consume too 
   much time (minutes???). It is possible to precalculate 
   them and read them from a file.
