NAME

       FBB::DigestBuf - Computes Message Digests from information inserted into a std::ostream

SYNOPSIS

       #include <bobcat/digestbuf>
       Linking option: -lbobcat

DESCRIPTION

       FBB::DigestBuf  objects  are  std::streambuf  objects  that  can  be  used  to  initialize
       std::ostream objects with.

       All information inserted into such a std::ostream is used  to  compute  a  message  digest
       from.

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

       The following message digest 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  algorithms  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  openssl/evp.h  lists  all
       available  digest  algorithms  (in  that  file  look  for  EVP_MD  *EVP_: a message digest
       algorithm immediately follows the 2nd underscore. E.g., const EVP_MD *EVP_md4(void)  which
       refers to the md4 message digest algorithm).

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       std::streambuf

CONSTRUCTORS

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

              The  bufsize  argument  specifies  the  internal  buffer used by 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.

OVERLOADED OPERATOR

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

MEMBER FUNCTIONS

       All members of std::streambuf are available, as FBB::DigestBuf inherits from this class.

       o      void eoi():
              This  member  finishes  the  computation  of the  message digest computation. It is
              needed as the 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:

                  create a DigestBuf object
                  use it to create a std::ostream object
                  insert information into the ostream object
                  call the DigestBuf object’s eoi() member or insert the
                      eoi manipulator into the ostream (see below)
                  obtain/process the hash value from the DigestBuf object.

       o      std::string const &hash() const:
              This member returns the hash value computed by the DigestBuf object. Its  value  is
              only  defined  after  having  called  close().  The  hash  value  is  returned in a
              std::string object. This string’s length() member contains the number of characters
              used  by  the  hash  value,  and  its  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 ’0’).

       o      void reset():
              This  member reinitializes the message digest computation. One a message digest has
              been computed for, say a stream streamA this member can be called after  which  the
              digest for a stream streamB can be computed using the same DigestBuf object.

MANIPULATOR

       o      FBB::eoi:
              The  eoi  manipulator  can  be inserted into the ostream to complete the digest. It
              performs the same actions as the eoi member. If inserted into a plain  std::ostream
              nothing happens.

EXAMPLE

       #include <iostream>
       #include <ostream>
       #include <bobcat/exception>
       #include "../digestbuf"

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           DigestBuf digestbuf(argv[1]);
           ostream out(&digestbuf);

           string hw("hello world\n");

           out << hw << eoi;
           cout << ">" << digestbuf << "<" << endl;

           digestbuf.reset();
           out.write(hw.c_str(), hw.length()) << eoi;
           cout << ">" << digestbuf << "<" << endl;
       }
       catch(exception const &err)
       {
           cout << err.what() << endl;
           return 1;
       }

FILES

       bobcat/digestbuf - defines the class interface

SEE ALSO

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

BUGS

       None reported

DISTRIBUTION FILES

       o      bobcat_5.02.00-x.dsc: detached signature;

       o      bobcat_5.02.00-x.tar.gz: source archive;

       o      bobcat_5.02.00-x_i386.changes: change log;

       o      libbobcat1_5.02.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.02.00-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms  of  the  GNU  General  Public  License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).