The class FBB::DiffieHellman 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 prime (e.g., a prime number consisting of 1024 bits), a generator (for which the value 5 is commonly used), and (using ** to represent the power operator on integral values) the value generator ** private mod prime, where private is a randomly selected large number, which is the private information.
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 initiator computes the prime and defines the generator. The prime is computed by FBB::DiffieHellman'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.
Next the initiator passes its public information, consisting of the prime, the generator, and the value generator ** private mod prime) to the other party, which in this man-page is called the peer. The public information is written in binairy, big-endian form to file using the member save. The initiator may optionally save the private information to a separate file as well.
The peer thereupon receives the initiator's public information. The initialor's public information is read by a FBB::DiffieHellman constructor either expecting the name of a file or a std::istream containining the initiator's public information.
Having obtained the prime and generator, the peer's public (and, optionally, private information) is saved by also calling save. This results, among other things, in the value generator ** private mod prime, but now using the peer's private information.
At this point the peer is already able to compute the shared key. The key is returned by calling the key member, which returns the shared key as a series of bytes stored in a std::string.
Before the initiator can compute the shared key the peer's generator ** private mod prime 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 std::istream to the key member, returning the shared key.
Perfect Forward Secrecy and Ephemeral Diffie Hellman
If the initiator and peer decide not to save their private information Perfect Forward Secrecy and Ephemeral Diffie Hellman may be obtained. Here, the procedure is applied as follows:
The enumeration FBB::DiffieHellman::SecretKey has two values:
This constructor should be called by the initiator to start the Diffie-Hellman shared key computation procedure.
- the size of the prime in bytes;
- the prime's bytes;
- the size of the generator in bytes;
- the generator's bytes;
- the size of the public info (generator ** private mod prime) in
bytes;
- the public info's bytes.
If action is specified as SAVE_SECRET_KEY then the private information is written in binary, big-endian format, using the following organization:
- the size of the private information in bytes;
- the private information bytes.
When called without arguments, the example program generates Diffie-Hellman parameters writing the initiator's public and private information to, respectively, init.pub and init.sec.
When called with one argument, init.pub is read, and the peer's public and private information is written to, respectively, peer.pub and peer.sec. Next, the (peer's) shared key is written to peerkey.
When called with two arguments, init.pub and init.sec are read, as well as the peer's public information (on the file peer.pub). Next, the (initiator's) shared key is written to initkey.
The files peerkey and initkey should be identical.
#include <fstream>
#include <iostream>
#include <bobcat/diffiehellman>
using namespace FBB;
using namespace std;
int main(int argc, char **argv)
try
{
if (argc == 1) // initiator: create DH parameters
{
DiffieHellman dh(1024, 5, true);
dh.save("init", DiffieHellman::SAVE_SECRET_KEY);
}
if (argc == 2) // peer: save peer's scret key
{
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';
}