NAME

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

SYNOPSIS

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

DESCRIPTION

       FBB::HMacBuf 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 HMAC from.

       All the message digest algorithms defined by the OpenSSL library that can be selected by name may be used
       in combination with HMacBuf objects.

       The following message hmac 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 algorithm 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 hmac 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      HMacBuf(std::string const &key, 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 hmac algorithms specified in the DESCRIPTION section may be  used
              here. E.g., to use the sha256 algorithm specify "sha256".

              The  constructor’s  first  argument  defines  the  key  to be used when computing the HMAC message
              digest.

              The bufsize argument specifies the internal buffer used by HMacBuf 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, HMacBuf const &hmacbuf):
              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::HMacBuf  inherits  from  this  class.  Some  of  the
       std::streambuf’s  member  are  overridden  or are hidden by HMacBuf. In normal situations these inherited
       members will not be used by programs using HMacBuf objects.

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

                  create a HMacBuf object
                  use it to create a std::ostream object
                  insert information into the ostream object
                  call the HMacBuf object’s close() member
                  obtain/process the hash value from the HMacBuf object.

       o      std::string const &hash() const:
              This member returns the hash value computed by the HMacBuf 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 hmac computation. One a message hmac has been computed for,
              say a stream streamA this member can be called after which the hmac for a stream  streamB  can  be
              computed using the same HMacBuf object.

EXAMPLE

       #include <iostream>
       #include <ostream>
       #include <cstring>
       #include <iomanip>
       #include <bobcat/exception>
       #include <bobcat/hmacbuf>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           if (argc < 3)
               throw Exception(0) << "Arg1: key, arg2: digest method required";

           string key(argv[1]);

           HMacBuf hmacbuf(key, argv[2]);
           ostream out(&hmacbuf);

           string hw("hello world\n");

           out << hw;
           hmacbuf.close();
           cout << ">" << hmacbuf << "<" << endl;

           hmacbuf.open();
           out.write(hw.c_str(), hw.length());
           hmacbuf.close();
           cout << ">" << hmacbuf << "<" << endl;
       }
       catch(exception const &err)
       {
           cout << err.what() << endl;
           return errno;
       }

FILES

       bobcat/hmacbuf - defines the class interface

SEE ALSO

       bobcat(7), digestbuf(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).