Provided by: libbobcat-dev_5.00.02-2_amd64 bug

NAME

       FBB::EncryptBuf - Encrypts information using various methods into a std::ostream

SYNOPSIS

       #include <bobcat/encryptbuf>
       Linking option:  -lbobcat -lcrypto

DESCRIPTION

       FBB::EncryptBuf  objects  are  std::streambuf  objects  that  can  be  used  to initialize
       std::ostream objects.

       All information inserted into such  a  std::ostream  is  encrypted  and  written  into  an
       std::ostream that is given as argument to EncryptBuf’s constructor.

       All  encryption  methods supported by the OpenSSL library that can be selected by name may
       be used by 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).

       Most modes use initialization vectors. Unless provided  at  construction  time  EncryptBuf
       objects  create  random initialization vectors. The initialization vector that is actually
       used can be obtained from the EncryptBuf  object.  This  is  important,  as  the  matching
       decryption  object  needs  to know the initialization vector that was used when encrypting
       the data. Initialization vectors are not considered confidential and 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  encryption  method  it  is  automatically  extended with 0-bytes to the
       required length.

       Block ciphers use one of the following four encryption modes:

       o      CBC (Cipher Block Chaining):
              The first block is XOR-ed by the initialization vector and then encrypted using the
              specified  method.  Subsequent  blocks  are  XOR-ed by the encrypted version of the
              preceding  block.  Due  to  the  initialization  vector  dictionary   attacks   are
              infeasible, as long as the initialization vector is truly random.

       o      ECB (Electronic Code Book):
              Each  block is encrypted by itself, using the specified encryption method. Although
              an initialization vector  may  be  specified,  it  is  not  used.  This  method  is
              susceptible  to dictionary attacks and should therefore be avoided, unless you know
              what you’re doing.

       o      CFB (Cipher Feednack):
              This method allows a block cipher to be  used  as  a  stream  cipher.  It  uses  an
              initialization  vector,  which  should  be unique and random for each new stream of
              data that is encrypted using the method. Encryption can only start after the  first
              data block has been received.

       o      OFB (Output Feednack):
              This is an alternative way to use a block cipher as a stream cipher. It is somewhat
              more susceptible to traditional data manipulation attacks,  which  can  usually  be
              thwarted  when  a  message authentication code is added to the information as well.
              Like CFB it uses an initialization vector, which should again be unique and  random
              for each new stream of data that is encrypted.

       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.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       FBB::CryptBuf, in turn inheriting from std::streambuf

CONSTRUCTOR/DESTRUCTOR

       o      EncryptBuf(std::ostream &outStream,  char  const  *type,  std::string  const  &key,
              std::string const &iv, size_t bufsize = 1024):
              This  constructor initializes the EncryptBuf object preparing it for the encryption
              algorithm specified with type. The encryption  algorithms  that  can  be  used  are
              listed  in the abovementioned table. E.g., to use the AES method on 24 bit keys and
              blocks in CBC mode specify "aes-192-cbc". The key parameter refers to the key to be
              used,  the iv parameter refers to the initialization vector to use. Both key and iv
              may contain non-displayable characters. When iv.length() is zero it will be  filled
              by  the  EncryptBuf  object  with  random  data.  When  the iv is too small for the
              requested method it is expanded by adding the required number of zero valued bytes.

              The constructor throws an FBB::Exception  exception  if  an  encryption  method  is
              specified that is not supported by OpenSSL.

              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 temporarily storing incoming characters. The provided  default  argument
              can most likely be kept as-is.

       o      ~EncryptBuf():
              Normally, once all information has been inserted into the encryption stream the end
              manipulator  (see  below)  is  inserted  to  complete   the   encryption   process.
              Alternatively,  the  encryption  process  ends  once the EncryptBuf’s destructor is
              called. E.g., if encStream is  the  std::ostream  to  receive  the  information  to
              encrypt and inStream is the std::istream containing the information to encrypt then

                  endStream << inStream.rdbuf();

              completes the decryption once EncryptBuf’s destructor is called. Alternatively,

                  encStream << inStream.rdbuf() << end;

              can be used to immediately complete the encryption process.

       Copy and move constructors (and assignment operators) are not available.

