bgneal@18: ==========
bgneal@18: Cpp-Enigma
bgneal@18: ==========
bgneal@18: A historically accurate Enigma Machine library written in C++11
bgneal@18: ---------------------------------------------------------------
bgneal@18: 
bgneal@18: :Author: Brian Neal <bgneal@gmail.com>
bgneal@18: :Version: 0.1
bgneal@18: :Date: July 11, 2012
bgneal@18: :Home Page: https://bitbucket.org/bgneal/cpp-enigma/
bgneal@18: :License: MIT License (see LICENSE.txt)
bgneal@18: :Support: https://bitbucket.org/bgneal/cpp-enigma/issues
bgneal@18: 
bgneal@18: 
bgneal@18: Overview
bgneal@18: --------
bgneal@18: 
bgneal@18: **Cpp-Enigma** is a C++11 library for simulating the `Enigma machines`_ used
bgneal@18: by the German armed forces (Wehrmacht) during World War 2. Cpp-Enigma makes it
bgneal@18: possible to both encrypt and decrypt messages that can be sent to, or received
bgneal@18: from, actual Enigma machines used by the German army (Heer), air force
bgneal@18: (Luftwaffe), and navy (Kriegsmarine).
bgneal@18: 
bgneal@18: It is my hope that library will be useful to Enigma enthusiasts, historians, and
bgneal@18: students interested in cryptography.
bgneal@18: 
bgneal@18: Cpp-Enigma is basically a C++11 port of my `Py-Enigma
bgneal@18: <https://bitbucket.org/bgneal/enigma>`_ library, which is written in Python 3.
bgneal@18: Cpp-Enigma was created when I started doing performance intensive hill-climbing
bgneal@18: searches for Enigma keys. The Python library is very convenient for quick
bgneal@18: experiments and simple brute force attacks when most of the key parameters are
bgneal@18: known. Cpp-Enigma is for when you need much greater performance, such as a
bgneal@18: cipher-text only attack involving hill-climbing.
bgneal@18: 
bgneal@18: 
bgneal@18: Quick Example
bgneal@18: -------------
bgneal@18: 
bgneal@18: This example shows how the library can be used to decode a message using the
bgneal@18: procedure employed by the German army::
bgneal@18:    
bgneal@18:    #include <iostream>
bgneal@18:    #include <string>
bgneal@18:    #include "machine.h"
bgneal@18: 
bgneal@18:    using namespace enigma;
bgneal@18: 
bgneal@18:    int main()
bgneal@18:    {
bgneal@18:       // setup machine according to specs from a key sheet:
bgneal@18: 
bgneal@18:       enigma_machine em({"II", "IV", "V"}, {1, 20, 11}, "B",
bgneal@18:             "AV BS CG DL FU HZ IN KM OW RX");
bgneal@18: 
bgneal@18:       // set initial rotor starting position
bgneal@18:       em.set_display("WXC");
bgneal@18: 
bgneal@18:       // decrypt the message key
bgneal@18:       const std::string msg_key = em.process_text("KCH");
bgneal@18: 
bgneal@18:       // decrypt the ciphertext with the unencrypted message key
bgneal@18:       em.set_display(msg_key);
bgneal@18: 
bgneal@18:       const std::string ciphertext("NIBLFMYMLLUFWCASCSSNVHAZ");
bgneal@18:       const std::string plaintext(em.process_text(ciphertext));
bgneal@18: 
bgneal@18:       std::cout << plaintext << std::endl;
bgneal@18:       return 0;
bgneal@18:    }
bgneal@18: 
bgneal@18: This program prints::
bgneal@18: 
bgneal@18:    THEXRUSSIANSXAREXCOMINGX
bgneal@18: 
bgneal@18: 
bgneal@18: Requirements
bgneal@18: ------------
bgneal@18: 
bgneal@18: Cpp-Enigma is written in C++, and uses features found in the C++11 standard. The
bgneal@18: code was developed on GCC 4.6.3.
bgneal@18: 
bgneal@18: Cpp-Enigma ships with SCons_ build files. 
bgneal@18: 
bgneal@18: Cpp-Enigma's unit tests require the CxxTest_ unit test framework. This is only
bgneal@18: required if you plan on running or modifying the tests.
bgneal@18: 
bgneal@18: Cpp-Enigma has no other requirements or dependencies.
bgneal@18: 
bgneal@18: 
bgneal@18: Installation
bgneal@18: ------------
bgneal@18: 
bgneal@18: You may download a tarball or .zip file of the latest code using the "get
bgneal@18: source" link on the `Cpp-Enigma Bitbucket page`_. Alternatively if you use
bgneal@18: Mercurial_, you can clone the repository with the following command::
bgneal@18: 
bgneal@18:    $ hg clone https://bitbucket.org/bgneal/cpp-enigma
bgneal@18: 
bgneal@18: Once you have obtained a copy of the source and installed SCons_ the software
bgneal@18: can be compiled on GCC with::
bgneal@18: 
bgneal@18:    $ scons
bgneal@18: 
bgneal@18: If you have CxxTest_ installed and configured to work with SCons_, you may run
bgneal@18: the unit tests with::
bgneal@18: 
bgneal@18:    $ scons check
bgneal@18: 
bgneal@18: I have not currently compiled the code on other compilers or environments.
bgneal@18: Patches or pull requests are welcome.
bgneal@18: 
bgneal@21: 
bgneal@18: Documentation
bgneal@18: -------------
bgneal@18: 
bgneal@18: Currently there is no documentation for Cpp-Enigma. However the design and API
bgneal@18: is almost identical to Py-Enigma, which is well documented. I will quote from
bgneal@18: the Py-Enigma README file below:
bgneal@18: 
bgneal@18:    The latest documentation is available at `Read the Docs
bgneal@18:    <http://readthedocs.org/projects/py-enigma/>`_. There you can `browse the
bgneal@18:    documentation online <http://readthedocs.org/docs/py-enigma/en/latest/>`_, or
bgneal@18:    `download it in a variety of formats
bgneal@18:    <http://readthedocs.org/projects/py-enigma/downloads/>`_.
bgneal@18: 
bgneal@18:    Sources for the documentation are also included in Sphinx_ format. If you
bgneal@18:    install Sphinx you can generate the documentation in several output formats.
bgneal@18: 
bgneal@21: Between the Python docs and the source code hopefully this will be enough to get
bgneal@21: you going. Proper documentation may be created in the future. Again, patches and
bgneal@21: pull requests are welcome.
bgneal@21: 
bgneal@20: 
bgneal@18: Support
bgneal@18: -------
bgneal@18: 
bgneal@18: Support is provided at the `issue tracker`_ at the `Cpp-Enigma Bitbucket page`_.
bgneal@18: If you have general questions or comments, please feel free to email me (address
bgneal@18: at the top of this file). 
bgneal@18: 
bgneal@18: And please, if you use Cpp-Enigma for anything, even if it is just learning,
bgneal@18: please let me know!
bgneal@18: 
bgneal@18: 
bgneal@18: Acknowledgements & References
bgneal@18: -----------------------------
bgneal@18: 
bgneal@18: This software would not have been possible without the thorough and detailed
bgneal@18: descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
bgneal@18: Machines and Cryptology website`_. In particular, his `Technical Details of the
bgneal@18: Enigma Machine`_ page was a gold mine of information.
bgneal@18: 
bgneal@18: Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
bgneal@18: look at his source code, I did use his simulator to check the operation of
bgneal@18: Cpp-Enigma.
bgneal@18: 
bgneal@18: I would also like to recommend the photos and video at Dr. Thomas B. Perera's
bgneal@18: `Enigma Museum`_.
bgneal@18: 
bgneal@18: Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
bgneal@18: 
bgneal@18: A nice video which shows the basic components and operation of the Enigma
bgneal@18: Machine is on YouTube: `Nadia Baker & Enigma demo`_.
bgneal@18: 
bgneal@18: 
bgneal@18: .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
bgneal@18: .. _Cpp-Enigma Bitbucket page: https://bitbucket.org/bgneal/cpp-enigma
bgneal@18: .. _Mercurial: http://mercurial.selenic.com/
bgneal@18: .. _issue tracker: https://bitbucket.org/bgneal/cpp-enigma/issues
bgneal@18: .. _SCons: http://www.scons.org/
bgneal@18: .. _CxxTest: http://cxxtest.com/
bgneal@18: .. _Sphinx: http://sphinx.pocoo.org/
bgneal@18: .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
bgneal@18: .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
bgneal@18: .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
bgneal@18: .. _Enigma Museum: http://w1tp.com/enigma/
bgneal@18: .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
bgneal@18: .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc