FBB::ECDH(3bobcat)

📦

version 6.15.01 · 5 versions

6.15.01 · ubuntu stonking (latest)
6.04.00 · ubuntu noble
6.02.02 · debian bookworm
6.11.00 · ubuntu resolute
6.07.01 · debian trixie, ubuntu questing

💖 FBB::ECDH 💖 — from the `3bobcat` manual, bestie

okay so. you're here because you're doing Elliptic Curve Diffie-Hellman and you want shared keys, and honestly? valid. let's get into it. no cap, this one's a whole journey, so grab a snack 🍓

✨ NAME ✨

FBB::ECDH — Elliptic Curve Diffie-Hellman PKI, computing shared keys 💅

✨ SYNOPSIS ✨

#include <bobcat/ecdh>
Linking option: -lbobcat -lcrypto

that's it, that's the vibe check. you include the header, you link against -lbobcat and -lcrypto, periodt 🫶

✨ DESCRIPTION ✨

So the class FBB::ECDH computes shared keys (aka shared secrets) by applying elliptic keys to the Diffie-Hellman (1976) algorithm. Yes, 1976, it's vintage and it ate 👑

The Diffie-Hellman algorithm uses public and private information and it gives you a public key infrastructure (PKI). The public info is literally just an elliptic curve specification plus a public key — and you can share that over insecure media, bestie, it's built different. 🔥

The Diffie-Hellman algorithm is commonly used to compute a shared key, and that shared key then gets used to encrypt info sent between two parties.

So here's the tea. One party — called the initiator in this man-page — does this at construction time:

specifies an elliptic curve 🌈
constructs a public and private key
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 gets written to file separately, because the private key is required for computing the shared key. Also, encryption may be used when writing the private key to file. 👀

Next the initiator passes the file with the initiator's public key and the name of the used elliptic curve to the other party, called the peer in this man-page.

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
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, because 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 initiator. The initiator constructs an ECDH object specifying the names of:

the used elliptic curve
the file containing the initiator's private key
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 info shared between the initiator and the peer. iconic, honestly. 💜

FBB::Exceptions are thrown if the ECDH constructors or members cannot complete their tasks. (so catch them, bestie 😭)

🦋 Perfect Forward Secrecy and Ephemeral Diffie Hellman 🦋

The initiator and peer may decide not to save their private information once they've constructed their shared keys — which gives you Perfect Forward Secrecy and Ephemeral Diffie Hellman. Here, this procedure is applied like this:

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.
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.
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.
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.
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. 🛡️
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's used to obtain a key that's 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 ✨

-

(nothing, bestie, it stands on its own 👑)

✨ ENUMERATIONS ✨

The class ECDH defines two enumerations, each having one defined value. The enumerations are used to select specific overloaded versions of the ECDH constructors or set members:

The t(enum TheInitiator) has value Initiator and is used to select overloaded versions meant for the initiator;
The t(enum ThePeer) has value Peer and is used to select overloaded versions meant for the peer.

✨ CONSTRUCTORS ✨

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; 🗺️
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; 🌟

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; 💌
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 🎀

okay bestie, here's where the actual magic happens. every single one of these, no skips, no cap:

std::string const &curve() const — hands you back the elliptic curve that's being used, that's it, that's the function. 💅
std::string privKey() const — returns the private key, all big-endian and hex-formatted, and it comes prefixed by a line containing hex. ✨
void privKey(std::string const &privKeyFname, std::string passphrase) const — encrypts the private key with the AES-256-GCM encryption algorithm, using passphrase as the passphrase. then it gets written to privKeyFname, prefixed by a line containing encrypted. important: passphrase has to be at least five characters and it can totally contain multiple words. 🫶
std::string const &pubKey() const — gives you the public key as a big-endian hexadecimal string. iconic. 🔥
void set(TheInitiator init, std::string const &curveName, std::string const &initPubFname) — this is the one the initiator calls, building the initiator's private and public keys using the elliptic curve named by curveName. the initiator's public key (big-endian hexadecimal format, obvi) plus curveName get written to initPubFname. it's automatically called by the constructor that takes the same parameters, but you can also call it explicitly later if you used the default constructor. 😌
void set(ThePeer peer, std::string const &initPubFname, std::string const &peerPubFname) — the peer's turn, and this one assumes the peer already got the initiator's public info from the file initPubFname. it constructs the peer's private and public keys and the shared key. the peer's public key (big-endian hexadecimal format again, we stay consistent) goes to peerPubFname, and that file then gets sent to the initiator. also automatically called by the constructor with the same parameters, and also callable explicitly after using the default constructor. 🤝
void set(std::string const &curveName, std::string const &peerPubFname, std::string const &initSecFname, std::string const passphrase = "") — initiator's version of things, called once the peer's public key (that's the file peerPubFname) has arrived. it computes the initiator's shared key. when you use this member, the initiator previously saved its private key to initSecFname, optionally with encryption. if encryption was used, you must pass that passphrase as the last argument. don't forget it, bestie. 🔐
std::string const &sharedKey() const — returns the computed shared key, big-endian hexadecimal format. done and dusted. 🌸
std::string const &sharedKey(std::string const &peerPubFname) — plot twist: instead of using the set(std::string const &curveName, ...) member or the ECDH(std::string const &curveName, ...) constructor, the initiator can just call the set(TheInitiator init, ...) member or the ECDH(TheInitiator init, ...) constructor, and let the process it's running in suspend until the file with the peer's public key shows up. then this member gets called on the constructed ECDH object to grab the initiator's shared key. the glow-up here? the initiator doesn't have to save the initiator's private key at all. main character efficiency. 👑

💖 OVERLOADED OPERATOR 💖

std::ostream &operator<<(ostream &out, ECDH const &ecdh) — writes the currently available elliptic curves and their associated comment to out. alphabetically ordered, one elliptic curve per line. cute and tidy. ✨

🌈 EXAMPLE 🌈

start the program with one of the following arguments:

curves: show the available elliptic curves on cout;
init: compute the initiator's public/secret keys, writing them to init.pub and init.sec;
peer: compute the peer's public/secret keys, writing them to peer.pub and peer.sec, and compute the peer's shared key (peer.shared);
priv: compute the initiator's shared key (init.shared) after making peer.pub available in a separate process, using a single initiator process.
shared: compute the initiator's shared key (init.shared) using a separate initiator process.

and here's the whole thing, verbatim, because girlies don't paraphrase code:

#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

go read those too, iykyk 📚

💀 BUGS 💀

None Reported.

(genuinely no notes. flawless behavior. we love to see it.) ✨

👑 BOBCAT PROJECT FILES 👑

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

Debian Bobcat project files:

libbobcat6: debian package containing the shared library, changelog and copyright note;
libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

🌸 BOBCAT 🌸

Bobcat is an acronym of Brokken’s Own Base Classes And Templates. yes bestie, it's a backronym situation, we stan. 💜

🧚 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).

and that's the whole page, bestie!! this one's from libbobcat-dev_6.15.01, dated 2005-2026, page FBB::ECDH(3bobcat) — go forth and elliptic-curve your little heart out 🫶💅✨

📦 where this page comes from

ubuntu stonking: libbobcat-dev 6.15.01-1 · GPL-3.0-or-later WITH OpenSSL exception
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms