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