NAME

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

SYNOPSIS

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

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/errno>
       #include <bobcat/hmacbuf>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           if (argc < 3)
               throw Errno(1, "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(Errno const &err)
       {
           cout << err.why() << endl;
           return 1;
       }

FILES

       bobcat/hmacbuf - defines the class interface

SEE ALSO

       bobcat(7), digestbuf(3bobcat), std::streambuf

BUGS

       None reported

DISTRIBUTION FILES

       o      bobcat_3.19.01-x.dsc: detached signature;

       o      bobcat_3.19.01-x.tar.gz: source archive;

       o      bobcat_3.19.01-x_i386.changes: change log;

       o      libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.19.01-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).