Mercurial > public > cpp-enigma

annotate README.rst @ 20:3a69c0c2d7dc

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