includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::ISymCryptStream)(3bobcat)(_CurYrs_)
(libbobcat-dev__CurVers_)  
                    (Symmetric en- and decryption)

manpagename(FBB::ISymCryptStream)(Istream performing symmetric encryption)

manpagesynopsis()
    bf(#include <bobcat/isymcryptstream>)nl()
    Linking option: tt(-lbobcat -lcrypto) 

manpagedescription()
    bf(FBB::ISymCryptStream) objects may be used to encrypt or decrypt
information that is available on a separate tt(std::istream).

     The tt(class ISymCryptStream) is a class template, using a
tt(FBB::CryptType) template non-type parameter. Objects of the class 
tt(FBB::ISymCryptStream<FBB::ENCRYPT>) encrypt the information they receive,
objects of the class tt(FBB::ISymCryptStream<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 in combination with tt(EncryptBuf) objects. To
select a particular encryption method an identifier is passed to the
constructor. E.g., tt("aes-128-cbc") indicating the AES (Rijndael) method,
using 128 bit sized keys and blocks using `cbc' mode (see below for an
explanation).

    Refer to the bf(isymcryptstreambuf)(3bobcat) man-page for a description of
available encryption methods.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(FBB::ISymCryptStreambuf) (private), nl()
    bf(std::istream) 
    

manpagesection(CONSTRUCTOR)
    itemization(
    itb(ISymCryptStream<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 a tt(std::istream) providing it with an
tt(FBB::ISymCryptStreambuf) stream buffer. The tt(ISymCryptStreambuf)'s
constructor receives all arguments that are passed to this constructor.

    - tt(ISymCryptStream<ENCRYPT>) objects perform encryption;nl()
        tt(ISymCryptStream<DECRYPT>) objects perform decryption;nl()
    - tt(ISymCryptStream<CryptType>) objects obtain the bytes to encrypt
or decrypt from tt(std::istream &in);nl()
    - The encryption method to use is specified by the tt(type)
parameter. E.g., tt("bf-cbc") selects the Blowfish Cipher Block Chaining
method;nl()
    - The symmetric key to use is specified by the tt(key) parameter;nl()
    - The initialization vector is specified by the tt(iv) parameter;nl()
    - The tt(FBB::ISymCryptStreambuf) internally used buffer will contain
tt(bufSize) characters. The default value is the smallest value that is
used. When a smaller tt(bufSize) value is specified, the default value is
used;nl()
    - The internally used tt(IFilterBuf) is initialized with a buffer of
size tt(filterBufSize), using a lower bound of 100;nl()
    - The parameter tt(ENGINE) can be used to specify a hardware
acceleration engine, as supported by the used encryption/decryption
method. Its default argument value indicates that no hardware acceleration is
available.
    )

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

manpagesection(INHERITED MEMBERS)

    Since the class uses public derivation from bf(std::istream), all members
of this class can be used.

manpagesection(EXAMPLE)
    verbinclude(../../isymcryptstream/driver/driver.cc)

manpagefiles()
    em(bobcat/isymcryptstream) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(isymcryptstreambuf)(3bobcat)

manpagebugs()

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

includefile(include/trailer)


