source: wiki/Overview.wiki @ 107

<p>
Here 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://code.blindspotsecurity.com/trac/bletchley/browser">source code</a>.
</p>

<h1>Installation</h1>
<p>
See: <a href="/trac/bletchley/browser/trunk/doc/INSTALL">INSTALL</a>
</p>

<h1>Command Line Tools</h1>

<h2> bletchley-analyze </h2>
<p>
Analyzes samples of encrypted data in an attempt to decode samples to
binary and identify patterns useful in cryptanalysis.  The purpose of
the tool is to provide an cryptanalyst with a variety of information
that is useful in determining how a token is encoded, encrypted and
formatted.
</p>
<p>
bletchley-analyze currently performs two primary functions: iterative
encoding detection and ciphertext-only block analysis.  Encrypted tokens
are processed in multiple rounds. Within each round, the following
occurs:
</p>
<p>
<ul>
 <li>Token length analysis is performed to attempt to determine possible
 ciphertext block sizes, where applicable</li>
 <li>The tokens are analyzed for blocks of data that are repeated
 throughout any of the tokens</li>
 <li>A hexadecimal dump and escaped binary/ascii string is printed for
 each token with repeated blocks highlighted</li>
 <li>The full set of all known and possible data encodings is
 determined<sup>1</sup></li>
 <li>An educated guess is made as to the most likely encoding is</li>
 <li>All tokens are decoded using the most likely encoding, and then the
 process is repeated until no further encodings are detected</li>
</ul>
</p>
<p>
<code>bletchley-analyze</code> can read from stdin or from a file.  Tokens are
delimited with newlines.  Various options are provided to give the
analyst control over the block sizes and encoding used during analysis.
See the tool's usage statement for more information.
</p>
<p>
As an example, several tokens were encrypted using ECB mode and encoded
using base64, and then percent (URL) encoded:
</p>
<pre>
zRW5bHxcRYHHqi0nriqOzg%3D%3D
meU8SyxVHE3Hqi0nriqOzg%3D%3D
vTA9eA4hhbFlktsbYI4hIg%3D%3D
meU8SyxVHE1lktsbYI4hIg%3D%3D
</pre>
<p>
These tokens were then fed to <code>bletchley-analyze</code>:
</p>
<p><img src="https://code.blindspotsecurity.com/trac/bletchley/export/head/wiki/images/bletchley-analyze.png" /></p>
<p>
1. <i>Bletchley's blobtools module currently supports 36 encoding variants,
including various forms of hexadecimal, base32, base64, and percent
encodings. Try '<code>-e ?</code>' to list them.</i>
</p>

<h2> bletchley-encode </h2>
<p>
A simple tool to encode arbitrary data using a specified encoding chain.
See the usage statement for more information.  A quick example:
</p>
<p>
<pre>
$ echo 'Mallory Is My Friend.' | bletchley-encode -e percent/upper-plus,base64/rfc3548
TWFsbG9yeSBJcyBNeSBGcmllbmQuCg%3D%3D
</pre>
</p>
<p>
NOTE: The encoding chain is applied from right to left in order to be consistent with other tools.  
That is, one can use the same encoding chain ordering for 
<code>bletchley-encode</code>, <code>bletchley-decode</code>, and <code>bletchley-analyze</code>.
</p>

<h2> bletchley-decode </h2>
<p>
A simple tool to decode data using a specified encoding chain.  See the
usage statement for more information.  A quick example:
</p>
<p>
<pre>
$ echo 'TWFsbG9yeSBJcyBNeSBGcmllbmQuCg%3D%3D' | bletchley-decode -e percent/upper-plus,base64/rfc3548
Mallory Is My Friend.
</pre>
</p>

<h2> bletchley-http2py </h2>
<p>
This script parses an HTTP request (provided via stdin or as a text
file) and generates a Python script that sends (approximately) the same
request.  This is useful when one wants to repeatedly send variations of
a request that was observed to be sent by an application or web
browser.  For more information, see the script's usage statement.
</p>

<h2> bletchley-nextrand </h2>
<p>A simple program which computes the state of a Java Random class
instance given two sequential outputs of 
<a href="http://docs.oracle.com/javase/6/docs/api/java/util/Random.html#nextInt()"><code>nextInt()</code></a>.
For more information, see the usage statement.
</p>

<h1>Libraries</h1>
<p>
Start with '<code>pydoc3 bletchley</code>'.  The following provides a brief overview of what each module is for.
</p>

<h2> blobtools </h2>

<p>This module contains the code which handles base analysis of encrypted
token encodings.  It can be used to automatically detect the most likely
encoding variant ("dialect") as well as to quickly encode or decode data
which is wrapped in multiple levels of encodings.
</p>

<h2> buffertools </h2>
<p>
This module contains a collection of tools mean to help one manipulate
binary buffers of ciphertext.
</p>

<h2> CBC </h2>
<p>
The CBC module contains various tools for attacking CBC encrypted data.
In particular, it contains the POA class which automates padding oracle
attacks.  To use the POA class, one simply needs to implement a function
in Python 3 which submits a request to an oracle and returns True if the
padding check was successful and False otherwise.  See 
'<code>pydoc3 bletchley.CBC.POA</code>' for more details.
</p>

<h1>Support</h1>
<p>
Having trouble?  Submit an issue <a href="/trac/bletchley/newticket">here</a>, or 
ask on the <a href="https://groups.google.com/d/forum/bletchley-devel">email list</a>.
</p>

<h1>Contributing</h1>
<p>
We welcome any kind of help with the project, from new tools to bug
fixes and documentation.  You might want to start with our <a href="/trac/bletchley/browser/trunk/doc/TODO">TODO</a>
list.  To submit a patch, please post an issue or submit it to the <a href="https://groups.google.com/d/forum/bletchley-devel">email list</a> and we'll merge it.
</p>