Cipher Class Reference

The cipher object encrypts plaintext data or decrypts ciphertext data. More...

#include <cipher.h>

Collaboration diagram for Cipher:

Public Types
typedef uchar	aes_iv_t [32]
typedef uchar	aes_key_t [32]
typedef uchar	aes_salt_t [8]
typedef std::pair< uchar *, uint >	kv1_t
typedef unsigned char	uchar
typedef unsigned int	uint

Public Member Functions
	Cipher ()
	Constructor. More...
	Cipher (const std::string &cipher, const std::string &digest, uint count, bool embed=true)
	Constructor. More...
	~Cipher ()
	Destructor. More...
void	debug (bool b=true)
	Set the internal debug flag. More...
bool	debug () const
	Is debug mode set? More...
kv1_t	decode_base64 (const std::string &mimetext) const
	Base64 decode. More...
std::string	decode_cipher (uchar *ciphertext, uint ciphertext_len) const
	Cipher decode. More...
std::string	decrypt (const std::string &ciphertext, const std::string &pass="", const std::string &salt="")
	Decrypt a buffer using AES 256 CBC (SHA1). More...
void	decrypt_file (const std::string &ifn, const std::string &ofn, const std::string &pass="", const std::string &salt="")
	Decrypt a file. More...
std::string	encode_base64 (uchar *ciphertext, uint ciphertext_len) const
	Base64 encode. More...
kv1_t	encode_cipher (const std::string &plaintext) const
	Cipher encode. More...
std::string	encrypt (const std::string &plaintext, const std::string &pass="", const std::string &salt="")
	Encrypt buffer using AES 256 CBC (SHA1). More...
void	encrypt_file (const std::string &ifn, const std::string &ofn, const std::string &pass="", const std::string &salt="")
	Encrypt a file. More...
std::string	file_read (const std::string &fn) const
	Read a file into a buffer. More...
void	file_write (const std::string &fn, const std::string &data, bool nl=false) const
	Write ASCII data to a file. More...

Private Member Functions
void	init (const std::string &pass)
	Initialize the cipher: set the key and IV values. More...
void	set_salt (const std::string &salt)
	Convert string salt to internal format. More...

Private Attributes
std::string	m_cipher
uint	m_count
bool	m_debug
std::string	m_digest
bool	m_embed
aes_iv_t	m_iv
aes_key_t	m_key
std::string	m_pass
aes_salt_t	m_salt

Detailed Description

The cipher object encrypts plaintext data or decrypts ciphertext data.

All data is in ASCII because it is MIME encoded.

The default cipher used is AES-256-CBC from the openssl library but there are many others available. The default digest used is SHA1 which is stronger than MD5.

The algorithms mimic openssl so files created with this object and with the openssl tool are interchangeable.

Here is how you would use it to encrypt and decrypt plaintext data in memory.

*   #include "cipher.h"
*   #include <string>
*   using namepsace std;
*
*   // Example the encrypts and decrypts some plaintext.
*   // Use encrypt_file or decrypt_file to deal with files.
*   void cipher_test()
*   {
*      string pass = "testTEST!23_";
*      string salt = "12345678"; // must be 8 chars
*      string plaintext = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
*
*      // Encrypt and decrypt.
*      Cipher c;
*      string ciphertext = c.encrypt(plaintext ,pass,salt);
*      string decoded    = c.decrypt(ciphertext,pass,salt);
*
*      // Test the results
*      if (plaintext == decoded) {
*         cout << "passed" << endl;
*      }
*      else {
*         cout << "failed" << endl;
*      }
*   }
* 

Author

Joe Linoff

Definition at line 74 of file cipher.h.

Member Typedef Documentation

typedef uchar Cipher::aes_iv_t[32]

Definition at line 80 of file cipher.h.

typedef uchar Cipher::aes_key_t[32]

Definition at line 79 of file cipher.h.

typedef uchar Cipher::aes_salt_t[8]

Definition at line 81 of file cipher.h.

typedef std::pair<uchar*,uint> Cipher::kv1_t

Definition at line 82 of file cipher.h.

typedef unsigned char Cipher::uchar

Definition at line 78 of file cipher.h.

typedef unsigned int Cipher::uint

Definition at line 77 of file cipher.h.

Constructor & Destructor Documentation

Cipher::Cipher

(

)

Constructor.

Definition at line 149 of file cipher.cc.

  : m_cipher(CIPHER_DEFAULT_CIPHER),
    m_digest(CIPHER_DEFAULT_DIGEST),
    m_count(CIPHER_DEFAULT_COUNT),
    m_embed(true), // compatible with openssl
    m_debug(false)
{
}

Cipher::Cipher	(	const std::string &	cipher,
		const std::string &	digest,
		uint	count,
		bool	embed = true
	)

Constructor.

Parameters

cipher	The cipher algorithm to use (def. aes-256-cbc).
digest	The digest to use (def. sha1).
count	The number of iterations (def. 1).
embed	Embed the salt. If this is false, the output will not be compatible with openssl.

Definition at line 161 of file cipher.cc.

  : m_cipher(cipher),
    m_digest(digest),
    m_count(count),
    m_embed(embed),
    m_debug(false)
{
}

Cipher::~Cipher

(

)

Destructor.

Definition at line 176 of file cipher.cc.

{
}

Member Function Documentation

void Cipher::debug ( bool  b = true )

inline

Set the internal debug flag.

This is only useful for library developers.

Parameters

b	True for debug or false otherwise.

Definition at line 270 of file cipher.h.

References m_debug.

{m_debug=b;}

bool Cipher::debug ( ) const

inline

Is debug mode set?

Returns

The current debug mode.

Definition at line 275 of file cipher.h.

References m_debug.

{return m_debug;}

Cipher::kv1_t Cipher::decode_base64

(

const std::string &

mimetext

)

const

Base64 decode.

Parameters

mimetext

ASCII MIME text.

Returns

Binary data.

Definition at line 290 of file cipher.cc.

References DBG_FCT.

Referenced by decrypt().

{
  DBG_FCT("decode_base64");
  kv1_t x;
  int SZ=mimetext.size(); // this will always be smaller
  x.first = new uchar[SZ];
  char* tmpbuf = new char[SZ+1];
  strcpy(tmpbuf,mimetext.c_str());
  BIO* b64 = BIO_new(BIO_f_base64());

  // This patch was suggested by Mihai Todor.
  // It was added to the code on 2013-11-21.
  // Please see this post for details:
  //    http://joelinoff.com/blog/?p=664
  if (SZ <= 64) {
    // If the string is less len 64 or less,
    // then the -A switch must be used in
    // openssl.
    BIO_set_flags(b64, BIO_FLAGS_BASE64_NO_NL);
  }

  BIO* bm  = BIO_new_mem_buf(tmpbuf,mimetext.size());
  bm = BIO_push(b64,bm);
  x.second = BIO_read(bm,x.first,SZ);
  BIO_free_all(bm);
  delete [] tmpbuf;
  return x;
}

Here is the caller graph for this function:

string Cipher::decode_cipher	(	uchar *	ciphertext,
		uint	ciphertext_len
	)		const

Cipher decode.

Parameters

ciphertext	Binary cipher text.
ciphertext_len	Length of cipher buffer.

Returns

The decoded ASCII string.

Definition at line 371 of file cipher.cc.

References DBG_FCT, m_iv, and m_key.

Referenced by decrypt().

{
  DBG_FCT("decode_cipher");
  uint SZ = ciphertext_len+20;
  uchar* plaintext = new uchar[SZ];
  bzero(plaintext,SZ);
  int plaintext_len = 0;
  EVP_CIPHER_CTX ctx;
  EVP_CIPHER_CTX_init(&ctx);

  if (!EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, m_key, m_iv)) {
    throw runtime_error("EVP_DecryptInit_ex() failed");
  }
  EVP_CIPHER_CTX_set_key_length(&ctx, EVP_MAX_KEY_LENGTH);

  if (!EVP_DecryptUpdate(&ctx,plaintext,&plaintext_len,ciphertext,ciphertext_len)) {
    throw runtime_error("EVP_DecryptUpdate() failed");
  }

  int plaintext_padlen=0;
  if (!EVP_DecryptFinal_ex(&ctx,plaintext+plaintext_len,&plaintext_padlen)) {
    throw runtime_error("EVP_DecryptFinal_ex() failed");
  }
  plaintext_len += plaintext_padlen;
  plaintext[plaintext_len] = 0;
    
  string ret = (char*)plaintext;
  delete [] plaintext;
  return ret;
}

Here is the caller graph for this function:

string Cipher::decrypt	(	const std::string &	ciphertext,
		const std::string &	pass = "",
		const std::string &	salt = ""
	)

Decrypt a buffer using AES 256 CBC (SHA1).

Parameters

ciphertext	The encrypted data.
pass	The passphrase.
salt	The optional salt.

Returns

The plaintext: decrypted, MIME decoded data.

Definition at line 218 of file cipher.cc.

References DBG_BDUMP, DBG_FCT, DBG_MDUMP, decode_base64(), decode_cipher(), init(), m_salt, SALTED_PREFIX, and set_salt().

Referenced by decrypt_file().

{
  DBG_FCT("decrypt");
  kv1_t  x     = decode_base64(mimetext);
  uchar* ct    = x.first;
  uchar* ctbeg = ct;
  uint   ctlen = x.second;
  DBG_BDUMP(ct,ctlen);

  if (strncmp((const char*)ct,SALTED_PREFIX,8) == 0) {
    memcpy(m_salt,&ct[8],8);
    ct += 16;
    ctlen -= 16;
  }
  else {
    set_salt(salt);
  }
  init(pass);
  string ret = decode_cipher(ct,ctlen);
  delete [] ctbeg;
  DBG_MDUMP(ret);
  return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void Cipher::decrypt_file	(	const std::string &	ifn,
		const std::string &	ofn,
		const std::string &	pass = "",
		const std::string &	salt = ""
	)

Decrypt a file.

Here is a usage example.

*   #include "cipher.h"
*   #include <iostream>
*   #include <string>
*   using namepsace std;
*
*   void example()
*   {
*      string pass = "password";
*      string salt = "12345678";    // must be 8
*      string ifn  = "license.dat"; // ciphertext
*      string ofn  = "license.txt"; // plaintext
*
*      // Decrypt file.
*      // It is the same as running this command:
*      // % openssl enc -d -a -md sha1 -aes-256-cbc -salt -p \
*      //       -pass pass:password                          \
*      //       -in license.dat -out license.txt
*      // NOTE: it is not necessary to specify the salt for decryption.
*      try {
*         Cipher c;
*         c.decrypt_file(ifn,ofn,pass,salt);
*      }
*      catch (exception& e) {
*         cerr << "ERROR: " << e.what() << endl;
*      }
*   }
* 

Parameters

ifn	The encrypted file.
ofn	The plaintext file.
pass	The passphrase.
salt	The optional salt.

Definition at line 247 of file cipher.cc.

References DBG_FCT, decrypt(), file_read(), and file_write().

{
  DBG_FCT("decrypt_file");
  string ciphertext = file_read(ifn);
  string plaintext = decrypt(ciphertext,pass,salt);
  file_write(ofn,plaintext);
}

Here is the call graph for this function:

string Cipher::encode_base64	(	uchar *	ciphertext,
		uint	ciphertext_len
	)		const

Base64 encode.

Parameters

ciphertext	Binary cipher text.
ciphertext_len	Length of cipher buffer.

Returns

The encoded ASCII MIME string.

Definition at line 261 of file cipher.cc.

References DBG_FCT.

Referenced by encrypt().

{
  DBG_FCT("encode_base64");
  BIO* b64 = BIO_new(BIO_f_base64());
  BIO* bm  = BIO_new(BIO_s_mem());
  b64 = BIO_push(b64,bm);
  if (BIO_write(b64,ciphertext,ciphertext_len)<2) {
    throw runtime_error("BIO_write() failed");
  }
  if (BIO_flush(b64)<1) {
    throw runtime_error("BIO_flush() failed");
  }
  BUF_MEM *bptr=0;
  BIO_get_mem_ptr(b64,&bptr);
  uint len=bptr->length;
  char* mimetext = new char[len+1];
  memcpy(mimetext, bptr->data, bptr->length-1);
  mimetext[bptr->length-1]=0;
  BIO_free_all(b64);

  string ret = mimetext;
  delete [] mimetext;
  return ret;
}

Here is the caller graph for this function:

Cipher::kv1_t Cipher::encode_cipher

(

const std::string &

plaintext

)

const

Cipher encode.

Parameters

plaintext

ASCII data to encode.

Returns

Binary data.

Definition at line 322 of file cipher.cc.

References DBG_FCT, m_embed, m_iv, m_key, m_salt, and SALTED_PREFIX.

Referenced by encrypt().

{
  DBG_FCT("encode_cipher");
  uint SZ=plaintext.size()+AES_BLOCK_SIZE+20;
  uchar* ciphertext = new uchar[SZ];
  bzero(ciphertext,SZ);
  uchar* pbeg = ciphertext;

  // This requires some explanation.
  // In order to be compatible with openssl, I need to append
  // 16 characters worth of information that describe the salt.
  // I found this in the openssl source code but I couldn't
  // find any associated documentation.
  uint off = 0;
  if (m_embed) {
    memcpy(&ciphertext[0],SALTED_PREFIX,8);
    memcpy(&ciphertext[8],m_salt,8);
    off = 16;
    ciphertext += off;
  }

  int ciphertext_len=0;
  int ciphertext_padlen=0;
  EVP_CIPHER_CTX ctx;
  EVP_CIPHER_CTX_init(&ctx);

  if (!EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, m_key, m_iv)) {
    throw runtime_error("EVP_EncryptInit_ex() failed");
  }
  EVP_CIPHER_CTX_set_key_length(&ctx, EVP_MAX_KEY_LENGTH);

  uchar* p    = (uchar*)plaintext.c_str();
  uint   plen = plaintext.size();
  if (!EVP_EncryptUpdate(&ctx,ciphertext,&ciphertext_len,p,plen)) {
    throw runtime_error("EVP_EncryptUpdate() failed");
  }

  uchar* pbuf = ciphertext+ciphertext_len; // pad at the end
  if (!EVP_EncryptFinal_ex(&ctx,pbuf,&ciphertext_padlen)) {
    throw runtime_error("EVP_EncryptFinal_ex() failed");
  }

  ciphertext_len += ciphertext_padlen + off; // <off> for the Salted prefix
  return kv1_t(pbeg,ciphertext_len);
}

Here is the caller graph for this function:

string Cipher::encrypt	(	const std::string &	plaintext,
		const std::string &	pass = "",
		const std::string &	salt = ""
	)

Encrypt buffer using AES 256 CBC (SHA1).

Parameters

plaintext	The plaintext buffer.
pass	The passphrase.
salt	The optional salt.

Returns

The ciphertext: encrypted, MIME encoded data.

Definition at line 183 of file cipher.cc.

References DBG_BDUMP, DBG_FCT, DBG_MDUMP, encode_base64(), encode_cipher(), init(), and set_salt().

Referenced by encrypt_file().

{
  DBG_FCT("encrypt");
  set_salt(salt);
  init(pass);
  kv1_t  x     = encode_cipher(plaintext);
  uchar* ct    = x.first;
  uint   ctlen = x.second;
  DBG_BDUMP(ct,ctlen);

  string ret = encode_base64(ct,ctlen);
  delete [] ct;
  DBG_MDUMP(ret);
  return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void Cipher::encrypt_file	(	const std::string &	ifn,
		const std::string &	ofn,
		const std::string &	pass = "",
		const std::string &	salt = ""
	)

Encrypt a file.

Here is a usage example.

*   #include "cipher.h"
*   #include <iostream>
*   #include <string>
*   using namepsace std;
*
*   void example()
*   {
*      string pass = "password";
*      string salt = "12345678";    // must be 8
*      string ifn  = "license.txt"; // plaintext
*      string ofn  = "license.dat"; // ciphertext
*
*      // Encrypt file.
*      // It is the same as running this command:
*      // % openssl enc -e -a -md sha1 -aes-256-cbc -salt -p \
*      //       -S 49505152535455676758                      \
*      //       -pass pass:password                          \
*      //       -in license.txt -out license.dat
*      try {
*         Cipher c;
*         c.encrypt_file(ifn,ofn,pass,salt);
*      }
*      catch (exception& e) {
*         cerr << "ERROR: " << e.what() << endl;
*      }
*   }
* 

Parameters

ifn	The plaintext file.
ofn	The encrypted file.
pass	The passphrase.
salt	The optional salt.

Exceptions

runtime_error

If a problem occurs.

Definition at line 204 of file cipher.cc.

References DBG_FCT, encrypt(), file_read(), and file_write().

{
  DBG_FCT("encrypt_file");
  string plaintext = file_read(ifn);
  string ciphertext = encrypt(plaintext,pass,salt);
  file_write(ofn,ciphertext,true);
}

Here is the call graph for this function:

string Cipher::file_read

(

const std::string &

fn

)

const

Read a file into a buffer.

Parameters

fn	The file name.

Returns

The file contents.

Exceptions

runtime_error

if the file doesn't exist.

Definition at line 482 of file cipher.cc.

References DBG_FCT.

Referenced by decrypt_file(), and encrypt_file().

{
  DBG_FCT("file_read");
  ifstream ifs(fn.c_str());
  if (!ifs) {
    string msg="Cannot read file '"+fn+"'";
    throw runtime_error(msg);
  }
  string str((istreambuf_iterator<char>(ifs)),
        istreambuf_iterator<char>());
  return str;
}

Here is the caller graph for this function:

void Cipher::file_write	(	const std::string &	fn,
		const std::string &	data,
		bool	nl = false
	)		const

Write ASCII data to a file.

Parameters

fn	The file name.
data	The data to write.
nl	Append a trailing new line.

Exceptions

runtime_error

if the file cannot be written.

Definition at line 498 of file cipher.cc.

References DBG_FCT.

Referenced by decrypt_file(), and encrypt_file().

{
  DBG_FCT("file_write");
  ofstream ofs(fn.c_str());
  if (!ofs) {
    string msg="Cannot write file '"+fn+"'";
    throw runtime_error(msg);
  }
  ofs << data;
  if (nl) {
    ofs << endl;
  }
  ofs.close();
}

Here is the caller graph for this function:

void Cipher::init ( const std::string &  pass )

private

Initialize the cipher: set the key and IV values.

Parameters

pass	The passphrase.

Definition at line 429 of file cipher.cc.

References DBG_FCT, DBG_PKV, DBG_TDUMP, m_cipher, m_count, m_digest, m_iv, m_key, m_pass, and m_salt.

Referenced by decrypt(), and encrypt().

{
  DBG_FCT("init");
  // Use a default passphrase if the user didn't specify one.
  m_pass = pass;
  if (m_pass.empty() ) {
    // Default: ' deFau1t pASsw0rD'
    // Obfuscate so that a simple strings will not find it.
    char a[] = {' ','d','e','F','a','u','1','t',' ',
      'p','A','S','s','w','0','r','D',0};
    m_pass = a;
  }

  // Create the key and IV values from the passkey.
  bzero(m_key,sizeof(m_key));
  bzero(m_iv,sizeof(m_iv));
  OpenSSL_add_all_algorithms();
  const EVP_CIPHER* cipher = EVP_get_cipherbyname(m_cipher.c_str());
  const EVP_MD*     digest = EVP_get_digestbyname(m_digest.c_str());
  if (!cipher) {
    string msg = "init(): cipher does not exist "+m_cipher;
    throw runtime_error(msg);
  }
  if (!digest) {
    string msg = "init(): digest does not exist "+m_digest;
    throw runtime_error(msg);
  }

  int ks = EVP_BytesToKey(cipher,    // cipher type
           digest,    // message digest
           m_salt,    // 8 bytes
           (uchar*)m_pass.c_str(), // pass value
           m_pass.length(),
           m_count,   // number of rounds
           m_key,
           m_iv);
  if (ks!=32) {
    throw runtime_error("init() failed: "
         "EVP_BytesToKey did not return a 32 byte key");
  }

  DBG_PKV(m_pass);
  DBG_PKV(m_cipher);
  DBG_PKV(m_digest);
  DBG_TDUMP(m_salt);
  DBG_TDUMP(m_key);
  DBG_TDUMP(m_iv);
  DBG_PKV(m_count);
}

Here is the caller graph for this function:

void Cipher::set_salt ( const std::string &  salt )

private

Convert string salt to internal format.

Parameters

salt

The salt.

Definition at line 406 of file cipher.cc.

References DBG_FCT, and m_salt.

Referenced by decrypt(), and encrypt().

{
  DBG_FCT("set_salt");
  if (salt.length() == 0) {
    // Choose a random salt.
    for(uint i=0;i<sizeof(m_salt);++i) {
      m_salt[i] = rand() % 256;
    }
  }
  else if (salt.length() == 8) {
    memcpy(m_salt,salt.c_str(),8);
  }
  else if (salt.length()<8) {
    throw underflow_error("init(): salt is too short, must be 8 characters");
  }
  else if (salt.length()>8) {
    throw overflow_error("init(): salt is too long, must be 8 characters");
  }
}

Here is the caller graph for this function:

Member Data Documentation

std::string Cipher::m_cipher

private

Definition at line 290 of file cipher.h.

Referenced by init().

uint Cipher::m_count

private

Definition at line 295 of file cipher.h.

Referenced by init().

bool Cipher::m_debug

private

Definition at line 297 of file cipher.h.

Referenced by debug().

std::string Cipher::m_digest

private

Definition at line 291 of file cipher.h.

Referenced by init().

bool Cipher::m_embed

private

Definition at line 296 of file cipher.h.

Referenced by encode_cipher().

aes_iv_t Cipher::m_iv

private

Definition at line 294 of file cipher.h.

Referenced by decode_cipher(), encode_cipher(), and init().

aes_key_t Cipher::m_key

private

Definition at line 293 of file cipher.h.

Referenced by decode_cipher(), encode_cipher(), and init().

std::string Cipher::m_pass

private

Definition at line 289 of file cipher.h.

Referenced by init().

aes_salt_t Cipher::m_salt

private

Definition at line 292 of file cipher.h.

Referenced by decrypt(), encode_cipher(), init(), and set_salt().

---

The documentation for this class was generated from the following files:

• src/cipher.h
• src/cipher.cc