.TH "FBB::DigestBuf" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Compute Message Digests"

.PP 
.SH "NAME"
FBB::DigestBuf \- Computes Message Digests from information inserted into a
std::ostream
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/digestbuf>\fP
.br 
Linking option: \fI\-lbobcat \-lcrypto\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::DigestBuf\fP objects are \fBstd::streambuf\fP objects that can be used
to initialize \fIstd::ostream\fP objects with\&.
.PP 
The message digest of all information inserted into such an
\fIstd::ostream\fP is computed\&.
.PP 
All the message digests defined by the OpenSSL library that can be
selected by name may be used in combination with \fIDigestBuf\fP objects\&.
.PP 
The currently supported message digest algorithms are shown by the
\fIopenssl list \-digest\-commands\fP\&. The names of the digest algorithms can be
used to select a digest algorithms for the class\(cq\&s constructor, below\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fBstd::streambuf\fP
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBDigestBuf(char const *digestName, size_t bufsize = 1024)\fP:
.br 
This constructor initializes the streambuf, setting it up for the
message digest algorithm specified with \fItype\fP\&. The message digest
algorithms specified in the \fBDESCRIPTION\fP section may be used here\&. E\&.g\&., to
use the sha256 algorithm specify \fI\(dq\&sha256\(dq\&\fP\&.
.IP 
The \fIbufsize\fP argument specifies the size of the internal buffer used by
\fIDigestBuf\fP to store incoming characters temporarily\&. The provided default
argument should be OK in all normal cases\&.

.PP 
The copy and move constructors and assignment operators are not
available\&.
.PP 
.SH "OVERLOADED OPERATOR"

.PP 
.IP o 
\fBstd::ostream &operator<<(std::ostream &out,
DigestBuf const &digestbuf)\fP:
.br 
The insertion operator is a free function defined in the namespace
\fIFBB\fP\&. It inserts a hash value as a series of hexadecimally displayed values
into the provided \fIostream\fP\&. See the example below for an illustration\&.

.PP 
.SH "MEMBER FUNCTIONS"

.PP 
All members of \fBstd::streambuf\fP are available, as \fBFBB::DigestBuf\fP
inherits from this class\&.
.PP 
.IP o 
\fBvoid eoi()\fP:
.br 
This member finishes the computation of the  message digest
computation\&. It is needed as the \fIDigestBuf\fP 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
digest is therefore:
.nf 

    1\&. create a DigestBuf object
    2\&. use it to create a std::ostream object
    3\&. insert information into the ostream object
    4\&. call the DigestBuf object\(cq\&s eoi() member or insert the
        eoi manipulator into the ostream (see below)
    5\&. obtain/process the hash value from the DigestBuf object\&.
        
.fi 

.IP 
.IP o 
\fBstd::string const &hash() const\fP:
.br 
This member returns the hash value computed by the \fIDigestBuf\fP
object\&. Its value is only defined after having called \fIclose()\fP\&. The hash
value is returned in a \fIstd::string\fP object\&. This string\(cq\&s \fIlength()\fP
member contains the number of characters used by the hash value, and its
\fIdata()\fP member refers to the hash value\(cq\&s characters\&. Note that a hash
value\(cq\&s character value may be 0 (not to be confused with \fI\(cq\&0\(cq\&\fP)\&.
.IP 
.IP o 
\fBvoid reset()\fP:
.br 
This member reinitializes the message digest computation\&. One a
message digest has been computed for, say a stream \fIstreamA\fP this member can
be called after which the digest for a stream \fIstreamB\fP can be computed
using the same \fIDigestBuf\fP object\&.

.PP 
.SH "MANIPULATOR"
.IP o 
\fBFBB::eoi\fP:
.br 
The \fIeoi\fP manipulator can be inserted into the \fIostream\fP to
complete the digest\&. It performs the same actions as the \fIeoi\fP member\&. If
inserted into a plain \fIstd::ostream\fP nothing happens\&.

.PP 
.SH "EXAMPLE"
.nf 
#include <iostream>
#include <ostream>
#include <bobcat/digestbuf>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
try
{
    DigestBuf digestbuf(argc == 1 ? \(dq\&sha256\(dq\& : argv[1]);
    ostream out(&digestbuf);

    string hw(\(dq\&hello world\en\(dq\&);

    out << hw << eoi;
    cout << \(dq\&>\(dq\& << digestbuf << \(dq\&<\(dq\& << endl;

    digestbuf\&.reset();
    out\&.write(hw\&.c_str(), hw\&.length()) << eoi;
    cout << \(dq\&>\(dq\& << digestbuf << \(dq\&<\(dq\& << endl;
}
catch(exception const &err)
{
    cout << err\&.what() << endl;
    return 1;
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/digestbuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBhmacbuf\fP(3bobcat), \fBstd::streambuf\fP
.PP 
.SH "BUGS"
None reported
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP