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

NAME

       FBB::DecryptBuf - Decrypts information using various methods into a std::ostream

SYNOPSIS

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

DESCRIPTION

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

       All information inserted into  such  an  std::ostream  is  decrypted  and  written  to  an
       std::ostream passed as argument to DecryptBuf’s constructor.

       All  encryption  methods supported by the OpenSSL library that can be selected by name may
       be used by DecryptBuf objects. In practice the information has previously  been  encrypted
       by  an  EncryptBuf  object,  using  the  same encryption method. Likewise, the constructor
       expects a key and initialization vector. The key and initialization vector that was passed
       to the EncryptBuf object must be passed to DecryptBuf’s constructor as well.

       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      DecryptBuf(std::ostream  &outStream,  char  const  *type,  std::string  const &key,
              std::string const &iv, size_t bufsize = 1024):
              This constructor initializes the DecryptBuf object preparing it for the  decryption
              algorithm  specified  by  type.  The  decryption  algorithms that are available are
              listed in the abovementioned table. As an example: to use the AES method on 192 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 that was  used
              when  encrypting  the  original information. The IV is not considered confidential.
              When using ECB modes no initialization vector is used. In those cases any non-empty
              initialization vector may be provided.

              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  receiving  the
              decrypted information.

              The  bufsize  argument  specifies  the size in bytes of the internal buffer used by
              DecryptBuf temporarily storing incoming characters. The provided  default  argument
              can most likely be kept as-is.

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

                  decStream << encStream.rdbuf();

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

                  desStream << encStream.rdbuf() << eoi;

              can be used to immediately complete the decryption process.

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

MEMBER FUNCTIONS

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

       o      void eoi():
              This member can be called instead of using the manipulator to  end  the  decryption
              process.  It  throws an std::exception if decryption fails (which may happen if the
              DecryptBuf object is provided with incorrect (usually improperly padded) input).

       o      bool setRounds(size_t nRounds):
              This member can only be used with the RC5 decryption 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 decryption 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 DecryptBuf may use this member to gain direct  access  to  the
              EVP_CIPHER_CTX  pointer used by the DecryptBuf object. This pointer is a pointer to
              an opaque structure used by many OpenSSL functions to set or query parameters of an
              decryption method.

MANIPULATOR

       o      FBB::eoi:
              The  eoi  manipulator  can  be  inserted into the decryption stream to complete the
              decryption process. If it is inserted into an std::ostream that is not  initialized
              with either a DecryptBuf or an EncryptBuf nothing happens.

EXAMPLE

       #include <iostream>
       #include <fstream>
       #include <bobcat/exception>
       #include <bobcat/ohexbuf>

       #include <openssl/evp.h>
       #include <openssl/err.h>

       #include "../decryptbuf"
       #include "../../encryptbuf/encryptbuf"

       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: iv, "
                           "4th arg: file to decrypt (to stdout)";

           // e.g., driver aes-128-cbc somekey iv-from-encryptbuf-driver
           // /tmp/enc > /tmp/driver.dec

           cerr << "Key: `" << argv[2] << "’\n"
                   "IV:  `" << argv[3] << "’\n";

           DecryptBuf decryptbuf(cout, argv[1], argv[2], argv[3]);

           ostream out(&decryptbuf);
           ifstream in(argv[4]);

           if (not in)
               throw Exception{} << "can’t read `" << argv[4] << ’\n’;

           out << in.rdbuf() << eoi;
       }
       catch(exception const &err)
       {
           cout << err.what() << endl;
           return 1;
       }

FILES

       bobcat/decryptbuf - defines the class interface

SEE ALSO

       bobcat(7), encryptbuf(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).