Provided by: libbobcat-dev_6.06.01-1_amd64 
NAME
FBB::ECDH - Elliptic Curve Diffie-Hellman PKI, computing shared keys
SYNOPSIS
#include <bobcat/ecdh>
Linking option: -lbobcat -lcrypto
DESCRIPTION
The class FBB::ECDH computes shared keys (shared secrets) applying elliptic keys to the Diffie-Hellman
(1976) algorithm. The Diffie-Hellman algorithm uses public and private information, providing a public
key infrastructure (PKI). The public information consists of an elliptic curve specification and a public
key, which may be shared over insecure media.
The Diffie-Hellman algorithm is commonly used to compute a shared key which is then used to encrypt
information sent between two parties.
One party, which in this man-page is called the initiator, specifies at construction time an elliptic
curve, constructs a public and private key, and writes the public key in hexadecimal big-endian form,
followed by the name of the used elliptic curve to file. The initiator’s private key is separately
written to file, as the private key is required for computating the shared key. Encryption may be used
when writing the private key to file.
Next the initiator passes the file containing the initiator’s public key and the name of the used
elliptic curve to the other party, which in this man-page is called the peer.
The peer, having received the initiator’s (public key) file constructs an FBB::ECDH object. The peer’s
ECDH constructor computes the peer’s public and private key, writes the peer’s public key to file, and
constructs the shared key. Once the peer’s ECDH object has been constructed the peer can write the shared
key to file. The peer’s private key may optionally also be written to file, but that’s optional, as the
peer’s private key is not required for subsequent computations. Encryption may also be used when writing
the peer’s private key to file.
The file containing the peer’s public key is then sent to the initator. The initator constructs an ECDH
object specifying the names of the used elliptic curve, of the file containing the initiator’s private
key, and the name of the file containing the peer’s public key. Once this ECDH object has been
constructed the peer may write the shared key to file.
The initiator and peer’s shared keys are identical and can be used for symmetric encryption of sensitive
information shared between the initiator and the peer.
FBB::Exceptions are thrown if the ECDH constructors or members cannot complete their tasks.
Perfect Forward Secrecy and Ephemeral Diffie Hellman
The initiator and peer may decide not to save their private information once they have constructed their
shared keys, resulting in Perfect Forward Secrecy and Ephemeral Diffie Hellman. Here, this procedure is
applied as follows:
o 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.
o Applying the procedure described in the previous section, the private keys are not saved on files,
and the process constructing the initiator’s ECDH object may not terminate, but must remain active
until the peer’s public key has been received. Once the initiator’s process has constructed the
public key that key is encrypted using the common secret, and is then sent to the peer.
Alternatively, the initiator’s private key may temporarily be stored in shared memory or may
temporarily be stored encrypted on file.
o The peer, having received the initiator’s public key, constructs the shared secret, encrypts the
peer’s public key, and sends the encrypted public key to the initiator.
o The initiator upon receipt of the peer’s public key, computes the shared key, either by continuing
the temporarily suspended construction process or by retrieving the shared key from memory or
file, removing the storage (memory or file) thereafter.
o Since the private keys and the public keys are not stored or kept on files the shared keys cannot
be reconstructed, while a Man-In-The-Middle attack is prevented by only exchanging encrypted
public information.
o The shared key can now be used to encrypt a communication session
Document encryption using Diffie Hellman
As with PKI in general, the Diffie Hellman key exchange method itself is normally not used for encrypting
documents. Instead, it is used to obtain a key that is used for symmetric encryption methods like 3DES or
CBC. These symmetric encryption methods are available through, e.g., Bobcats’ ISymCryptStream and
OSymCryptStream classes.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the
namespace FBB.
INHERITS FROM
-
ENUMERATIONS
The class ECDH defines two enumerations, each having one defined value. The enumberations are used to
select specific overloaded versions of the ECDH constructors or set members:
o The t(enum TheInitiator) has value Initiator and is used to select overloaded versions meant for
the initiator;
o The t(enum ThePeer) has value Peer and is used to select overloaded versions meant for the peer.
CONSTRUCTORS
o ECDH():
The default constructor is available merely constructing a valid object. It also prepares a map of
all elliptic curves predefined by openSSL. As all other constructors use default constructor
delegation the map is also available after calling the other constructors;
o ECDH(TheInitiator init, std::string const &curveName, std::string const &initPubFname):
This constructor initializes the ECDH object to be used by the initiator, constructing the
initiator’s private and public keys using the elliptic curve specified by curveName (e.g.,
secp384r1, see also operator<< below). The initiator’s public key (in big-endian hexadecimal
format) and curveName are written to initPubFname;
This constructor should be called by the initiator to start the Diffie-Hellman shared key
computation procedure;
o ECDH(ThePeer peer, std::string const &initPubFname, std::string const &peerPubFname):
This constructor is used by the peer, having received the initiator’s public info on the file
initPubFname. It constructs the peer’s private and public keys as well as the shared key. The
peer’s public key (in big-endian hexadecimal format) is written to peerPubFname, which file is
then be sent to the initiator;
o ECDH(std::string const &curveName, std::string const &peerPubFname, std::string const
&initSecFname, std::string const passphrase = ""):
Once the initiator has received the peer’s public key (in the file peerPubFname) this constructor
constructs the initiator’s version of the shared key. Here, the initiator has previously saved the
initiator’s private key to initSecFname, optionally using encryption. If encryption was used then
the then used passphrase must also be specified when using this constructor.
The move constructor (and move assignment operator) is available.
MEMBER FUNCTIONS
o std::string const &curve() const:
The used elliptic curve is returned;
o std::string privKey() const:
The big-endian hex-formatted private key is returned, prefixed by a line containing hex;
o void privKey(std::string const &privKeyFname, std::string passphrase) const:
The private private key is encrypted using the AES-256-GCM encryption algorithm, using passphrase
passphrase. It is then written to privKeyFname, prefixed by a line containing encrypted. The
string passphrase must consist of at least five characters, and may contain multiple words;
o std::string const &pubKey() const:
The public key is returned as a big-endian hexadecimal string;
o void set(TheInitiator init, std::string const &curveName, std::string const &initPubFname):
This member should be called by the initiator, constructing the initiator’s private and public
keys using the elliptic curve specified by curveName. The initiator’s public key (in big-endian
hexadecimal format) and curveName are written to initPubFname. This member is automatically
called by the constructor having the same parameters, but it may also explicitly called after
using the default constructor;
o void set(ThePeer peer, std::string const &initPubFname, std::string const &peerPubFname):
This member should be called by the peer, having received the initiator’s public info on the file
initPubFname. It constructs the peer’s private and public keys as well as the shared key. The
peer’s public key (in big-endian hexadecimal format) is written to peerPubFname, which file is
then be sent to the initiator. This member is automatically called by the constructor having the
same parameters, but it may also explicitly called after using the default constructor;
o void set(std::string const &curveName, std::string const &peerPubFname, std::string const
&initSecFname, std::string const passphrase = ""):
This member should be called by the initiator, once the peer’s public key (in the file
peerPubFname) has been received. It computes the initiator’s version of the shared key. When using
this member the initiator has previously saved the initiator’s private key to initSecFname,
optionally using encryption. If encryption was used then the then used passphrase must also be
specified as this member’s last argument.
o std::string const &sharedKey() const:
This member returns the computed shared key (in big-endian hexadecimal format);
o std::string const &sharedKey(std::string const &peerPubFname):
Instead of using the set(std::string const &curveName, ...) member or the ECDH(std::string const
&curveName, ...) constructor, the initiator may also merely call the set(TheInitiator init, ...)
member or the ECDH(TheInitiator init, ...) constructor, suspending the process in which they are
called until the file containing the peer’s public key has been received. Then, this member can be
called by the constructed ECDH object to obtain the initiator’s shared key. The advantage of using
this member is that the initiator does not have to save the initiator’s private key.
OVERLOADED OPERATOR
o std::ostream &operator<<(ostream &out, ECDH const &ecdh):
The (alphabetically ordered) currently available elliptic curves and their associated comment is
written to out, one elliptic curve on a separate line.
EXAMPLE
Start the program with one of the following arguments:
o curves: show the available elliptic curves on cout;
o init: compute the initiator’s public/secret keys writing them to init.pub and init.sec;
o peer: compute the peer’s public/secret keys writing them to peer.pub and peer.sec, compute the
peer’s shared key (peer.shared);
o priv: compute the initiator’s shared key (init.shared) after making peer.pub available in a
separate process, using a single initiator process.
o shared: compute the initiator’s shared key (init.shared) using a separate initiator process.
#include "main.ih"
int main(int argc, char **argv)
try
{
if (argc == 1)
{
usage(path{ argv[0] }.filename().string());
return 0;
}
if ("curves"s == argv[1]) // show supported ECDH curves.
cout << ECDH{};
else if ("init"s == argv[1]) // initiator key construction
{
// write the file containing
// the curve + public key
ECDH ecdh{ ECDH::Initiator, "secp384r1", "init.pub" };
// save the initiator’s
// private key
ecdh.privKey("init.sec", "use your passphrase");
// not using encryption:
// auto initSec = Exception::factory<ofstream>("init.sec");
// initSec << ecdh.privKey() << ’\n’;
}
else if ("priv"s == argv[1]) // initiator key construction
{
// write the file containing
// the curve + public key
ECDH ecdh{ ECDH::Initiator, "secp384r1", "init.pub" };
cout << "wait for the peer’s public key. "
"Press Enter to continue... ";
cin.ignore(100, ’\n’);
// written to file
auto initShared = Exception::factory<ofstream>("init.shared");
initShared << ecdh.sharedKey("peer.pub") << ’\n’;
}
else if ("peer"s == argv[1]) // peer’s key construction
{
// write the peer’s public key
ECDH ecdh{ ECDH::Peer, "init.pub", "peer.pub" };
// save the peer’s private
// key (although not needed)
auto out = Exception::factory<ofstream>("peer.sec");
out << ecdh.privKey() << ’\n’;
out = Exception::factory<ofstream>("peer.shared");
out << ecdh.sharedKey() << ’\n’;
}
else if ("shared"s == argv[1]) // the initiator’s shared key
{ // construction
ECDH ecdh{ "secp384r1", "peer.pub", "init.sec",
"use your passphrase" };
auto initShared = Exception::factory<ofstream>("init.shared");
initShared << ecdh.sharedKey() << ’\n’; // written to file
}
else
{
usage(path{ argv[0] }.filename().string());
return 1;
}
}
catch (exception const &exc)
{
cerr << "Error: " << exc.what() << ’\n’;
return 1;
}
catch (...) // and handle an unexpected exception
{
cerr << "unexpected exception\n";
return 1;
}
FILES
bobcat/ecdh - defines the class interface
SEE ALSO
bobcat(7), bigint(3bobcat), diffiehellman(3bobcat), isymcryptstream(3bobcat), osymcryptstream(3bobcat)
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.06.01-x.dsc: detached signature;
o bobcat_6.06.01-x.tar.gz: source archive;
o bobcat_6.06.01-x_i386.changes: change log;
o libbobcat1_6.06.01-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.06.01-x_*.deb: debian package containing the libraries, headers and manual pages;
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).