Provided by: libbobcat-dev_4.08.02-2build1_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 with.

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

       All  encryption methods defined by the OpenSSL library that can be selected by name may be
       used in combination with DecryptBuf objects. Most likely the information  will  have  been
       encrypted  using  an  EncryptBuf  object,  selecting  a  particular encryption method. The
       encryption  method  used  when  encrypting  information  should  also  be  specified  when
       constructing   a   DecryptBuf   object.  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

       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  message
              decrypt  algorithm  specified with type. The decryption algorithms that can be used
              are listed in the table  found  in  the  EncryptBuf(3bobcat)  manual  page.  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 to use. The iv’s length cannot be zero. 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 unknown encryption method
              was specified.

              The constructor’s first  parameter  refers  to  the  std::ostream  to  receive  the
              decrypted information.

              The  bufsize  argument  specifies  the size in bytes of the internal buffer used by
              DecryptBuf to store incoming characters temporarily. The provided default  argument
              should be OK in all normal cases.

       o      ~DecryptBuf():
              The  destructor  calls the done() member (see below), prevending any exception that
              function might throw  from  leaving  the  destructor.  In  this  case  only  a  non
              thread-safe  way  to determine whether the decryption was successfully completed is
              available through the static member function lastOK() (see  below).   There  is  no
              copy constructor, nor move constructor (as std::streambuf doesn’t support either).

MEMBER FUNCTIONS

       All  members of std::streambuf are available, as FBB::DecryptBuf inherits from this class.
       Some of the std::streambuf’s member are overridden or are hidden by DecryptBuf. In  normal
       situations these inherited members will not be used by programs using DecryptBuf objects.

       o      void done():
              This member can be called to indicate that all information to be decrypted has been
              received. It throws an FBB::Exception exception if decryption fails (resulting from
              providing  the DecryptBuf object with incorrect (usually improperly padded) input).
              If not explicitly called it is called by DecryptBuf’s  destructor,  preventing  its
              exception from leaving the destructor.

       o      void setIv(std::string const &iv):
              This  member  can  be  used  to  specify  the  initialization  vector  to use after
              construction time but before  any  data  has  been  decrypted.  When  called  after
              decryption  has  started  or  when  specifying  an  empty  initialization vector an
              FBB::Exception exception will be thrown.  When using ECB  modes  no  initialization
              vector is used. In those cases any non-empty initialization vector may be provided.

       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).

STATIC MEMBER

       o      bool lastOK():
              This  member  is  a  non  thread-safe  way  to determine whether the decryption has
              succeeded when the  DecryptBuf object’s done member has not  been  called  and  the
              object  has  been destroyed. In that case the object’s destructor will call done to
              complete the decryption. The member lastOK returns true if  the  DecryptBuf  object
              destroyed  last  could  complete  its  decryption  successfully  and  returns false
              otherwise.

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.

EXAMPLE

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

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

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

           DecryptBuf decryptbuf(cout, argv[1], argv[2], argv[4]);
           ostream out(&decryptbuf);
           ifstream in(argv[3]);

           out << in.rdbuf();
       }
       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_4.08.02-x.dsc: detached signature;

       o      bobcat_4.08.02-x.tar.gz: source archive;

       o      bobcat_4.08.02-x_i386.changes: change log;

       o      libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.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).