includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::HMacBuf)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Compute HMAC Message Digests)

manpagename(FBB::HMacBuf)
           (Computes HMAC Message Digests from information inserted into a
std::ostream)

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

manpagedescription()
    bf(FBB::HMacBuf) 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 used to compute a
message HMAC.

    All the message digest and cipher algorithms defined by the OpenSSL
library that can be selected by name, may be used in combination with
tt(HMacBuf) objects.

    For the currently supported  message digest algorithms issue the command
        verb(
    openssl list -digest-commands
        )
    For the currently supported  message cipher algorithms issue the command
        verb(
    openssl list -cipher-commands
        )
    The defaults used by tt(HMacBuf) constructors are the tt(sha256) digest
algorithm and the tt(aes-128-cbc) cipher algorithm.

includefile(include/namespace)

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

manpagesection(CONSTRUCTORS)
    itemization(
    itb(HMacBuf())
       The default constructor defines a tt(HmacBuf) object. It can be
        used once a non-default constructed tt(HMacBuf) object has been
        move-assigned to it;

    itb(HMacBuf(HMacBuf &&tmp))
       The move constructor initialized a tt(HmacBuf) object by moving
        tt(tmp) into the current tt(HMacBuf) object;

    itb(HMacBuf(std::string const &key, char const *digest, size_t bufsize))
       This constructor initializes the streambuf, setting it up for the
        message digest algorithm specified with tt(digest). E.g., to
        use the sha256 algorithm specify tt("sha256").

       The constructor's first argument defines the key to be used when
        computing the HMAC message digest. The key's length must be 16
        characters. An exception is thrown if an empty key is specified.

       The tt(bufsize) argument specifies the size (in bytes) of the internal
        buffer used by tt(HMacBuf) to store incoming characters temporarily. A
        value of 1024 should be OK for all normal cases;

    itb(HMacBuf(std::string const &key, char const *cipher = "aes-128-cbc",
                char const *digest = "sha256", size_t bufsize = 1024))
       Like the previous constructor, but this one offers defaults for the
        cipher and digest algorithms and buffer size. When specifying another
        cipher algorithm the key length must match the cipher
        requirement. Usually the cipher's name contains a number (like 128),
        which can be divided by 8 to obtain the required key length of
        fixed-key length ciphers.
    )


manpagesection(OVERLOADED OPERATOR)

    itemization(
    itb(HMacBuf &operator=(HMacBuf &&rhs))
       The move assignment operator moves the tt(rhs HMacBuf) object into the
        current object;

    itb(std::ostream &operator<<(std::ostream &out,
                                 HMacBuf const &hmacbuf))
       The insertion operator is a free function defined in the namespace
        tt(FBB). It inserts a hash value as a series of hexadecimally
        displayed values into the provided tt(ostream). See the example below
        for an illustration.
    )

manpagesection(MEMBER FUNCTIONS)

     All members of bf(std::streambuf) are available, as bf(FBB::HMacBuf)
inherits from this class.

    itemization(
    itb(std::string const &hash() const)
       This member returns the hash value computed by the tt(HMacBuf)
        object. Its value is only defined after having called tt(close()). The
        hash value is returned in a tt(std::string) object. This string's
        tt(length()) member contains the number of characters used by the hash
        value, and its tt(data()) member refers to the hash value's
        characters. Note that a hash value's character value may be 0 (not to
        be confused with tt('0')).

       When called from a default constructed tt(HMacBuf) object an empty
        string is returned;

    itb(void reset())
       This member reinitializes the message hmac computation. One a message
        hmac has been computed for, say a stream tt(streamA) this member can
        be called after which the hmac for a stream tt(streamB) can be
        computed using the same tt(HMacBuf) object.

       No action is performed When called from a default constructed
        tt(HMacBuf) object;

    itb(void eoi())
       This member can be called to complete the message digest
        computation. Instead of calling this member the tt(eoi) manipulator
        (see below) can be used.
    )

manpagesection(MANIPULATOR)
    itemization(
    itb(FBB::eoi)
       The tt(eoi) manipulator can be inserted into the tt(ostream) to
        complete the digest computation. If it is inserted into a plain
        tt(std::ostream) nothing happens.
        
       tt(eoi) can also be called as a function, receiving the stream that
        uses the tt(HMacBuf) as its tt(streambuf), but it must be called
        either way as the tt(HMacBuf) object itself cannot decide whether all
        information to compute the digest for has yet been received or
        not. The general approach for computing a message hmac is therefore:
       verb(
    1. create a HMacBuf object
    2. use it to create a std::ostream object
    3. insert information into the ostream object
    4. call the HMacBuf object's eoi() member or insert eoi into the ostream
       object
    5. obtain/process the hash value from the HMacBuf object.
        )
    )

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

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

manpageseealso()
    bf(bobcat)(7), bf(digestbuf)(3bobcat), bf(std::streambuf)

manpagebugs()
    None reported

includefile(include/trailer)
