Provided by: libbobcat-dev_6.03.02-2_amd64 
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.
All the message digest and cipher algorithms defined by the OpenSSL library that can be
selected by name, may be used in combination with HMacBuf objects.
For the currently supported message digest algorithms issue the command
openssl list -digest-commands
For the currently supported message cipher algorithms issue the command
openssl list -cipher-commands
The defaults used by HMacBuf constructors are the sha256 digest algorithm and the
aes-128-cbc cipher 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():
The default constructor defines a HmacBuf object. It can be used once a non-default
constructed HMacBuf object has been move-assigned to it;
o HMacBuf(HMacBuf &&tmp):
The move constructor initialized a HmacBuf object by moving tmp into the current
HMacBuf object;
o HMacBuf(std::string const &key, char const *digest, size_t bufsize):
This constructor initializes the streambuf, setting it up for the message digest
algorithm specified with digest. 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 key’s length must be 16 characters. An exception is thrown if
an empty key is specified.
The bufsize argument specifies the size (in bytes) of the internal buffer used by
HMacBuf to store incoming characters temporarily. A value of 1024 should be OK for
all normal cases;
o HMacBuf(std::string const &key, char const *cipher = "aes-128-cbc", char const
*digest = "sha256", size_t bufsize = 1024):
Like the previous constructor, but this one offers defaults for the cipher and
digest algorithms and buffer size. When specifying another cipher algorithm the key
length must match the cipher requirement. Usually the cipher’s name contains a
number (like 128), which can be divided by 8 to obtain the required key length of
fixed-key length ciphers.
OVERLOADED OPERATOR
o HMacBuf &operator=(HMacBuf &&rhs):
The move assignment operator moves the rhs HMacBuf object into the current object;
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.
MEMBER FUNCTIONS
All members of std::streambuf are available, as FBB::HMacBuf inherits from this class.
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’).
When called from a default constructed HMacBuf object an empty string is returned;
o void reset():
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.
No action is performed When called from a default constructed HMacBuf object;
o void eoi():
This member can be called to complete the message digest computation. Instead of
calling this member the eoi manipulator (see below) can be used.
MANIPULATOR
o FBB::eoi:
The eoi manipulator can be inserted into the ostream to complete the digest
computation. If it is inserted into a plain std::ostream nothing happens.
eoi can also be called as a function, receiving the stream that uses the HMacBuf as
its streambuf, but it must be called either way as the HMacBuf object itself cannot
decide whether all information to compute the digest for has yet been received or
not. The general approach for computing a message hmac is therefore:
1. create a HMacBuf object
2. use it to create a std::ostream object
3. insert information into the ostream object
4. call the HMacBuf object’s eoi() member or insert eoi into the ostream
object
5. obtain/process the hash value from the HMacBuf object.
EXAMPLE
#include <fstream>
#include <iostream>
#include <bobcat/hmacbuf>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
try
{
// using the default (sha256) digest algorithm
if (argc == 1)
throw Exception{} <<
"Usage: arg1: 16-byte key, arg2: file to process,\n"
" arg3 (opt) buf size (default 1024)";
HMacBuf hmacbuf{ argv[1], "aes-128-cbc", "sha256",
argc == 3 ? 1024 : stoul(argv[3]) };
HMacBuf empty; // Demo: an empty HMacBuf
empty = HMacBuf{ argv[1], "sha256", 100 }; // Demo: move assignmeent
ostream out(&hmacbuf); // the ostream receiving the
// input to compute the hmac of
ifstream in{ argv[2] }; // the file to process
out << in.rdbuf() << eoi; // compute the hmac
// and show the hmac value
cout << " computed hmac value: >" << hmacbuf << "<\n";
in.seekg(0); // to illustrate ’reset’: do it
hmacbuf.reset(); // again
out << in.rdbuf();
eoi(out); // calling eoi as a function
cout << "recomputed hmac value: >" << hmacbuf << "<\n";
}
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
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.03.02-x.dsc: detached signature;
o bobcat_6.03.02-x.tar.gz: source archive;
o bobcat_6.03.02-x_i386.changes: change log;
o libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.03.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).