Design Overview

lightway-core is a small, multi-platform, pure C library that encapsulates the encryption and processing of IP packets.

On its own, lightway-core is not an executable application. Instead, it is a purposefully simple library. Intentionally, lightway-core is opinionated about how it works and the scope it controls, and very agnostic about everything else. The core use case of this library is as part of a high-performance, always-on VPN application, which necessarily entails deferring items like "how do I actualy send UDP packets?" to the host application, which can use the best API for the platform, be it a Windows desktop or an iPhone.

Terminology

Some people may prefer to see these terms in context, see What does it actually do?

Inside

Refers to data that will be wrapped or has already been unwrapped by lightway-core.

Outside

Refers to data wrapped by lightway-core

SSL Context

lightway-core attributes that may be shared across multiple connections

Connection

lightway-core attributes that reflect a single wrapped data path between a client<→server.

What does it actually do?

At a very high-level, once a connection is established, lightway-core provides a bidirectional pathway for wrapping data in a way that can be securely sent over the internet.

One direction is the "inside path". The host application passes data to lightway-core for wrapping, and then lightway-core will call the host application’s outside_write_cb one or more times with the appropriately encrypted data, which the host is then responsible for transmitting appropriately.[1]

The other direction is the "outside path". The host application passes data wrapped by lightway-core to the appropriate library function; lightway-core will then call the host application’s inside_write_cb one or more times with the appropriately unwrapped data, which the host can then deliver appropriately.

Of course, the devil is in the details, and there are a lot of details here.

Where to next?

  • Life of a Packet

  • lightway-core Wire Protocol (Coming Soon)

  • lightway-core Msg Protocol (Coming Soon)

  • lightway-core Connection Lifecycle (Coming Soon)

1. Where "appropriately" normally means "send these packets over the internet, client→server or server→client depending on which side of the connection we are on."