Mercurial > public > cpp-enigma

comparison README.rst @ 18:aa7a4298d609 0.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added a LICENSE, README, and an example.
author Brian Neal <bgneal@gmail.com>
date Wed, 11 Jul 2012 20:19:35 -0500
parents
children 3a69c0c2d7dc
comparison
equal deleted inserted replaced
17:b04dea5f71a3 18:aa7a4298d609
1 ==========
2 Cpp-Enigma
3 ==========
4 A historically accurate Enigma Machine library written in C++11
5 ---------------------------------------------------------------
6
7 :Author: Brian Neal <bgneal@gmail.com>
8 :Version: 0.1
9 :Date: July 11, 2012
10 :Home Page: https://bitbucket.org/bgneal/cpp-enigma/
11 :License: MIT License (see LICENSE.txt)
12 :Support: https://bitbucket.org/bgneal/cpp-enigma/issues
13
14
15 Overview
16 --------
17
18 **Cpp-Enigma** is a C++11 library for simulating the `Enigma machines`_ used
19 by the German armed forces (Wehrmacht) during World War 2. Cpp-Enigma makes it
20 possible to both encrypt and decrypt messages that can be sent to, or received
21 from, actual Enigma machines used by the German army (Heer), air force
22 (Luftwaffe), and navy (Kriegsmarine).
23
24 It is my hope that library will be useful to Enigma enthusiasts, historians, and
25 students interested in cryptography.
26
27 Cpp-Enigma is basically a C++11 port of my `Py-Enigma
28 <https://bitbucket.org/bgneal/enigma>`_ library, which is written in Python 3.
29 Cpp-Enigma was created when I started doing performance intensive hill-climbing
30 searches for Enigma keys. The Python library is very convenient for quick
31 experiments and simple brute force attacks when most of the key parameters are
32 known. Cpp-Enigma is for when you need much greater performance, such as a
33 cipher-text only attack involving hill-climbing.
34
35
36 Quick Example
37 -------------
38
39 This example shows how the library can be used to decode a message using the
40 procedure employed by the German army::
41
42 #include <iostream>
43 #include <string>
44 #include "machine.h"
45
46 using namespace enigma;
47
48 int main()
49 {
50 // setup machine according to specs from a key sheet:
51
52 enigma_machine em({"II", "IV", "V"}, {1, 20, 11}, "B",
53 "AV BS CG DL FU HZ IN KM OW RX");
54
55 // set initial rotor starting position
56 em.set_display("WXC");
57
58 // decrypt the message key
59 const std::string msg_key = em.process_text("KCH");
60
61 // decrypt the ciphertext with the unencrypted message key
62 em.set_display(msg_key);
63
64 const std::string ciphertext("NIBLFMYMLLUFWCASCSSNVHAZ");
65 const std::string plaintext(em.process_text(ciphertext));
66
67 std::cout << plaintext << std::endl;
68 return 0;
69 }
70
71 This program prints::
72
73 THEXRUSSIANSXAREXCOMINGX
74
75
76 Requirements
77 ------------
78
79 Cpp-Enigma is written in C++, and uses features found in the C++11 standard. The
80 code was developed on GCC 4.6.3.
81
82 Cpp-Enigma ships with SCons_ build files.
83
84 Cpp-Enigma's unit tests require the CxxTest_ unit test framework. This is only
85 required if you plan on running or modifying the tests.
86
87 Cpp-Enigma has no other requirements or dependencies.
88
89
90 Installation
91 ------------
92
93 You may download a tarball or .zip file of the latest code using the "get
94 source" link on the `Cpp-Enigma Bitbucket page`_. Alternatively if you use
95 Mercurial_, you can clone the repository with the following command::
96
97 $ hg clone https://bitbucket.org/bgneal/cpp-enigma
98
99 Once you have obtained a copy of the source and installed SCons_ the software
100 can be compiled on GCC with::
101
102 $ scons
103
104 If you have CxxTest_ installed and configured to work with SCons_, you may run
105 the unit tests with::
106
107 $ scons check
108
109 I have not currently compiled the code on other compilers or environments.
110 Patches or pull requests are welcome.
111
112 Documentation
113 -------------
114
115 Currently there is no documentation for Cpp-Enigma. However the design and API
116 is almost identical to Py-Enigma, which is well documented. I will quote from
117 the Py-Enigma README file below:
118
119 The latest documentation is available at `Read the Docs
120 <http://readthedocs.org/projects/py-enigma/>`_. There you can `browse the
121 documentation online <http://readthedocs.org/docs/py-enigma/en/latest/>`_, or
122 `download it in a variety of formats
123 <http://readthedocs.org/projects/py-enigma/downloads/>`_.
124
125 Sources for the documentation are also included in Sphinx_ format. If you
126 install Sphinx you can generate the documentation in several output formats.
127
128 Support
129 -------
130
131 Support is provided at the `issue tracker`_ at the `Cpp-Enigma Bitbucket page`_.
132 If you have general questions or comments, please feel free to email me (address
133 at the top of this file).
134
135 And please, if you use Cpp-Enigma for anything, even if it is just learning,
136 please let me know!
137
138
139 Acknowledgements & References
140 -----------------------------
141
142 This software would not have been possible without the thorough and detailed
143 descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
144 Machines and Cryptology website`_. In particular, his `Technical Details of the
145 Enigma Machine`_ page was a gold mine of information.
146
147 Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
148 look at his source code, I did use his simulator to check the operation of
149 Cpp-Enigma.
150
151 I would also like to recommend the photos and video at Dr. Thomas B. Perera's
152 `Enigma Museum`_.
153
154 Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
155
156 A nice video which shows the basic components and operation of the Enigma
157 Machine is on YouTube: `Nadia Baker & Enigma demo`_.
158
159
160 .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
161 .. _Cpp-Enigma Bitbucket page: https://bitbucket.org/bgneal/cpp-enigma
162 .. _Mercurial: http://mercurial.selenic.com/
163 .. _issue tracker: https://bitbucket.org/bgneal/cpp-enigma/issues
164 .. _SCons: http://www.scons.org/
165 .. _CxxTest: http://cxxtest.com/
166 .. _Sphinx: http://sphinx.pocoo.org/
167 .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
168 .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
169 .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
170 .. _Enigma Museum: http://w1tp.com/enigma/
171 .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
172 .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc