All information inserted into such a std::ostream is encrypted and written into a std::ostream that is given as argument to EncryptBuf's constructor.
All encryption methods defined by the OpenSSL library that can be selected by name may be used in combination with EncryptBuf objects. To select a particular encryption method an identifier is passed to the constructor. E.g., "aes-128-cbc" indicating the AES (Rijndael) method, using 128 bit sized keys and blocks using `cbc' mode (see below for an explanation).
When providing shorter keys than expected by the method the provided key is extended by adding the required number of 0-bytes. (zero valued bytes, not '0' characters).
Most modes use an initialization vector. Unless provided at construction time or explicitly set thereafter an initialization vector containg randomly selected values will be used. The initialization vector that is actually used can be obtained from the EncryptBuf object. This is important, as the matching decrypting object needs to know the initialization vector that was used when encrypting the data. Initialization vectors are not security sensitive in the sense that they can be sent in the clear to the decryption object. What is important, though, is that they contain random data when used `for real'. When an initialization vector is specified that is shorter than expected by the method it will be extended with the required number of 0-bytes.
Block ciphers use one of the following four encryption modes:
The following table presents an overview of methods that are currently available. Methods for which the block size is specified as N.A. are stream ciphers; other methods are block ciphers:
| method | keysize | blocksize | mode | identifier |
| (bytes) | (bytes) | |||
| AES | 16 | 8 | CBC | "aes-128-cbc" |
| EBC | "aes-128-ecb" | |||
| CFB | "aes-128-cfb" | |||
| OFB | "aes-128-ofb" | |||
| 24 | 24 | CBC | "aes-192-cbc" | |
| EBC | "aes-192-ecb" | |||
| CFB | "aes-192-cfb" | |||
| OFB | "aes-192-ofb" | |||
| 32 | 32 | CBC | "aes-256-cbc" | |
| EBC | "aes-256-ecb" | |||
| CFB | "aes-256-cfb" | |||
| OFB | "aes-256-ofb" | |||
| BLOWFISH | 16 | 8 | CBC | "bf-cbc" |
| EBC | "bf-ecb" | |||
| CFB | "bf-cfb" | |||
| OFB | "bf-ofb" | |||
| max key length is 56 bytes, 16 generally used | ||||
| CAMELLIA | 16 | 16 | CBC | "camellia-128-cbc" |
| EBC | "camellia-128-ecb" | |||
| CFB | "camellia-128-cfb" | |||
| OFB | "camellia-128-ofb" | |||
| 24 | CBC | "camellia-192-cbc" | ||
| EBC | "camellia-192-ecb" | |||
| CFB | "camellia-192-cfb" | |||
| OFB | "camellia-192-ofb" | |||
| 32 | CBC | "camellia-256-cbc" | ||
| EBC | "camellia-256-ecb" | |||
| CFB | "camellia-256-cfb" | |||
| OFB | "camellia-256-ofb" | |||
| CAST | 16 | 8 | CBC | "cast-cbc" |
| EBC | "cast-ecb" | |||
| CFB | "cast-cfb" | |||
| OFB | "cast-ofb" | |||
| min key length is 5 bytes, max is shown | ||||
| DES | 8 | 8 | CBC | "des-cbc" |
| EBC | "des-ebc" | |||
| CFB | "des-cfb" | |||
| OFB | "des-ofb" | |||
| DESX | 8 | 8 | CBC | "desx-cbc" |
| 3DES | 16 | 8 | CBC | "des-ede-cbc" |
| EBC | "des-ede" | |||
| CFB | "des-ede-cfb" | |||
| OFB | "des-ede-ofb" | |||
| 3DES | 24 | 8 | CBC | "des-ede3-cbc" |
| EBC | "des-ede3" | |||
| CFB | "des-ede3-cfb" | |||
| OFB | "des-ede3-ofb" | |||
| Key bytes 9-16 define the 2nd key, bytes 17-24 | ||||
| define the 3rd key | ||||
| RC2 | 16 | 8 | CBC | "rc2-cbc" |
| EBC | "rc2-ecb" | |||
| CFB | "rc2-cfb" | |||
| OFB | "rc2-ofb" | |||
| Key length variable, max. 128 bytes, default length is shown | ||||
| RC2-40 | 5 | 8 | "rc2-40-cbc" | |
| obsolete: avoid | ||||
| RC2-64 | 8 | 8 | "rc2-64-cbc" | |
| obsolete: avoid | ||||
| RC4 | 16 | N.A. | "rc4" | |
| Key length is variable, max. 256 bytes. default length is shown | ||||
| Encrypt again to decrypt. Don't use DecryptBuf | ||||
| RC4-40 | 5 | N.A. | "rc4-40" | |
| obsolete: avoid | ||||
| RC5 | 16 | 8 | CBC | "rc5-cbc" |
| EBC | "rc5-ecb" | |||
| CFB | "rc5-cfb" | |||
| OFB | "rc5-ofb" | |||
| Key length variable, max. 256 bytes, rounds 8, 12 or 16, | ||||
| default # rounds is 12 |
The RC4 stream cipher is subject to a well-known attack (cf. http://www.wisdom.weizmann.ac.il/~itsik/RC4/Papers/Mantin1.zip) unless the initial 256 bytes produced by the cipher are discarded.
The constructor throws an FBB::Exception exception if an unknown encryption method was specified.
The constructor's first parameter refers to the std::ostream to receive the encrypted information. Be aware of the fact that the encrypted information most likely contains non-displayable characters.
The bufsize argument specifies the size in bytes of the internal buffer used by EncryptBuf to store incoming characters temporarily. The provided default argument should be OK in all normal cases.
All members of std::streambuf are available, as FBB::EncryptBuf inherits from this class. Some of the std::streambuf's member are overridden or are hidden by EncryptBuf. In normal situations these inherited members will not be used by programs using EncryptBuf objects.
#include <iostream>
#include <fstream>
#include <bobcat/errno>
#include <bobcat/encryptbuf>
#include <bobcat/ohexstreambuf>
#include <openssl/evp.h>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
try
{
if (argc == 1)
throw Errno("1st arg: method, 2nd arg: key, 3rd arg: (opt): iv, "
"stdin: file to encrypt (to stdout)");
string key(argv[2]);
string iv;
if (argc > 3)
iv = argv[3];
EncryptBuf encryptbuf(cout, argv[1], key, iv);
ostream out(&encryptbuf);
cerr << "Block length: " << encryptbuf.blockLength() << '\n' <<
"Key length: " << encryptbuf.keyLength() << '\n' <<
"Max Key length: " << EVP_MAX_KEY_LENGTH << '\n' <<
"IV length: " << encryptbuf.ivLength() << endl;
cerr << encryptbuf.iv().length() << ' ';
OHexStreambuf ohsb(cerr);
ostream ohs(&ohsb);
ohs.write(encryptbuf.iv().data(), encryptbuf.iv().length()) << flush;
cerr << endl;
out << cin.rdbuf();
}
catch(Errno const &err)
{
cout << err.why() << endl;
return 1;
}
To ignore the initial 256 bytes generated by the RC4 algorithm a simple wrapper class around the eventual output stream can be used. Here is an illustration:
#include <ostream>
#include <bobcat/ofilterstreambuf>
class Skip256: public FBB::OFilterStreambuf
{
size_t d_count;
public:
Skip256(std::ostream &os)
:
OFilterStreambuf(os),
d_count(0)
{}
private:
virtual int overflow(int c)
{
if (d_count == 256)
out().put(c);
else
++d_count;
return c;
}
};
Next, an Skip256 object is used to define an intermediate
std::ostream that is then passed to the EncryptBuf object. E.g., only
showing the essential steps defining the EncryptBuf object:
Skip256 skip256(std::cout);
std::ostream out(&skip256);
EncryptBuf encryptbuf(out, "rc4", key, "");