-------------------------------------------------------------------------
                                 WARNING

These implimentations of crypto functions are NOT SECURE and SHOULD NOT
be used in any serious implimentations of anything whatsoever. This code
has been written solely as a learning experience for the writer. One day
far in the future it might come closer to being secure, but that day is
not today. As it stands, there are more vulnerabilities than I can count
or even understand.

Seriously, don't use this.

-------------------------------------------------------------------------

                               DESCRIPTION

This is RSAES, a C++ interface for encryption over RSA and AES-N.

In its current state, this project IS NOT SECURE and should not
be used in production. It is a learning experience on the author's
part, and only might be secure in the distant future.

The intent is for applications which need very simple encryption
in a very small footprint. This library is meant to be portable
above all else, with two options of use: using a pre-compiled
version of GMP linked through lgmp, or through a version of
mini-gmp when <gmp.h> is not available, which is contained herein.

AES-N is a fork of the AES algorithm which has been designed to work with
any key size that is a power of two above 128. For values of 128, 256,
and 512, the algorithm is the same as the reference AES algorithm.
Larger key sizes follow the most obvious pattern in the algorithm, and
are implimented accordingly. I've personally tested key sizes up to 
about 1 Gigabyte with success.

-------------------------------------------------------------------------

                          MAKEFILE INSTRUCTIONS

To begin using RSAES, one must first run `make init` in the RSAES
directory. This will construct RSAES.hpp from RSAES.hpp.proto, which can
be included in desired applications. `make init` has a few options,
which are described as follows:

make init
     Assumes the behavior of make init lib=yes

make init lib=yes
     Assumes GMP is installed on the target system. RSAES.hpp will
     include <gmp.h> and should compiled with the -lgmp flag. If
     GMP is not installed on the target system, use the next option

make init lib=no
     Assumes GMP is not installed on the target system. Instead of
     linking to libgmp, RSAES.hpp will include "mini-gmp/mini-gmp.c"
     and will include the functions and struct definitions needed for
     RSAES to work properly. The advantage here is more portability
     at the cost of performance, as mini-gmp uses a pure C
     implimentation of GMP. This is slower as it does not have assemby
     optimizations, but should be fully cross-platform.

In both cases, simply `#include "RSAES.hpp"` in your project, with
proper directory structure, and everything should work smoothly.

Furthermore, the makefile has a few more abilities, all accessable only
after a `make init`. They are as follows:

make test
     Compiles tests_and_examples.cpp using RSAES.hpp and runs a test
     suite. `make test` assumes g++ to comple, however a specific
     compiler can be used through specifying the CXX flag. As follows is
     an example:
     	make test CXX=clang++
     This would compile tests_and_examples.cpp with clang and run a.out.
     Additionally, CXXFLAGS is recognized and can be passed to the
     makefile in order to specify optimizations or special circumstances.
     Example is as follows:
     	make test CXXFLAGS="-O2 -Wall -Werror"

make debug
     Same as make test, but runs the resulting executable under valgrind
     to check for errors.

make time
     Same as make test, but runs the resulting executable with the
     `time` command

make clean
     Remove all generated files, likely editor files, and executables
     generated by other make options. Should leave the entire repository
     the same as it was when first cloned

-------------------------------------------------------------------------

                           TOP LEVEL INTERFACE

The top level interface is held in the `RSAES` namespace in the class
`EncryptionManager`.


----------EncryptionManager CONSTRUCTORS

EncryptionManager(unsigned int RSAbits)
    Creates an empty EncryptionManager and initilizes public and private
    RSA keys (the size of which is passed as RSAbits). This should be the
    first constructor used when starting 2-way communicatoin.

    At this point, the getPublicKey() method is now available.

EncryptionManager(std::string key, size_t AESbits)
    Creates an EncryptionManager using an RSA public key. This public key
    should come from the getPublicKey() method from the first
    constructor. AESbits is the size of bits in AES-N. See description for
    clarification on AES-N.

    At this point, the getKeyResponse() method is now available.

