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

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

       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

       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 message
              encrypt algorithm specified with type. The encryption algorithms that can  be  used
              are  listed  in  the  table  found in the DESCRIPTION section. 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  at  the time encryption starts it will be
              filled by the EncryptBuf object with random data. When the key and/or the iv is too
              small  for the requested method they will be expanded by adding the required number
              of zero valued bytes.

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

       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      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  encrypted.  When  called  after
              encryption has started an FBB::Exception exception will be thrown.

       o      void setKey(std::string const &key, size_t numberOfBytes = 0):
              This  member  can be used to specify the key and its length after construction time
              but before any data has been encrypted. When called after encryption has started an
              FBB::Exception  exception  will be thrown. The size of the key is assumed to be the
              number of bytes in the key’s data. If another key length  is  required  the  member
              function’s second parameter can be used to specify the length of the key in bytes.

       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 <fstream>
       #include <bobcat/exception>
       #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 Exception(1) <<
                           "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(exception const &err)
       {
           cout << 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/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, "");

FILES

       bobcat/encryptbuf - defines the class interface

SEE ALSO

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

BUGS

       None reported

DISTRIBUTION FILES

       o      bobcat_4.08.06-x.dsc: detached signature;

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

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

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

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