NAME

       FBB::ISymCryptStreambuf - Streambuf performing symmetric en/decryption

SYNOPSIS

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

DESCRIPTION

       FBB::ISymCryptStreambuf  objects  can  be  used  as std::streambuf objects of std::istream
       objected, and  encrypt  or  decrypt  information  that  is  made  available  via  separate
       std::istream streams.

       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.

       All symmetric encryption methods defined by the OpenSSL library that can  be  selected  by
       name  may  be  used to en/decrypt information. To select a particular encryption method an
       identifier is passed to the constructor. E.g.,  "aes-256-gcm".  For  an  overview  of  the
       currently supported cipher algorithms issue the command

           openssl list -cipher-algorithms

       ISymCryptStreambuf  objects  read the information to en/decrypt from std::istream objects,
       which are at construction-time  specified  as  istream  references  or  by  filename.  The
       characters  that  are  thereupon  extracted  or  read  from  ISymCryptStream  objects  are
       en/decrypted, and could, e.g., be written to some output stream.

NAMESPACE

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

INHERITS FROM

       FBB::ISymCryptBase (public)

       The class FBB::ISymCryptBase is an `internal use only’ class, derived from std::streambuf,
       and therefore ISymCryptStreambuf is a std::streambuf class.

CONSTRUCTORS

       o      ISymCryptStreambuf<CryptType>(std::istream     &inStream,     std::string     const
              &cipherName,  std::string  const  &key,  std::string  const &iv, size_t inBufSize =
              100):
              This constructor defines a  std::streambuf  object  encrypting  or  decrypting  the
              characters which are read from inStream.

              - ISymCryptStreambuf<FBB::ENCRYPT> objects perform encryption;
              ISymCryptStreambuf<FBB::DECRYPT> objects perform decryption;

              -  ISymCryptStreambuf<CryptType>  objects  receive  the  characters  to  encrypt or
              decrypt from std::istream &in;
              - The encryption method to use is specified  by  the  cipherName  parameter.  E.g.,
              "AES-256-GCM";
              - The symmetric key to use is specified by the key parameter;
              - The initialization vector is specified by the iv parameter;
              -  The  FBB::ISymCryptStreambufbuf  internally  used  buffer  will  hold  inBufSize
              characters. The default value is the smallest value that is used. When specifying a
              smaller bufSize value than the default value then the default value is used;

       o      ISymCryptStreambuf<CryptType>(std::string  const  &inStreamName,  std::string const
              &cipherName, std::string const &key, std::string  const  &iv,  size_t  inBufSize  =
              100):
              Same  constructor  as  the  previous  one,  but  this constructor’s first parameter
              specifies the name of the file containing the characters to encrypt or decrypt.

       If the construction fails an exception is thrown, mentioning  the  openssl  function  that
       failed to complete (see also errorMsg below).

       The  move  constructor is available, the copy constructor and assignment operators are not
       available,

INHERITED MEMBERS

       Since the class is publicly derived from std::istreambuf, all std::streambuf  members  can
       can be used.

MEMBER FUNCTIONS

       o      static std::string errorMsg():
              If  an  openssl  function  fails  an exception is thrown mentioning the name of the
              failing function. In those cases the function errorMsg can be  called  returning  a
              std::string  containing  the openssl error code (returned by ERR_get_error) and its
              textual representation (returned by ERR_error_string). If the reported  error  code
              is  zero,  then  in  fact  no  error  has occurred and the exception was spuriously
              reported;

       o      static size_t keyLength(std::string const &cipherName):
              returns the minimum key length required for cipher cipherName;

       o      static size_t ivLength(std::sting const &cipherName):
              returns the minimum length of the initialization vector that is required for cipher
              cipherName.

       The  latter  two  functions  throw exceptions if cipherName does not contain the name of a
       supported cipher algorithm.

EXAMPLE

       See  the  example  in  the  isymcryptstream(3bobcat)  man-page.  Instead  of  defining  an
       ISymCryptStream   an   ISymCryptStreamBuf  can  be  defined,  passing  its  address  to  a
       std::istream which can then be used as the ISymCryptStream used in the example.

FILES

       bobcat/isymcryptstream - defines the class interface

SEE ALSO

       bobcat(7), isymcryptstream(3bobcat), osymcryptstream(3bobcat), osymcryptstreambuf(3bobcat)

BUGS

       None Reported.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb: debian package containing  the  libraries,  headers
              and manual pages;

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