EncryptionManager(std::string key)
    Creates an EncryptionManager with only an RSA public key. Identical
    in purpose to the above constructor, but chooses the largest
    AES-N keysize that can fit within the RSA key. Gives less control,
    but ensures the most secure possible algorithm given the size of
    the RSA key.
    
    At this point, the getKeyResponse() method is now available.

EncryptionManager()
    Creates an empty EncryptionManager for the express reason of
    unpacking a string into it. See the pack() and unpack() methods

~EncryptionManager()
    The deconstructor is available at any time and should be mentioned
    here. When deconstructed, this object overwrites all its members
    with random bits before freeing them, just in case a malacoius
    program would get a hold of the malloc'd memory. Additionally,
    memory management has been taken care of so that even if an
    EncryptionManager goes out of scope before being fully initilized,
    memory management is still safe and secure.

----------EncryptionManager METHODS

std::string getPublicKey()
    Available immediatly after using the first constructor. This method
    returns the RSA public key, as packed in base64. Once transfered,
    the result should be passed to the second constructor.

std::string getKeyResponse()
    Available immediatly after using the second constructor. This method
    returns the internal AES-N key, encrypted with the RSA key, and packed
    in base64. Once transfered, the result should be passed to the
    following method on the first object.

    At this point, the encrypt() and decrypt() methods are available.

void registerPass(std::string KeyResponse)
    Available immediatly after calling getPublicKey() on an object
    instantiated by the first constructor. This method decrypts and stores
    the shared AES-N key.

    At this point, the encrypt() and decrypt() methods are available.


std::string encrypt(std::string input)
    Available immediatly after calling getKeyResponse() or registerPass()
    on an object. This method takes a string of any length and returns the
    string as encrypted by AES-N, using the internal AES-N key, and packed
    as base64.

std::string decrypt(std::string input)
    Available immediatly after calling getKeyResponse() or registerPass()
    on an object. This method takes a string returned from the encrypt()
    method and returns the decrypted string using the internal AES-N key.

std::string pack()
    Return a base64 encoded string containing a small snippet of the AES
    key. This string can be saved to disk for future sessions when RAM
    is cleared

void unpack(std::string input)
    Takes a string previously returned from pack(), used to initilize
    an EncryptionManager constructed from the default EncryptionManager()
    constructor. After running unpack, both encrypt and decrypt are
    available.

void destroy()
    Free all allocated memory associated with the object. Very similar
    to the deconstructor, but doesn't re-seed the random objects.

-------------------------------------------------------------------------

                          LOW LEVEL INTERFACES

The low level interfaces are held in the RSAES namespace, under one of
the following sub-namespaces: RSA, AES, or UTIL. The low level interface
is not meant to be used directly and thus is not as clean as the top
level interface. However, in the usecases of debugging or highly-
optimized implimentations where the top level interface offers more than
needed, use of the low level interfaces are encouraged.

----------UTIL

The UTILity namespace houses the general utility functions and objects
used all over in the library. They are as follows:

-->OBJECTS
Global objects are as such so that they only needs to be initilized once,
saving on memory usage and improving speed.

std::random_device rd;
       An std::random_device used for better randomization than rand().
std::mt19937 mt(rd());
       The Mersenne Twister algorithm, as initilized by our random device.
       Used for extracting random numbers from the distribution objects.
std::uniform_int_distribution<unsigned short> dist_char(0, 255);
       Used for creating padding at the end of messages.
std::uniform_int_distribution<unsigned short> dist_char_1(1, 255);
       Used for creating an AES key. This is different because bugs.
std::uniform_int_distribution<unsigned long long int>
       dist_short(0, std::numeric_limits<unsigned short>::max());
       Used for clearing vectors, as it's much faster to use shorts when
       possible.
std::uniform_int_distribution<unsigned long>
       dist_r(0, std::numeric_limits<unsigned long>::max());
       Used for generic randomness and seeding the GMP random structs.
const char base64_chars[64];
       Used as a lookup table for base64 en/decoding.

-->FUNCTIONS

