NAME

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

SYNOPSIS

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

DESCRIPTION

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

       The message digest of all information inserted into such an 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 DigestBuf objects.

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

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 *digestName, 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 size of 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:

                  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.

       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/digestbuf>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           DigestBuf digestbuf(argc == 1 ? "sha256" : 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

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb: debian package containing the libraries, headers and manual pages;

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

libbobcat-dev_6.04.00                               2005-2023                            FBB::DigestBuf(3bobcat)