/usr/share/doc/libbobcat3-dev/man/diffiehellman.3.html is in libbobcat-dev 3.19.01-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 | <html><head>
<title>FBB::DiffieHellman</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::DiffieHellman</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz</h2>
<h2>2005-2013</h2>
<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>
<html><head>
<title>FBB::DiffieHellman(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::DiffieHellman(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz Diffie Hellman key computations</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::DiffieHellman - Diffie-Hellman PKI, computing shared keys
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/diffiehellman></strong><br>
Linking option: <em>-lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
<p>
The class <strong>FBB::DiffieHellman</strong> computes shared keys (shared secrets) using
the Diffie-Hellman (1976) algorithm. The Diffie-Hellman algorithm uses public
and private information. The public information consists of a <em>prime</em> (e.g.,
a prime number consisting of 1024 bits), a <em>generator</em> (for which the value
5 is commonly used), and the value <em>generator<sup>private</sup> mod prime</em>, where
<em>private</em> is a randomly selected large number, which is the private
information.
<p>
The Diffie-Hellman algorithm is commonly used to compute a shared key which
can be used to encrypt information sent between two parties. One party, which
in this man-page is called the <em>initiator</em> computes the prime and defines
the generator. The prime is computed by <strong>FBB::DiffieHellman</strong>'s first
constructor, while the generator is passed to this constructor as one of its
arguments. For the generator the value 5 is often used.
<p>
Next the initiator passes its public information, consisting of the prime, the
generator, and the value <em>generator<sup>private</sup> mod prime</em> to the other
party, which in this man-page is called the <em>peer</em>. The public information
is written in binairy, big-endian form to file using the member <em>save</em>. The
initiator may optionally save the private information to a separate file as
well.
<p>
The peer thereupon receives the initiator's public information. The
initialor's public information is read by a <strong>FBB::DiffieHellman</strong> constructor
either expecting the name of a file or a <em>std::istream</em> containining the
initiator's public information.
<p>
Having obtained the prime and generator, the peer's public (and, optionally,
private information) is saved by also calling <em>save</em>. This results, among
other things, in the value <em>generator<sup>private</sup> mod prime</em>, but now using
the peer's private information.
<p>
At this point the peer is already able to compute the shared key. The key is
returned by calling the <em>key</em> member, which returns the shared key as a
series of bytes stored in a <em>std::string</em>.
<p>
Before the initiator can compute the shared key the peer's
<em>generator<sup>private</sup> mod prime</em> value must be available. The peer sends
the saved public data to the initiator. The initiator then passes the peer's
public data either by file name or by <em>std::istream</em> to the <em>key</em> member,
returning the shared key.
<p>
<strong>Perfect Forward Secrecy and Ephemeral Diffie Hellman</strong>
<p>
If the initiator and peer decide not to save their private information
<em>Perfect Forward Secrecy</em> and <em>Ephemeral Diffie Hellman</em> may be
obtained. Here, the procedure is applied as follows:
<p>
<ul>
<li> Initiator and peer have agreed upon and securely exchanged a
long-lasting common secret, which may be used in combination with, e.g.,
symmetric encryption methods.
<li> Applying the abovementioned procedure, the private information is
never saved on file. Consequently, the shared key, once computed, cannot be
reconstructed anymore.
<li> The value <em>generator<sup>private</sup> mod prime</em> is not sent to either
peer or initiator `in the clear', but encrypted using the long-lasting common
secret. As the current implementation saves all public information on file,
it's probably easiest to encrypt the file containing the public information.
<li> The recipients, having recieved the other party's encrypted public
information, decrypt it using the long-lasting shared secret and compute the
the shared key.
<li> As the secret information is not kept, the shared key cannot be
reconstructed, while a Man-In-The-Middle attack is prevented by only
exchanging encrypted public information.
<li> The shared key can now be used to encrypt a communication session
</ul>
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
-
<p>
<h2>PUBLIC ENUMERATION</h2>
<p>
The enumeration <em>FBB::DiffieHellman::SecretKey</em> has two values:
<ul>
<li> <em>DONT_SAVE_SECRET_KEY</em>, indicating that the secret information
should not be saved on file;
<li> <em>SAVE_SECRET_KEY</em>, indicating that the secret information
should be saved on file;
</ul>
<p>
<h2>CONSTRUCTORS</h2>
<ul>
<li> <strong>DiffieHellman(size_t primeLength = 1024, size_t generator = 5,
bool progress = false)</strong>:<br>
This constructor computes a prime of the specified length, and
initializes the public information with the indicated generator. If
<em>progress</em> is <em>true</em>, the progress of the prime construction process is
shown to <em>std::cout</em> by a series of dots, minuses and plusses. Generating a
suitable prime may fail, resulting in an <em>FBB::Exception</em> being
thrown. Unless the generator is specified as 2 or 5 the warning <em>cannot
check the validity of generator ...</em> is inserted into the
<strong>mstream</strong>(3bobcat)'s <em>wmsg</em> object. A warning is also inserted if the
provided generator is not a generator for the computed prime.
<p>
This constructor should be called by the initiator to start the
Diffie-Hellman shared key computation procedure.
<p>
<li> <strong>DiffieHellman(std::string const &initiatorPublicFileName)</strong>:<br>
This constructor should be called by the peer, after having received the
initiator's public info. It makes the initiator's public information available
to the peer, after which the peer's public and private information can be
computed.
<p>
<li> <strong>DiffieHellman(std::stream &initiatorPublicStream)</strong>:<br>
This constructor acts like the previous constructor, expecting a
<em>std::istream</em> rather than a file name. It should be called by the peer,
after having received the initiator's public info. It makes the initiator's
public information available to the peer, after which the peer's public and
private information can be computed.
<p>
<li> <strong>DiffieHellman(std::string const &initiatorPublicFileName, std::string
const &initiatorPrivateFileName)</strong>:<br>
Unless the initiator's <em>DiffieHellman</em> object is still available,
this constructor should again be called by the initiator, to load the
initiator's public and private data.
<p>
<li> <strong>DiffieHellman(std::stream &initiatorPublicStream, std::stream
&initiatorPrivateStream)</strong>:<br>
This constructor acts like the previous constructor, expecting
<em>std::istreams</em> rather than file names. It should be called by the
initiator, to load the initiator's public and private info.
</ul>
Copy and move constructors are available.
<p>
<h2>OVERLOADED OPERATORS</h2>
Copy and move assignment operators are available.
<p>
<h2>MEMBER FUNCTIONS</h2>
<ul>
<li> <strong>std::string key() const</strong>:<br>
This member should be called by the peer. It returns the shared key. If
the key cannot be computed, or if the key is not resistant to the small group
attack (i.e., if the key equals 1, or is at least equal to the public prime
value, or if <em>key<sup>(prime - 1) / 2</sup> mod prime != 1</em>), then an
<em>FBB::Exception</em> is thrown.
<p>
<li> <strong>std::string key(std::string const &peerPublicFileName) const</strong>:<br>
This member should be called by the initiator. It skips the data referring
to the prime and generator found in <em>peerPublicFileName</em> and then reads the
peer's <em>generator<sup>private</sup> mod prime</em> value. If this value cannot be
read or if the key is not resistant to the small group attack (cf. the
description of the previous <em>key</em> member) then an <em>FBB::Exception</em> is
thrown. It returns the shared key.
<p>
<li> <strong>std::string key(std::istream const &peerPublicStream) const</strong>:<br>
This member should be called by the initiator. It acts like the previous
<em>key</em> member, reading the peer's <em>generator<sup>private</sup> mod prime</em> value
from <em>peerPublicStream</em>. It returns the shared key.
<p>
<li> <strong>void save(std::string const &basename, SecretKey action =
DONT_SAVE_SECRET_KEY)</strong>:<br>
This member should be called by the initiator. It saves the public
information on the file <em>'basename'.pub</em>. The information is written in
binary, big-endian format, using the following organization:
<p>
- the size of the prime in bytes;<br>
- the prime's bytes;<br>
- the size of the generator in bytes;<br>
- the generator's bytes;<br>
- the size of the public info (<em>generator<sup>private</sup> mod prime</em>) in
bytes;<br>
- the public info's bytes.<br>
<p>
If <em>action</em> is specified as <em>SAVE_SECRET_KEY</em> then the private
information is written in binary, big-endian format, using the following
organization:
<p>
- the size of the private information in bytes;<br>
- the private information bytes.
</ul>
<p>
<h2>EXAMPLE</h2>
<p>
When called without arguments, the example program generates
Diffie-Hellman parameters writing the initiator's public and private
information to, respectively, <em>init.pub</em> and <em>init.sec</em>.
<p>
When called with one argument, <em>init.pub</em> is read, and the peer's public
and private information is written to, respectively, <em>peer.pub</em> and
<em>peer.sec</em>. Next, the (peer's) shared key is written to <em>peerkey</em>.
<p>
When called with two arguments, <em>init.pub</em> and <em>init.sec</em> are read,
as well as the peer's public information (on the file <em>peer.pub</em>). Next, the
(initiator's) shared key is written to <em>initkey</em>.
<p>
The files <em>peerkey</em> and <em>initkey</em> should be identical.
<p>
<pre>
#include <fstream>
#include <iostream>
#include <bobcat/diffiehellman>
using namespace FBB;
using namespace std;
int main(int argc, char **argv)
try
{
if (argc == 1)
{
DiffieHellman dh(1024, 5, true);
dh.save("init", DiffieHellman::SAVE_SECRET_KEY);
}
if (argc == 2)
{
DiffieHellman dh("init.pub");
dh.save("peer", DiffieHellman::SAVE_SECRET_KEY);
string key = dh.key();
cout << "Key length: " << key.length() << '\n';
ofstream outkey("peerkey");
outkey.write(key.data(), key.length());
}
if (argc == 3)
{
DiffieHellman dh("init.pub", "init.sec");
string key = dh.key("peer.pub");
cout << "Key length: " << key.length() << '\n';
ofstream outkey("initkey");
outkey.write(key.data(), key.length());
}
}
catch (std::exception const &exc)
{
std::cout << exc.what() << '\n';
}
</pre>
<p>
<h2>FILES</h2>
<em>bobcat/diffiehellman</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>bigint</strong>(3bobcat)
<p>
<h2>BUGS</h2>
None Reported.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_3.19.01-x.dsc</em>: detached signature;
<li> <em>bobcat_3.19.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_3.19.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_3.19.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_3.19.01-x_*.deb</em>: debian package holding the
libraries, headers and manual pages;
<li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
</ul>
<p>
<h2>BOBCAT</h2>
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
This is free software, distributed under the terms of the
GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
|