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.  There is no copy constructor.

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.  The overloaded assignment
              operator is not available.

MEMBER FUNCTIONS

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

       o      void close():
              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 close() member
                  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 open():
              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.

EXAMPLE

       #include <iostream>
       #include <ostream>
       #include <bobcat/exception>
       #include <bobcat/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;
           digestbuf.close();
           cout << ">" << digestbuf << "<" << endl;

           digestbuf.open();
           out.write(hw.c_str(), hw.length());
           digestbuf.close();
           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_4.01.03-x.dsc: detached signature;

       o      bobcat_4.01.03-x.tar.gz: source archive;

       o      bobcat_4.01.03-x_i386.changes: change log;

       o      libbobcat1_4.01.03-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.01.03-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).