source: wiki/Overview.wiki @ 85

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

GitHub? doc fixes

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