CSNET

CSNET is a C application programming library for communicating over a SCION network. More information about SCION can be found here. CSNET exposes a BSD-socket-like API to send and receive SCION packets. CSNET provides similar functionalities to snet (Go), PAN (Go), JPAN (Java) and scion-rs (Rust).

Feature Summary:

• Linux, MacOS and ESP32 support
• UDP over SCION
• SCMP (ICMP for SCION)
• Explicit SCION path selection
• SCION ping tool

To get started with CSNET follow the building and installation instructions below and afterward continue with the Getting Started Guide.

Requirements

Building and installing the library and examples requires CMake 3.22 or newer (download here).

All the requirements for building the library and examples are fetched automatically with CMake and installed in the workspace build directory, ensuring the rest of the system remains unaffected.

Running the examples (in ./examples) additionally requires the following:

• a running local SCION Network (see Local SCION Network Setup for setup instructions)
• some examples have additional requirements, consult the README for more information

Building the documentation (in ./docs) requires:

• doxygen (download here)
• graphviz (download here)

Building and Installation

Setup the CMake build directory in ./dist with

cmake -DBUILD_LIB=ON -DBUILD_CMD=ON -DBUILD_EXAMPLES=ON -DBUILD_TESTS=OFF -DBUILD_DOCS=OFF -B dist

The following options exist:

• BUILD_LIB: build the library in ./lib
• BUILD_CMD: build the command line tools in ./cmd
• BUILD_EXAMPLES: build the examples in ./examples.
• BUILD_TESTS: build the tests in ./tests, the cmd tools in ./cmd and some of the examples in ./examples that serve as E2E tests. This means that even if BUILD_EXAMPLES is OFF some examples may still be built if BUILD_TESTS is ON. The same holds for BUILD_CMD.
• BUILD_DOCS: build the docs which are output to ./docs/api.

Build everything with

cmake --build dist

To install the library execute:

 cmake --install dist --prefix "your installation directory"

Depending on the installation directory you might need to run the command with sudo.

The installation will produce the static libraries lib/libscion.a, lib/libnghttp2.a, lib/libprotobuf.a, the header file include/scion/scion.h and the command-line tool bin/ping in your installation directory. When using the library make sure to link against all the static libraries produced by the installation.

Known Issues

• On ARM you might get clang++: error: unsupported option '-msse4.1' for target 'arm64-apple-darwin24.4.0 when building. This is a known issue and we have to wait for a version bump in protobuf ( discussion here).

Local SCION Network Setup

Requirements:

• Linux, MacOS or WSL
• Go 1.23 or newer (download here)

To set up a local SCION Network execute the setup script in scripts/setup-network.sh. After successfully installing it, the network can be started with scripts/run-testnet.sh. Press Ctrl+C to shut down the test network.

ESP32

EPS32 specific instructions can be found here.

Library Development

Requirements

Required tools:

• protobuf and protobuf-c: Protobuf to C compiler required to generate code from .proto files to talk to a control server.
• (optionally) clang-format: Code formatter we use.

Code Quality

To automatically format the code install clang-format (e.g., via Homebrew) and run

find . -iname "*.h" -o -iname "*.c"  | xargs clang-format -i

Individual sections can be excluded from formatting like follows:

// clang-format off
...
// clang-format on

Entire files and directories are ignored by adding them to .clang-format-ignore