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.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.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).