source: wiki/Overview.wiki @ 83

Last change on this file since 83 was 83, checked in by tim, 9 years ago

initial doc changes for transition to GitHub?

File size: 5.3 KB
Line 
1Here you will find a brief overview of the tools and libraries provided by Bletchley.  For further details, see the individual tool usage statements, pydoc documentation, and of course the <a href="https://github.com/ecbftw/bletchley">source code</a>.
2
3*Contents*
4<wiki:toc max_depth="2" />
5
6= Installation =
7See: <a href="https://github.com/ecbftw/bletchley/blob/master/trunk/INSTALL">INSTALL</a>
8
9= Command Line Tools =
10
11== bletchley-analyze ==
12
13Analyzes samples of encrypted data in an attempt to decode samples to
14binary and identify patterns useful in cryptanalysis.  The purpose of
15the tool is to provide an cryptanalyst with a variety of information
16that is useful in determining how a token is encoded, encrypted and
17formatted.
18<br />
19bletchley-analyze currently performs two primary functions: iterative
20encoding detection and ciphertext-only block analysis.  Encrypted tokens
21are processed in multiple rounds. Within each round, the following
22occurs:
23<ul>
24 <li>Token length analysis is performed to attempt to determine possible
25 ciphertext block sizes, where applicable</li>
26 <li>The tokens are analyzed for blocks of data that are repeated
27 throughout any of the tokens</li>
28 <li>A hexadecimal dump and escaped binary/ascii string is printed for
29 each token with repeated blocks highlighted</li>
30 <li>The full set of all known and possible data encodings is
31 determined<sup>1</sup></li>
32 <li>An educated guess is made as to the most likely encoding is</li>
33 <li>All tokens are decoded using the most likely encoding, and then the
34 process is repeated until no further encodings are detected</li>
35</ul>
36
37`bletchley-analyze` can read from stdin or from a file.  Tokens are
38delimited with newlines.  Various options are provided to give the
39analyst control over the block sizes and encoding used during analysis.
40See the tool's usage statement for more information.
41
42As an example, several tokens were encrypted using ECB mode and encoded
43using base64, and then percent (URL) encoded:
44{{{
45zRW5bHxcRYHHqi0nriqOzg%3D%3D
46meU8SyxVHE3Hqi0nriqOzg%3D%3D
47vTA9eA4hhbFlktsbYI4hIg%3D%3D
48meU8SyxVHE1lktsbYI4hIg%3D%3D
49}}}
50
51These tokens were then fed to `bletchley-analyze`:
52<img src="https://raw.githubusercontent.com/ecbftw/bletchley/master/wiki/images/bletchley-analyze.png" />
53
541. <i>Bletchley's blobtools module currently supports 36 encoding variants,
55including various forms of hexadecimal, base32, base64, and percent
56encodings. Try '`-e ?`' to list them.</i>
57
58
59== bletchley-encode ==
60A simple tool to encode arbitrary data using a specified encoding chain.
61See the usage statement for more information.  A quick example:
62{{{
63$ echo 'Mallory Is My Friend.' | bletchley-encode -e percent/upper-plus,base64/rfc3548
64TWFsbG9yeSBJcyBNeSBGcmllbmQuCg%3D%3D
65}}}
66
67NOTE: The encoding chain is applied from right to left in order to be consistent with other tools. 
68That is, one can use the same encoding chain ordering for
69`bletchley-encode`, `bletchley-decode`, and `bletchley-analyze`.
70
71
72== bletchley-decode ==
73A simple tool to decode data using a specified encoding chain.  See the
74usage statement for more information.  A quick example:
75{{{
76$ echo 'TWFsbG9yeSBJcyBNeSBGcmllbmQuCg%3D%3D' | bletchley-decode -e percent/upper-plus,base64/rfc3548
77Mallory Is My Friend.
78}}}
79
80== bletchley-http2py ==
81This script parses an HTTP request (provided via stdin or as a text
82file) and generates a Python script that sends (approximately) the same
83request.  This is useful when one wants to repeatedly send variations of
84a request that was observed to be sent by an application or web
85browser.  For more information, see the script's usage statement.
86
87== bletchley-nextrand ==
88A simple program which computes the state of a Java Random class
89instance given two sequential outputs of
90<a href="http://docs.oracle.com/javase/6/docs/api/java/util/Random.html#nextInt()">`nextInt()`</a>.
91For more information, see the usage statement.
92
93
94= Libraries =
95
96Start with '`pydoc3 bletchley`'.  The following provides a brief overview of what each module is for.
97
98
99== blobtools ==
100This module contains the code which handles base analysis of encrypted
101token encodings.  It can be used to automatically detect the most likely
102encoding variant ("dialect") as well as to quickly encode or decode data
103which is wrapped in multiple levels of encodings.
104
105
106== buffertools ==
107This module contains a collection of tools mean to help one manipulate
108binary buffers of ciphertext.
109
110
111== CBC ==
112The CBC module contains various tools for attacking CBC encrypted data.
113In particular, it contains the POA class which automates padding oracle
114attacks.  To use the POA class, one simply needs to implement a function
115in Python 3 which submits a request to an oracle and returns True if the
116padding check was successful and False otherwise.  See
117'`pydoc3 bletchley.CBC.POA`' for more details.
118
119
120= Support =
121
122Having trouble?  Submit an issue <a href="https://github.com/ecbftw/bletchley/issues">here</a>, or
123ask on the <a href="https://groups.google.com/d/forum/bletchley-devel">email list</a>.
124
125
126= Contributing =
127
128We welcome any kind of help with the project, from new tools to bug
129fixes and documentation.  You might want to start with our
130<a href="https://github.com/ecbftw/bletchley/blob/master/trunk/doc/TODO">TODO</a>
131list. To submit a patch, just check out a copy of our Subversion
132repository, make your changes, and submit the output of `svn diff` to one of the project leaders.
Note: See TracBrowser for help on using the repository browser.