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

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

    The following message hmac algorithms are currently supported: mull, md2,
md5, sha, sha1, sha224, sha256, sha384, sha512, dss, dss1, ecdsa, mdc2,
ripemd160. These very names are the ones to use to select the particular
digest algorithm for the class's constructor, below. It is quite possible that
future releases of the openssl library will support additional message digest
algorithms. The header file tt(openssl/evp.h) lists all available hmac
algorithms (in that file look for tt(EVP_MD *EVP_): a message digest algorithm
immediately follows the 2nd underscore. E.g., tt(const EVP_MD *EVP_md4(void))
which refers to the md4 message digest algorithm).

includefile(include/namespace)

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

manpagesection(CONSTRUCTORS)
    itemization(
    itb(HMacBuf(std::string const &key, char const *type, 
                size_t bufsize = 1024))
        This constructor initializes the streambuf, setting it up for the
message digest algorithm specified with tt(type). The message hmac
algorithms specified in the bf(DESCRIPTION) section may be used here. 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 tt(bufsize) argument specifies the internal buffer used by
tt(HMacBuf) to store incoming characters temporarily. The provided default
argument should be OK in all normal cases. 
    )

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

manpagesection(OVERLOADED OPERATOR)

    itemization(
    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(void eoi())
        This member completes the message digest computation. It is needed as
the tt(HMacBuf) object has no external means for deciding whether all
information to compute the digest for has yet been received or
not. Alternatively, the tt(eoi) manipulator can be inserted into the stream
computing the message digest (see below) The general approach for
computing a message hmac is therefore:
        verb(
    create a HMacBuf object
    use it to create a std::ostream object
    insert information into the ostream object
    call the HMacBuf object's eoi() member or insert eoi into the ostream
    object 
    obtain/process the hash value from the HMacBuf object.
        )

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

    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.

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

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)




