# HG changeset patch
# User Brian Neal <bgneal@gmail.com>
# Date 1342055975 18000
# Node ID aa7a4298d609fbfdc8f101596c171ccf83ffcfb2
# Parent  b04dea5f71a3e050a4b1fe63b26f52bbd4faecc0
Added a LICENSE, README, and an example.

diff -r b04dea5f71a3 -r aa7a4298d609 LICENSE.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/LICENSE.txt	Wed Jul 11 20:19:35 2012 -0500
@@ -0,0 +1,18 @@
+Copyright (c) 2012 by Brian Neal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff -r b04dea5f71a3 -r aa7a4298d609 README.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.rst	Wed Jul 11 20:19:35 2012 -0500
@@ -0,0 +1,172 @@
+==========
+Cpp-Enigma
+==========
+A historically accurate Enigma Machine library written in C++11
+---------------------------------------------------------------
+
+:Author: Brian Neal <bgneal@gmail.com>
+:Version: 0.1
+:Date: July 11, 2012
+:Home Page: https://bitbucket.org/bgneal/cpp-enigma/
+:License: MIT License (see LICENSE.txt)
+:Support: https://bitbucket.org/bgneal/cpp-enigma/issues
+
+
+Overview
+--------
+
+**Cpp-Enigma** is a C++11 library for simulating the `Enigma machines`_ used
+by the German armed forces (Wehrmacht) during World War 2. Cpp-Enigma makes it
+possible to both encrypt and decrypt messages that can be sent to, or received
+from, actual Enigma machines used by the German army (Heer), air force
+(Luftwaffe), and navy (Kriegsmarine).
+
+It is my hope that library will be useful to Enigma enthusiasts, historians, and
+students interested in cryptography.
+
+Cpp-Enigma is basically a C++11 port of my `Py-Enigma
+<https://bitbucket.org/bgneal/enigma>`_ library, which is written in Python 3.
+Cpp-Enigma was created when I started doing performance intensive hill-climbing
+searches for Enigma keys. The Python library is very convenient for quick
+experiments and simple brute force attacks when most of the key parameters are
+known. Cpp-Enigma is for when you need much greater performance, such as a
+cipher-text only attack involving hill-climbing.
+
+
+Quick Example
+-------------
+
+This example shows how the library can be used to decode a message using the
+procedure employed by the German army::
+   
+   #include <iostream>
+   #include <string>
+   #include "machine.h"
+
+   using namespace enigma;
+
+   int main()
+   {
+      // setup machine according to specs from a key sheet:
+
+      enigma_machine em({"II", "IV", "V"}, {1, 20, 11}, "B",
+            "AV BS CG DL FU HZ IN KM OW RX");
+
+      // set initial rotor starting position
+      em.set_display("WXC");
+
+      // decrypt the message key
+      const std::string msg_key = em.process_text("KCH");
+
+      // decrypt the ciphertext with the unencrypted message key
+      em.set_display(msg_key);
+
+      const std::string ciphertext("NIBLFMYMLLUFWCASCSSNVHAZ");
+      const std::string plaintext(em.process_text(ciphertext));
+
+      std::cout << plaintext << std::endl;
+      return 0;
+   }
+
+This program prints::
+
+   THEXRUSSIANSXAREXCOMINGX
+
+
+Requirements
+------------
+
+Cpp-Enigma is written in C++, and uses features found in the C++11 standard. The
+code was developed on GCC 4.6.3.
+
+Cpp-Enigma ships with SCons_ build files. 
+
+Cpp-Enigma's unit tests require the CxxTest_ unit test framework. This is only
+required if you plan on running or modifying the tests.
+
+Cpp-Enigma has no other requirements or dependencies.
+
+
+Installation
+------------
+
+You may download a tarball or .zip file of the latest code using the "get
+source" link on the `Cpp-Enigma Bitbucket page`_. Alternatively if you use
+Mercurial_, you can clone the repository with the following command::
+
+   $ hg clone https://bitbucket.org/bgneal/cpp-enigma
+
+Once you have obtained a copy of the source and installed SCons_ the software
+can be compiled on GCC with::
+
+   $ scons
+
+If you have CxxTest_ installed and configured to work with SCons_, you may run
+the unit tests with::
+
+   $ scons check
+
+I have not currently compiled the code on other compilers or environments.
+Patches or pull requests are welcome.
+
+Documentation
+-------------
+
+Currently there is no documentation for Cpp-Enigma. However the design and API
+is almost identical to Py-Enigma, which is well documented. I will quote from
+the Py-Enigma README file below:
+
+   The latest documentation is available at `Read the Docs
+   <http://readthedocs.org/projects/py-enigma/>`_. There you can `browse the
+   documentation online <http://readthedocs.org/docs/py-enigma/en/latest/>`_, or
+   `download it in a variety of formats
+   <http://readthedocs.org/projects/py-enigma/downloads/>`_.
+
+   Sources for the documentation are also included in Sphinx_ format. If you
+   install Sphinx you can generate the documentation in several output formats.
+
+Support
+-------
+
+Support is provided at the `issue tracker`_ at the `Cpp-Enigma Bitbucket page`_.
+If you have general questions or comments, please feel free to email me (address
+at the top of this file). 
+
+And please, if you use Cpp-Enigma for anything, even if it is just learning,
+please let me know!
+
+
+Acknowledgements & References
+-----------------------------
+
+This software would not have been possible without the thorough and detailed
+descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
+Machines and Cryptology website`_. In particular, his `Technical Details of the
+Enigma Machine`_ page was a gold mine of information.
+
+Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
+look at his source code, I did use his simulator to check the operation of
+Cpp-Enigma.
+
+I would also like to recommend the photos and video at Dr. Thomas B. Perera's
+`Enigma Museum`_.
+
+Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
+
+A nice video which shows the basic components and operation of the Enigma
+Machine is on YouTube: `Nadia Baker & Enigma demo`_.
+
+
+.. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
+.. _Cpp-Enigma Bitbucket page: https://bitbucket.org/bgneal/cpp-enigma
+.. _Mercurial: http://mercurial.selenic.com/
+.. _issue tracker: https://bitbucket.org/bgneal/cpp-enigma/issues
+.. _SCons: http://www.scons.org/
+.. _CxxTest: http://cxxtest.com/
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
+.. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
+.. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
+.. _Enigma Museum: http://w1tp.com/enigma/
+.. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
+.. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc
diff -r b04dea5f71a3 -r aa7a4298d609 enigma/SConscript
--- a/enigma/SConscript	Sat Jul 07 15:03:39 2012 -0500
+++ b/enigma/SConscript	Wed Jul 11 20:19:35 2012 -0500
@@ -11,3 +11,4 @@
 env.StaticLibrary('enigma', sources)
 
 SConscript(['tests/SConscript'], exports='env', variant_dir='build', duplicate=0)
+SConscript(['examples/SConscript'], exports='env', variant_dir='build/examples', duplicate=0)
diff -r b04dea5f71a3 -r aa7a4298d609 enigma/examples/SConscript
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/enigma/examples/SConscript	Wed Jul 11 20:19:35 2012 -0500
@@ -0,0 +1,3 @@
+Import('env')
+
+env.Program('example1', ['example1.cpp'])
diff -r b04dea5f71a3 -r aa7a4298d609 enigma/examples/example1.cpp
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/enigma/examples/example1.cpp	Wed Jul 11 20:19:35 2012 -0500
@@ -0,0 +1,34 @@
+// Copyright (C) 2012 by Brian Neal.
+// This file is part of Cpp-Enigma, the Enigma Machine simulation.
+// Cpp-Enigma is released under the MIT License (see License.txt).
+//
+// example1.cpp - Quick example program showing usage.
+
+#include <iostream>
+#include <string>
+#include "machine.h"
+
+using namespace enigma;
+
+int main()
+{
+   // setup machine according to specs from a key sheet:
+
+   enigma_machine em({"II", "IV", "V"}, {1, 20, 11}, "B",
+         "AV BS CG DL FU HZ IN KM OW RX");
+
+   // set initial rotor starting position
+   em.set_display("WXC");
+
+   // decrypt the message key
+   const std::string msg_key = em.process_text("KCH");
+
+   // decrypt the ciphertext with the unencrypted message key
+   em.set_display(msg_key);
+
+   const std::string ciphertext("NIBLFMYMLLUFWCASCSSNVHAZ");
+   const std::string plaintext(em.process_text(ciphertext));
+
+   std::cout << plaintext << std::endl;
+   return 0;
+}