Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64 bug

NAME

       FBB::ISymCryptStreambuf - Input Filtering stream buffer doing symmetric encryption

SYNOPSIS

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

DESCRIPTION

       The information made available by ISymCryptStreambuf objects has been subject to symmetric
       encryption or decryption. The information to be encrypted or decrypted is  made  available
       to ISymCryptStreambuf object via std::istream objects.

       The class ISymCryptStreambuf is a class template, using a FBB::CryptType template non-type
       parameter.  Objects  of  the  class  FBB::ISymCryptStreambuf<FBB::ENCRYPT>   encrypt   the
       information  they  receive,  objects  of  the  class FBB::ISymCryptStreambuf<FBB::DECRYPT>
       decrypt the information they receive. See also section ENUMERATION below.

       All symmetric 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. The initialization vector must be provided at
       construction time. The matching decrypting object needs to know the initialization  vector
       that  was  used  when  encrypting  the data: the application must ensure that the matching
       decryption object receives the same initialization vector as the one that was provided  to
       the encryption object. 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:

       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::IFilterStreambuf

MEMBER FUNCTIONS

       All  members  of  FBB::IFilterStreambuf are available, as ISymCryptStreambuf inherits from
       this class.

       Overloaded move and/or copy assignment operators are not available.

ENUMERATION

       ISymCryptStreambuf objects  either  encrypt  or  decrypt  information.  ISymCryptStreambuf
       objects  of the class FBB::ISymCryptStreambuf<FBB::ENCRYPT> encrypt the data they receive,
       ISymCryptStreambuf objects of the class FBB::ISymCryptStreambuf<FBB::DECRYPT> decrypt  the
       data they receive.

       The  values ENCRYPT and DECRYPT are defined in the enum CryptType, which is defined in the
       FBB namespace.

CONSTRUCTOR

       o      ISymCryptStreambuf<CryptType>(   std::istream   &in,          char   const   *type,
              std::string  const  &key,   std::string  const &iv, size_t bufSize = 100,    size_t
              filterBufSize = 1000, ENGINE *engine = 0):
              This constructor initializes the streambuf.  - ISymCryptStreambuf<ENCRYPT>  objects
              perform encryption;
              ISymCryptStreambuf<DECRYPT> objects perform decryption;
              - ISymCryptStreambuf<CryptType> objects obtain the bytes to encrypt or decrypt from
              std::istream &in;
              - The encryption method to use is specified by the type parameter.  E.g.,  "bf-cbc"
              selects the Blowfish Cipher Block Chaining method;
              - The symmetric key to use is specified by the key parameter;
              - The initialization vector is specified by the iv parameter;
              -   The   FBB::ISymCryptStreambuf  internally  used  buffer  will  contain  bufSize
              characters. The default value is the smallest value that is used.  When  a  smaller
              bufSize value is specified, the default value is used;
              -  FBB::ISymCryptStreambuf’s  IFilterStreambuf  base  class  is  initialized with a
              buffer of size filterBufSize, using a lower bound of 100;
              - The parameter ENGINE can be used to specify a hardware accelleration  engine,  as
              supported  by  the  used  encryption/decryption  method. Its default argument value
              indicates that no hardware accelleration is available.  Copy- and move constructors
              are not available.

EXAMPLE

       The  example shows the construction of an ISymCryptStreambuf<ENCRYPT> object ebuf which is
       used to initialize a std::istream object.  The  information  read  from  this  istream  is
       encrypted  using the Blowfish CBC method. A ISymCryptStreambuf<DECRYPT> object (dbuf reads
       the information from that stream and decrypts it again. The  std::istream  din  object  is
       initialized  with  the  ISymCryptStreambuf<DECRYPT>  object,  and  its contents is sent to
       std::cout. The information that is presented at std::cin and  that  appears  at  std::cout
       should be identical.

       #include <iostream>

       #include <bobcat/isymcryptstreambuf>

       using namespace std;
       using namespace FBB;

       int main()
       {
           ISymCryptStreambuf<ENCRYPT> ebuf(cin, "bf-cbc",
                                           "1234567890", "1234567890");
           istream ein(&ebuf);

           ISymCryptStreambuf<DECRYPT> dbuf(ein, "bf-cbc",
                                           "1234567890", "1234567890");
           istream din(&dbuf);

           cout << din.rdbuf();
       }

FILES

       bobcat/isymcryptstreambuf - defines the class interface

SEE ALSO

       bobcat(7),   encryptbuf(3bobcat),   isymcryptstream(3bobcat),   ibase64streambuf(3bobcat),
       ifilterstreambuf(3bobcat), ofilterstreambuf(3bobcat), std::streambuf.

BUGS

       Sep/Oct  2013:  due   to   a   change   in   library   handling   by   the   linker   (cf.
       http://fedoraproject.org/wiki/UnderstandingDSOLinkChange                               and
       https://wiki.debian.org/ToolChain/DSOLinking) libraries that are indirectly  required  are
       no  longer  automatically  linked  to  your  program. With BigInt this is libcrypto, which
       requires programs to link to both bobcat and crypto.

DISTRIBUTION FILES

       o      bobcat_3.19.01-x.dsc: detached signature;

       o      bobcat_3.19.01-x.tar.gz: source archive;

       o      bobcat_3.19.01-x_i386.changes: change log;

       o      libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.19.01-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).