includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::EncryptBuf)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_-x.tar.gz)
                    (Encrypt information)

manpagename(FBB::EncryptBuf)
           (Encrypts information using various methods into a std::ostream) 

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

manpagedescription()
    bf(FBB::EncryptBuf) objects are bf(std::streambuf) objects that can be used
to initialize tt(std::ostream) objects with.

    All information inserted into such a tt(std::ostream) is encrypted and
written into a tt(std::ostream) that is given as argument to tt(EncryptBuf)'s
constructor.

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

    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 tt('0') characters). 

Most modes use an em(initialization vector). Unless provided at construction
time or explicitly set thereafter an initialization vector containg randomly
selected values will be used. The initialization vector that is actually used
can be obtained from the tt(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 em(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.

includefile(blockciphers)

includefile(symcryptciphers)


includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(std::streambuf)

manpagesection(CONSTRUCTOR)
    itemization(
    itb(EncryptBuf(std::ostream &outStream, char const *type, 
                            std::string const &key, std::string const &iv,
                            size_t bufsize = 1024))
        This constructor initializes the tt(EncryptBuf) object preparing it
for the message encrypt algorithm specified with tt(type). The encryption
algorithms that can be used are listed in the table found in the
bf(DESCRIPTION) section. E.g., to use the AES method on 24 bit keys and
blocks in CBC mode specify tt("aes-192-cbc"). The tt(key) parameter refers to
the key to be used, the tt(iv) parameter refers to the initialization vector
to use. Both tt(key) and tt(iv) may contain non-displayable characters. When
tt(iv.length()) is zero at the time encryption starts it will be filled by the
tt(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 tt(FBB::Exception) exception if an unknown
encryption method was specified.

    The constructor's first parameter refers to the tt(std::ostream) to
receive the encrypted information. Be aware of the fact that the encrypted
information most likely contains non-displayable characters.

    The tt(bufsize) argument specifies the size in bytes of the internal
buffer used by tt(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 tt(std::streambuf)
doesn't support either).

manpagesection(MEMBER FUNCTIONS)

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

    itemization(
    itb(size_t blockLength() const)
        This member returns the block size (in bytes) that are used by
the specified method.
    itb(size_t ivLength() const)
        This member returns the size (in bytes) of the initialization vector
that is used by the specified method.
    itb(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. 
    itb(size_t keyLength() const)
        This member returns the size of the key (in bytes) that are used by
the specified method.
    itb(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.
    itb(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 tt(FBB::Exception) exception will be thrown.
    itb(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 tt(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 em(in bytes).
    itb(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 tt(true). It returns tt(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).
    )

manpagesection(PROTECTED MEMBER)
    itemization(
    itb(EVP_CIPHER_CTX *cipherCtx())
        Classes derived from tt(EncryptBuf) may use this member to gain direct
access to the tt(EVP_CIPHER_CTX) pointer used by the tt(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.
    )
manpagesection(EXAMPLE)
    verbinclude(../../encryptbuf/driver/driver.cc)

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:
        verb(
    #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 tt(Skip256) object is used to define an intermediate
tt(std::ostream) that is then passed to the tt(EncryptBuf) object. E.g., only
showing the essential steps defining the tt(EncryptBuf) object:
        verb(
    Skip256 skip256(std::cout);
    std::ostream out(&skip256);

    EncryptBuf encryptbuf(out, "rc4", key, "");
        )

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

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

manpagebugs()
    None reported

includefile(include/trailer)




