--- name: "hmacbuf" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/hmacbuf" --- # hmacbuf(3bobcat) Computes HMAC Message Digests from information inserted into a std::ostream ## NAME FBB::HMacBuf - Computes HMAC Message Digests from information inserted into a std::ostream ## SYNOPSIS **#include \**\ 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 #include #include 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)](/bobcat/7.md), [**digestbuf**(3bobcat)](/digestbuf/3bobcat.md), **std::streambuf** ## BUGS None reported ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## 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**).