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