DwmCredence Class Library

Table of Contents

• Introduction
• Main Library Abstractions
  • Peer
    • Connection Establishment
    • Mutual Authentication
    • Send and Receive Messages
  • Key Stash and Known Keys
    • Key Stash
    • Known Keys
• History
• Platforms
• Examples
  • Assumptions
  • Simple echo
    • Simple echo client
    • Simple echo server

Introduction

This class library may be used for secure, authenticated network communication over TCP. The main three classes are Dwm::Credence::Peer, Dwm::Credence::KeyStash and Dwm::Credence::KnownKeys. Utilizing just these three classes, it is relatively easy to create secure TCP applications.

The library depends on libsodium, boost::asio and libDwm.

Since I'm using libsodium, I'm using XChaCha20Poly1305 for encryption. User and server authentication uses signatures produced and validated with Ed25519 keys.

No passwords are used, only key files (which aren't password protected). This is intentional since my main usage is in applications that are not launched interactively. I may later add password protected keys.

Main Library Abstractions

Peer

The Peer class encapsulates a connection, via TCP or a UNIX domain socket. It is the main interface through which connections are initiated (via the Connect() member), accepted (via the Accept() member), and authenticated (via the Authenticate() member). It is also the interface through which messages are sent (via the Send() member) and received (via the Receive() member).

Connection Establishment

A client utilizes the Connect() member to connect to a server. A server accepts incoming connections via the Accept() member. As part of the connection setup, a shared encryption key is derived by each side. This key is ephemeral (only used for this connection), and used to encrypt all future traffic between the peers.

Mutual Authentication

The Authenticate() member of the Peer class performs mutual authentication. It verifies the claimed identity of the remote service and provides verifiable evidence of the identity of the local application to the remote service. It returns true if authentication succeeds, false if it fails.

Send and Receive Messages

Messages are exchanged using the Send() and Receive() members of the Peer class. These are member function templates, and use Dwm::StreamIO functionality from libDwm to allow sending and receiving all types supported directly by libDwm as well as all types which implement the requirements of the Dwm::HasStreamRead and Dwm::HasStreamWrite concepts.

Key Stash and Known Keys

Key Stash

Known Keys

History

This library came about when I needed a replacement for Crypto++ (needed by libDwmAuth). In my own applications, libDwmAuth was replaced by libDwmCredence. The new name is a hint that it's not the same as libDwmAuth under the hood, and allowed me to migrate my applications as I had time.

Platforms

I only maintain support for 4 platforms: FreeBSD, macOS, desktop linux and Raspbian (now Raspberry Pi OS). FreeBSD is my operating system of choice for servers and macOS is my operating system of choice for desktops and laptops. I have several Raspberry Pis I utilize for various tasks, and Ubuntu VMs and Ubuntu workstations.

Examples

Assumptions

The examples assume that you have created your key files by running credence keygen, and that they are present in the default directory (~/.credence). They also assume that you have your own public key (from ~/.credence/id_ed25519.pub) in the default ~/.credence/known_keys file.

Simple echo

Simple echo client

#include "DwmCredencePeer.hh"
 
int main(int argc, char *argv[])
{
  using namespace std;
  using namespace Dwm;
  
  int  rc = 1;
  
  if (argc < 3) {
    cerr << "Usage: " << argv[0] << " host port\n";
    return 1;
  }
  
  Credence::Peer  peer;
  if (peer.Connect(argv[1], std::stoul(argv[2]))) {
    Credence::KeyStash   keyStash;
    Credence::KnownKeys  knownKeys;
    if (peer.Authenticate(keyStash, knownKeys)) {
      rc = 0;
      string  msg;
      while (std::getline(cin, msg)) {
        if (! peer.Send(msg))    { rc = 1; break; }
        if (! peer.Receive(msg)) { rc = 1; break; }
        cout << msg << '\n';
        if (msg == "Goodbye")    { break; }
      }
    }
    else {
      cerr << "Failed to authenticate to " << argv[1]
           << " port " << argv[2] << '\n';
    }
  }
  else {
    cerr << "Failed to connect to " << argv[1]
         << " port " << argv[2] << '\n';
  }
  
  return rc;
}

Simple echo server

Note that this server only accepts one client, and will exit after communicating with the client. In other words, it's not typical, but instead is a minimal illustration.

#include "DwmCredencePeer.hh"
 
using namespace std;
using namespace boost::asio;
using namespace Dwm;
 
//----------------------------------------------------------------------------
static ip::tcp::socket AcceptSocket(io_context & ioContext,
                                    const string & addr, uint16_t port)
{
  ip::tcp::endpoint  endPoint(ip::address::from_string(addr), port);
  ip::tcp::acceptor  acc(ioContext, endPoint);
  boost::asio::ip::tcp::acceptor::reuse_address  option(true);
  acc.set_option(option);
  acc.non_blocking(false);
 
  ip::tcp::endpoint  client;
  ip::tcp::socket    sock(ioContext);
  acc.accept(sock, client);
  sock.native_non_blocking(false);
  return sock;
}
 
//----------------------------------------------------------------------------
static bool AcceptPeer(io_context & ioContext, const string & addr,
                       const string & port, Credence::Peer & peer)
{
  bool  rc = false;
  try {
    ip::tcp::socket  sock = AcceptSocket(ioContext, addr, std::stoul(port));
    if (sock.is_open()) {
      rc = peer.Accept(std::move(sock));
    }
  }
  catch (std::exception & ex) {
    cerr << "Exception: " << ex.what() << '\n';
  }
  return rc;
}
 
//----------------------------------------------------------------------------
int main(int argc, char *argv[])
{
  if (argc < 3) {
    cerr << "Usage: " << argv[0] << " addr port\n";
    return 1;
  }
 
  int  rc = 1;
  io_context      ioContext;
  Credence::Peer  peer;
  if (AcceptPeer(ioContext, argv[1], argv[2], peer)) {
    Credence::KeyStash   keyStash;
    Credence::KnownKeys  knownKeys;
    if (peer.Authenticate(keyStash, knownKeys)) {
      rc = 0;
      string  msg;
      do {
        if (! peer.Receive(msg)) { rc = 1; break; }
        if (! peer.Send(msg))    { rc = 1; break; }
      } while (msg != "Goodbye");
    }
    else {
      cerr << "Authentication failed\n";
    }
  }
  else {
    cerr << "AcceptPeer failed\n";
  }
  
  return rc;
}