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.
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;
All members of std::streambuf are available, as FBB::HMacBuf inherits from this class.
When called from a default constructed HMacBuf object an empty string is returned;
No action is performed When called from a default constructed HMacBuf object;
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.
#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;
}