inline char find_as_base64(char tofind)
       Used to reverse the lookup base64_chars lookup table during decodng.

std::string base64_encode(unsigned char const* bytes_to_encode,
       		   	         size_t in_len)
       Used to base64 encode some bytes. It doesn't take a string because
       that's how I found it on the internet.

std::string base64_decode(std::string const& encoded_string)
       Used to decode a base64 string. The return value is a string whos
       bytes are not all valid ascii.


----------RSA

The RSA namespace houses everything needed to run and manage the RSA side
of RSAES. It contains various functions and a single class (RSAmanager).

-->FUNCTIONS

std::string packKey(std::pair<mpz_t,mpz_t> key)
       Packs the public `key` and returns valid ascii.

void unpackKey(std::pair<mpz_t,mpz_t> **rop, std::string key)
       Unpacks the public `key` into `rop`.

std::string encrypt(std::string input, std::pair<mpz_t,mpz_t> *key)
       The full RSA encryption algorithm. Encrypts `input` using the public
       `key`.

-->RSAmanager

The RSAmanager is a mid-level interface for dealing with RSA encryption.

>Members
std::pair<mpz_t,mpz_t> public_key;
	Public member which stores the public key.

mpz_t private_key;
        Private member which stores the private key.

gmp_randstate_t r;
        The source of randomness for the object.

>Constructor

RSAmanager(unsigned int bits)
        Takes bits as an argument. Typically 1024, 2048, 4096, or higher.
	Creates the public and private key.

>Destructor

~RSAmanager()
        Fills all used ram with random bits before clearing memory, just
	in case.

>Methods

inline std::string decrypt(std::string msg)
        Full RSA decryption algorithm. Decrypts `msg` using the private key.

All private methods are simply used to help decrypt and instantiate.


----------AES

The AES namespace houses everything needed to run and manage the AES side
of RSAES. Although it is a part of RSAES, it can stand alone as just an
AES implimentation. It contains many functions, varibles and a single
class (AESkey). Only the important ones are shown.

-->FUNCTIONS

std::vector<unsigned char> expand_key(std::vector<unsigned char> in)
       Takes an N-bit key, where N is restricted to 128, 256, or any power
       of two thereafter. Returns an expanded key. This is the KeyExpansion
       step in the reference AES algorithm.

unsigned char small_encrypt(unsigned char *in, AESkey &expanded_key)
       Fully encrypts a 4x4 bytetable. This is the entire reference AES
       algorithm.

unsigned char small_decrypt(unsigned char *in, AESkey &expanded_key)
       Fully decrypts a 4x4 bytetable. This is the reference AES decryption
       algorithm.

std::string big_encrypt(std::string input, AESkey &expanded_key)
       Takes a whole string, padds it, encrypts each table, then wraps
       it up in base64 and returns a passable, encrypted string.

std::string big_decrypt(std::string input, AESkey &expanded_key)
       Takes a whole string, decodes it from base64, decrypts it,
       un-padds it and returns the clean string.

-->AESkey

The AES key class is simply a wrapper for an expanded key with methods to
step over the key and produce round keys.

>Members
size_t base;
        The base size of the key in bytes. If you're using AES-256, this
	value would be 32.
std::vector<unsigned char> expanded_key;
        Holds the value of the expanded key.

>Constructors

AESkey(std::vector<unsigned char> in)
        Creates an expanded key from a given unexpanded key (in the case)
	of a hashed password.

AESkey(size_t _base)
	Creates an expanded key at random, given only by the size of key
	desired.

>Destructor

~AESkey()
	Randomizes all ram before releasing just in case.

>Methods

std::array<unsigned char, 16> getRoundKey(bool B = false)
        Gets the next round key and automatically advances forward
	or backwards.

inline void advanceRound()
        Readys the next round key.

inline void setStart()
        Gets the key ready for front-to-back navigation (encryption).

inline void setEnd()
        Gets the key ready for back-to-fromt navigation (decryption).

inline std::string pack()
        Returns a base64 encoded, shortened version of the internal key
	used for saving to disk.