bionic (3) digestbuf.3bobcat.gz

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.08.02-x.dsc: detached signature;

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

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

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

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