wave-crypto.h

Go to the documentation of this file.

/*
 * wave-crypto.h
 *
 * Copyright (C) 2007,2009,2011  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Simple API for cryptography.  These are helper functions layered on top of
 * the RSA APIs.
 */

#ifndef WAVEPACKET_CRYPTO_H__
#define WAVEPACKET_CRYPTO_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "threadsafe/smart_ptr.h"


namespace crypto {

/// \ingroup lib
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
///     \defgroup crypto Cryptography Libraries
///
///     Provides basic encryption support.
///
///     Simple objects to abstract:
///       - RSA Keys (public/private pair)
///       - RSA Public Key (just the public key from an RSA pair)
///       - DES Key (used for fast symmetric encryption)
///
///     These are optimized for usability (and correctness) over efficiency! 
///     If you are
///     doing hardcore crypto you should use the RSA APIs directly.  For
///     instance, these APIs aren't clever about memory management, they
///     allocate and de-allocate as needed.
///
///     Encrypted strings have simple encoding applied so they are safe to
///     pass around as strings (no null characters and should be MIME-friendly).
///     Decryption routines assume the string is encoded and they will decode
///     first.  In theory these could be split out but in practice I expect
///     most people to just treat the encrypted strings opaquely anyway.
///
///     These APIs are best for applications that are using crypto tactically
///     in just a few rarely-used places.
///
///     Seed the randomizer before calling any crypto APIs
///
///     Because the RSA libraries are confusing (or at least, I wasn't clever
///     enough to determine if there was a standard way of serializing keys or
///     not),
///     I don't think the results
///     of these can be mixed with other libraries.  That is, you can't take
///     the encrypted value from this API and decrypt it using another API.  All
///     encryption/decryption must happen using these APIs (although that can
///     happen across processes and machines, etc.).
///
///     These aren't designed for streaming.  These are designed for
///     encryption of small blocks of data (a couple of KB or so at most).
///     These APIs are designed for user-readable null-terminated strings, not
///     arbitrary binary data.
///
///     Typical usage is to create a DESKey for use in encrypting data,
///     and only use the public/private keys to safely exchange the DES key.
///
///     Example:
///
///     Generate RSAKey on host 1:
/// \code
///             smart_ptr<RSAKey> rsa = RSAKey::create();       // expensive!
///             smart_ptr<RSAPublicKey> pubkey = rsa->getPublicKey();
///             std::string serialized = pubkey->serialize();
///
///             // great, now send serialized version of public key to host 2
///             send_string_to("host2", serialized);
/// \endcode
///
///     Then, on host 2:
/// \code
///             // receive string from remote host
///             std::string serialized = get_string_from("host1");
///
///             // deserialize into local version of their public key
///             smart_ptr<RSAPublicKey> pubkey =
///                 RSAPublicKey::create(serialized.c_str());
///
///             // create a new secret symmetric encryption key
///             smart_ptr<DESKey> secret = DESKey::create();
///             std::string des_serial = secret->serialize();
///
///             // encrypt DES key (secret) with host 1's public key
///             std::string encrypted = pubkey->encrypt(des_serial.c_str());
///
///             // send secret to host 1
///             send_string_to("host1", encrypted);
/// \endcode
///
///     Then, back on host 1:
/// \code
///             // receive encrypted secret from host 2
///             std::string encrypted = get_string_from("host2");
///
///             // decrypt using our private key
///             std::string serialized = rsa->decrypt(encrypted.c_str());
///
///             // deserialize DES key so we have a local copy
///             smart_ptr<DESKey> secret = DESKey::create(serialized.c_str());
///
///             // now I can communicate with host 2 using shared secret key
///             std::string password = secret->encrypt("This is my password!");
///             send_string_to("host2", password);
/// \endcode
///
///     Don't get too excited about these, because you are still vulnerable to
///     attack/cracking during the initial handshake phase (how do you trust
///     the machine you are handing your public key to?).  But these are
///     intended to make it harder to crack non-critical data, for instance
///     game data where you want to make it more expensive but not necessarily
///     impossible to crack other players' packets.
///
///     Put another way, the code above is vulnerable to man-in-the-middle
///     attacks but is good protection against passive listeners.
///
///     Also, someday this library may beef up the handshake process, at which
///     point the other code could be more generally useful and secure.
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// public key suitable for encrypting
///
/// Get these from a private/public RSAKey or by serializing
///  and deserializing
class RSAPublicKey {
public:
        // virtual destructor --------------------------------------------------
        virtual ~RSAPublicKey(void) throw();

        // crypto::RSAPublicKey class interface methods ------------------------
        /// return a serialized (string) version of the public key
        virtual std::string serialize(void) = 0;

        /// return the given text encrypted with the public key
        virtual std::string encrypt(IN const char * plaintext) = 0;

        // static factory methods ----------------------------------------------
        /// factory to create public key from serialized (string) version
        static smart_ptr<RSAPublicKey> create(IN const char * serialized);
};


/// private/public key pair.
class RSAKey {
public:
        // virtual destructor --------------------------------------------------
        virtual ~RSAKey(void) throw();

        // crypto::RSAKey class interface methods ------------------------------
        /// return the public key for the public/private pair
        virtual smart_ptr<RSAPublicKey> getPublicKey(void) = 0;

        /// decrypt a string encrypted with the public key, using the private key
        virtual std::string decrypt(IN const char * encrypted) = 0;

        // static factory methods ----------------------------------------------
        /// create new RSA public/private key pair (note: very expensive!)
        static smart_ptr<RSAKey> create(void);
};



/// fast symmetric encryption
class DESKey {
public:
        // virtual destructor --------------------------------------------------
        virtual ~DESKey(void) throw();

        // crypto::DESKey class interface methods -----------------------------
        /// return a serialized (string) version of the DES key
        virtual std::string serialize(void) = 0;

        /// encrypt the given plaintext string using the DES key
        /// (pads if necessary to fill out to minSize)
        virtual std::string encrypt(IN const char * plaintext,
                                        IN int minSize) = 0;

        /// decrypt the given string using the DES key (returns original plaintext)
        virtual std::string decrypt(IN const char * encrypted) = 0;

        // static factory methods ----------------------------------------------
        /// create new DES key
        static smart_ptr<DESKey> create(void);

        /// factory to create DES key from serialized (string) version
        static smart_ptr<DESKey> create(IN const char * serialized);
};


/// quick one-way encryption (SHA1 algorithm, see
/// http://en.wikipedia.org/wiki/SHA-1)
std::string getSHA1(IN const char * data);


/// given binary data, encode into base64 ascii string
std::string encodeBase64(IN const byte_t * data, IN long bytes,
                                IN bool encodeLength = true);


typedef std::vector<byte_t> vec_byte_t;

/// given base64 ascii string, decode into byte array
void decodeBase64(IN const char * base64,
                                OUT vec_byte_t& data);


/*@}*/  // end of documentation group


};      // crypto namespace


#endif  // WAVEPACKET_CRYPTO_H__