FBB::HMacBuf(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

✨ FBB::HMacBuf ✨

okay so bestie, welcome to the manual page for FBB::HMacBuf, straight outta section 3bobcat — the part of the manual where the C++ library pages live. grab a snack, this one's cute 🍓

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, and the whole point of them is that you can use one to initialize a std::ostream object with it. that's the vibe 🌈

everything you insert into such a std::ostream? yeah, all of it gets used to compute a message HMAC. every last byte. no cap.

every message digest and cipher algorithm that the OpenSSL library defines and that can be selected by name is fair game here — you can use any of them in combination with HMacBuf objects. the way that flexibility is just iconic tbh.

wanna see which message digest algorithms are currently supported? run:

openssl list -digest-commands

wanna see which message cipher algorithms are currently supported? run:

openssl list -cipher-commands

and here's the tea on defaults: the defaults used by HMacBuf constructors are the sha256 digest algorithm and the aes-128-cbc cipher algorithm. periodt 💅

NAMESPACE

FBB

all constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB. so bestie, that's where you'll find them 🫶

INHERITS FROM

std::streambuf

CONSTRUCTORS

  • HMacBuf() — the default constructor defines a HmacBuf object. you can use it once a non-default constructed HMacBuf object has been move-assigned to it 🌸
  • HMacBuf(HMacBuf &&tmp) — the move constructor initializes a HmacBuf object by moving tmp into the current HMacBuf object ✨
  • 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. like, to use the sha256 algorithm you specify "sha256". easy 💖

the constructor's first argument defines the key to be used when computing the HMAC message digest. and listen — 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 👑

  • 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 the 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. math girlies stay winning 🧚

OVERLOADED OPERATOR

  • HMacBuf &operator=(HMacBuf &&rhs) — the move assignment operator moves the rhs HMacBuf object into the current object 💫
  • 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. so you're not losing anything, you're gaining 🌈

  • std::string const &hash() const — this member returns the hash value computed by the HMacBuf object. heads up though: 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'). yes, those are different things and it matters 💀

when called from a default constructed HMacBuf object an empty string is returned.

  • void reset() — this member reinitializes the message hmac computation. once 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. reuse era 💅

no action is performed when called from a default constructed HMacBuf object.

  • 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. two paths, same destination, slay ✨

MANIPULATOR

  • 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. literally nothing. it's fine 🙈

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, because the HMacBuf object itself cannot decide whether all information to compute the digest for has yet been received or not. it's not psychic, bestie, you have to tell it 😭

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. we love a clean record 👑

BOBCAT PROJECT FILES

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

bestie, that's one package for running it and one for building against it. both iconic 🫶

BOBCAT

Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’. acronym reveal moment 🤯

this is free software, distributed under the terms of the GNU General Public License (GPL). free as in freedom, fr fr 💖

AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl). thank you for your service 🙏

and that's the whole page, bestie!! this one came out of libbobcat-dev_6.15.01, dated 2005-2026, and yes it's still FBB::HMacBuf(3bobcat) at heart 💅✨ go compute some HMACs, you've got this 🦋

📦 where this page comes from