MEMBER FUNCTIONS

       All members of std::streambuf are available, as FBB::EncryptBuf inherits from this class.

       o      size_t blockLength() const:
              This  member  returns  the  block  size  (in  bytes) that are used by the specified
              method.

       o      size_t ivLength() const:
              This member returns the size (in bytes) of the initialization vector that  is  used
              by the specified method.

       o      std::string iv() const:
              This  member  returns  a reference to the initialization vector that is used by the
              specified  method.  Be  advised  that  the  initialization   vector   may   contain
              non-displayable characters.

       o      size_t keyLength() const:
              This  member  returns the size of the key (in bytes) that are used by the specified
              method.

       o      size_t rounds() const:
              This member can only be used with the RC5 encryption method to query the number  of
              rounds of the algorithm. It returns the currently used number of rounds or 0 if the
              member is called for another encryption method than RC5.

       o      bool setRounds(size_t nRounds):
              This member can only be used with the RC5 encryption method to set  the  number  of
              rounds  of  the  algorithm  to  8, 12 or 16. When the number of rounds were updated
              successfully the member returns true. It returns false in other cases (e.g., called
              for other encryption methods than RC5 or the requested number of rounds differ from
              8, 12 or 16).

PROTECTED MEMBER

       o      EVP_CIPHER_CTX *cipherCtx():
              Classes derived from EncryptBuf may use this member to gain direct  access  to  the
              EVP_CIPHER_CTX  pointer used by the EncryptBuf object. This pointer is a pointer to
              an opaque structure used by many OpenSSL functions to set or query parameters of an
              encryption method.

EXAMPLE

       #include <iostream>
       #include <iomanip>
       #include <fstream>
       #include <bobcat/exception>
       #include <bobcat/ohexbuf>
       #include "../encryptbuf"

       #include <openssl/evp.h>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           if (argc == 1)
               throw Exception(1) <<
                           "1st arg: method, 2nd arg: key, 3rd arg:  (opt): iv, "
                           "stdin: file to encrypt (to stdout)\n"
                   "e.g., driver aes-128-cbc somekey < driver.cc > /tmp/enc\n";

           string key(argv[2]);
           string iv;

           if (argc > 3)
               iv = argv[3];

           EncryptBuf encryptbuf(cout, argv[1], key, iv, 50);

           ostream out(&encryptbuf);

           size_t ivLength = encryptbuf.iv().length();
           cerr << "Block length: " << encryptbuf.blockLength() << "\n"
                   "Key length: " << encryptbuf.keyLength() << "\n"
                   "Max Key length: " << EVP_MAX_KEY_LENGTH << "\n"
                   "actual IV length: " << ivLength << "\n"
                   "IV =\n";

           OHexBuf ohb{ cerr, ivLength << 1 };
           ostream outHex(&ohb);
           outHex << encryptbuf.iv();
           cerr << ’\n’ << dec;

           out << cin.rdbuf() << eoi;
       }
       catch(exception const &err)
       {
           cerr << err.what() << 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/ofilterbuf>

           class Skip256: public FBB::OFilterBuf
           {
               size_t d_count;
               public:
                   Skip256(std::ostream &os)
                   :
                       OFilterBuf(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, "");

FILES

       bobcat/encryptbuf - defines the class interface

SEE ALSO

       bobcat(7), decryptbuf(3bobcat), ofilterbuf(3bobcat), std::streambuf

BUGS

       None reported

DISTRIBUTION FILES

       o      bobcat_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.00.02-x_*.deb: debian package holding the libraries,  headers  and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This  is  free  software,  distributed  under  the terms of the GNU General Public License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).