1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::HMacBuf)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(Compute HMAC Message Digests)
manpagename(FBB::HMacBuf)
(Computes HMAC Message Digests from information inserted into a
std::ostream)
manpagesynopsis()
bf(#include <bobcat/hmacbuf>)nl()
Linking option: tt( -lbobcat -lcrypto)
manpagedescription()
bf(FBB::HMacBuf) objects are bf(std::streambuf) objects that can be used
to initialize tt(std::ostream) objects with.
All information inserted into such a tt(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
tt(HMacBuf) objects.
For the currently supported message digest algorithms issue the command
verb(
openssl list -digest-commands
)
For the currently supported message cipher algorithms issue the command
verb(
openssl list -cipher-commands
)
The defaults used by tt(HMacBuf) constructors are the tt(sha256) digest
algorithm and the tt(aes-128-cbc) cipher algorithm.
includefile(include/namespace)
manpagesection(INHERITS FROM)
bf(std::streambuf)
manpagesection(CONSTRUCTORS)
itemization(
itb(HMacBuf())
The default constructor defines a tt(HmacBuf) object. It can be
used once a non-default constructed tt(HMacBuf) object has been
move-assigned to it;
itb(HMacBuf(HMacBuf &&tmp))
The move constructor initialized a tt(HmacBuf) object by moving
tt(tmp) into the current tt(HMacBuf) object;
itb(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 tt(digest). E.g., to
use the sha256 algorithm specify tt("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 tt(bufsize) argument specifies the size (in bytes) of the internal
buffer used by tt(HMacBuf) to store incoming characters temporarily. A
value of 1024 should be OK for all normal cases;
itb(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.
)
manpagesection(OVERLOADED OPERATOR)
itemization(
itb(HMacBuf &operator=(HMacBuf &&rhs))
The move assignment operator moves the tt(rhs HMacBuf) object into the
current object;
itb(std::ostream &operator<<(std::ostream &out,
HMacBuf const &hmacbuf))
The insertion operator is a free function defined in the namespace
tt(FBB). It inserts a hash value as a series of hexadecimally
displayed values into the provided tt(ostream). See the example below
for an illustration.
)
manpagesection(MEMBER FUNCTIONS)
All members of bf(std::streambuf) are available, as bf(FBB::HMacBuf)
inherits from this class.
itemization(
itb(std::string const &hash() const)
This member returns the hash value computed by the tt(HMacBuf)
object. Its value is only defined after having called tt(close()). The
hash value is returned in a tt(std::string) object. This string's
tt(length()) member contains the number of characters used by the hash
value, and its tt(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 tt('0')).
When called from a default constructed tt(HMacBuf) object an empty
string is returned;
itb(void reset())
This member reinitializes the message hmac computation. One a message
hmac has been computed for, say a stream tt(streamA) this member can
be called after which the hmac for a stream tt(streamB) can be
computed using the same tt(HMacBuf) object.
No action is performed When called from a default constructed
tt(HMacBuf) object;
itb(void eoi())
This member can be called to complete the message digest
computation. Instead of calling this member the tt(eoi) manipulator
(see below) can be used.
)
manpagesection(MANIPULATOR)
itemization(
itb(FBB::eoi)
The tt(eoi) manipulator can be inserted into the tt(ostream) to
complete the digest computation. If it is inserted into a plain
tt(std::ostream) nothing happens.
tt(eoi) can also be called as a function, receiving the stream that
uses the tt(HMacBuf) as its tt(streambuf), but it must be called
either way as the tt(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:
verb(
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.
)
)
manpagesection(EXAMPLE)
verbinclude(../../hmacbuf/driver/driver.cc)
manpagefiles()
em(bobcat/hmacbuf) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(digestbuf)(3bobcat), bf(std::streambuf)
manpagebugs()
None reported
includefile(include/trailer)
|
