plucky (3) digestbuf.3bobcat.gz

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

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

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

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

       o      libbobcat1-dev_6.06.02-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).