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.04.00-x.dsc: detached signature;

o

bobcat_6.04.00-x.tar.gz: source archive;

o

bobcat_6.04.00-x_i386.changes: change log;

o

libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

o

libbobcat1-dev_6.04.00-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).