includefile(include/header)

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

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

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

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

    The message digest of all information inserted into such an
tt(std::ostream) is computed.

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

    The currently supported message digest algorithms are shown by the
tt(openssl list -digest-commands). The names of the digest algorithms can be
used to select a digest algorithms for the class's constructor, below.

COMMENT(
   The header file tt(openssl/evp.h) lists all available digest 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).
END)

includefile(include/namespace)

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

manpagesection(CONSTRUCTORS)
    itemization(
    itb(DigestBuf(char const *digestName, size_t bufsize = 1024))
        This constructor initializes the streambuf, setting it up for the
message digest algorithm specified with tt(type). The message digest
algorithms specified in the bf(DESCRIPTION) section may be used here. E.g., to
use the sha256 algorithm specify tt("sha256").

    The tt(bufsize) argument specifies the size of the internal buffer used by
tt(DigestBuf) to store incoming characters temporarily. The provided default
argument should be OK in all normal cases.
    )

    The copy and move constructors and assignment operators are not
available.

manpagesection(OVERLOADED OPERATOR)

    itemization(
    itb(std::ostream &operator<<(std::ostream &out,
                                 DigestBuf const &digestbuf))
        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::DigestBuf)
inherits from this class.

    itemization(
    itb(void eoi())
        This member finishes the computation of the  message digest
computation. It is needed as the tt(DigestBuf) object has no external means
for deciding whether all information to compute the digest for has yet been
received or not. The general approach to follow when computing a message
digest is therefore:
        verb(
    1. create a DigestBuf object
    2. use it to create a std::ostream object
    3. insert information into the ostream object
    4. call the DigestBuf object's eoi() member or insert the
        eoi manipulator into the ostream (see below)
    5. obtain/process the hash value from the DigestBuf object.
        )

    itb(std::string const &hash() const)
        This member returns the hash value computed by the tt(DigestBuf)
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 digest computation. One a
message digest has been computed for, say a stream tt(streamA) this member can
be called after which the digest for a stream tt(streamB) can be computed
using the same tt(DigestBuf) object.
    )

manpagesection(MANIPULATOR)
    itemization(
    itb(FBB::eoi)
        The tt(eoi) manipulator can be inserted into the tt(ostream) to
complete the digest. It performs the same actions as the tt(eoi) member. If
inserted into a plain tt(std::ostream) nothing happens.
    )

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

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

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

manpagebugs()
    None reported

includefile(include/trailer)
