Developer Documentation

Contributions / License

Before starting development, please read our contribution requirements.

Getting the Source Code

The easiest way to get the source code is checking it out from our Git repository:

git clone https://github.com/strongswan/strongswan.git

Browsing the Source Code

The Git repository can be browsed directly at GitHub.

Source Code Documentation

strongSwan uses extractable inline documentation extensively. This documentation is extracted with Doxygen for the latest release and uploaded to strongswan.org/apidoc. Use make apidoc to generate it from the sources.

Code style

For our code we heavily use an object oriented programming style for C. Also have a look to our basic programming style guidelines.

Quality Assurance

Unit Tests

Our libraries are tested with an increasing number of unit tests. To run them use make check. The following environment variables change the behavior of the test runner:

Variable Description Since Version

TESTS_PLUGINS

A space-separated list of plugins to load
(not implemented by all test runners)

5.3.3

TESTS_REDUCED_KEYLENGTHS

If this is set, test cases that generate keys will do so only for reduced key lengths to avoid blocking on hosts with low entropy

TESTS_STRONGSWAN_CONF

Path to a custom strongswan.conf file used for the tests

5.2.0

TESTS_RUNNERS

A comma-separated list of test runners to run

5.5.0

TESTS_SUITES

A comma-separated list of test suites to run
(all suites are run if this is not specified)

TESTS_SUITES_EXCLUDE

A comma-separated list of test suites excluded from running

5.2.1

TESTS_CASES

A comma-separated list of test cases to run
(all cases of selected suites are run if this is not specified)

5.9.0

TESTS_CASES_EXCLUDE

A comma-separated list of test cases excluded from running

5.9.0

TESTS_FUNCTIONS

A comma-separated list of test functions to run (all functions of selected suites/cases are run if this is not specified)

5.9.0

TESTS_FUNCTIONS_EXCLUDE

A comma-separated list of test functions excluded from running

5.9.0

TESTS_ITERATIONS

A comma-separated list of iterations of a loop-based test function to run (all iterations are run if this is not specified)

5.9.8

TESTS_NO_IPV6

Disables IPv6 test cases (e.g. to run the tests in Docker containers that only provide IPv4 networking)

5.9.6

TESTS_VERBOSITY

The log level used when running the tests (-1 to 4 with a default of -1), see Logging

TESTS_VERBOSITY_<GROUP>

The log level used for a specific log group (CFG, IKE, etc.) when running the tests (-1 to 4 with a default of TESTS_VERBOSITY), see Logging

5.9.7

LEAK_DETECTIVE_DISABLE

If our custom memory allocator is enabled with --enable-leak-detective, it can be disabled temporarily by setting this variable in order to speed up running the tests

Coverage reports can be generated with make coverage which requires the --enable-coverage ./configure option which is not recommended for production builds as it disables all optimizations.

The unit tests also run automatically for every commit:

Linux

Android

macOS

Windows

Windows

FreeBSD

Information on the code coverage:

Codecov

And the code base is automatically analyzed:

SonarCloud

Sonarcloud

LGTM

LGTM Grade

Part of the source code is periodicylly fuzzed by Google OSS-Fuzz:

Fuzzing

Testing Environment

Our integration and regression testing environment helps us ensure the quality of future releases. The test results for the latest strongSwan release are published online.

Components

The src directory in the strongSwan distribution contains the following components:

Component Description

aikgen

Utility to generate an Attestation Identity Key bound to a TPM 1.2

charon

The IKE keying daemon

charon-cmd

A command line IKE client

charon-nm

The back end for the NetworkManager D-BUS plugin

charon-svc

The Windows IKE service

charon-systemd

An IKE daemon similar to charon but specifically designed for use with systemd

charon-tkm

A variant of charon that is backed by a Trusted Key Manager (TKM)

checksum

Utility to generate checksums of built executables and libraries

conftest

Conformance test tool

frontends/android

VPN client for Android

frontends/gnome

NetworkManager plugin

frontends/osx

charon-xpc helper daemon for the native macOS application

ipsec

The legacy ipsec command line tool wrapping commands and other tools

libcharon

Contains most of the code and the plugins of the charon daemon

libfast

A lightweight framework to build native web applications using ClearSilver and FastCGI

libimcv

Various Integrity Measurement Collectors (IMCs), Integrity Measuremeent Validators (IMVs) and the library code shared by them

libipsec

A userland IPsec implementation used by kernel-libipsec and the Android VPN Client app

libpts

Contains code for TPM-based Platform Trust Services (PTS) and SWID tag handling

libpttls

Implements the PT-TLS protocol

libradius

RADIUS protocol implementation used by e.g. the eap-radius and tnc-pdp plugins

libsimaka

Contains code shared by several EAP-SIM/AKA plugins

libstrongswan

The strongSwan library with basic functions used by the daemons and utilities

libtls

TLS implementation used by the eap-tls, eap-ttls, eap-peap and other plugins

libtnccs

Implements the IF-TNCCS interface

libtncif

Implmements the IF-IMC/IF-IMV interfaces

manager

A deprecated graphical management application for charon based on libfast

medsrv

An experimental management front end for mediation servers based on libfast

pki

Public Key Infrastructure utility

pool

Utility to manage attributes and IP address pools provided by the attr-sql plugin

pt-tls-client

Integrity measurement client using the PT-TLS protocol

scepclient

Utility to enroll certificates using the SCEP protocol

sec-updater

Utility extracting information about security updates and backports of Linux repositories (e.g. Debian or Ubuntu)

starter

Legacy daemon that reads ipsec.conf and controls the keying daemon charon

stroke

Legacy command line utility to control charon via the stroke protocol

swanctl

Configuration and control utility that communicates via the vici interface

sw-collector

Utility extracting information about software package installation, update or removal events from the apt history log

tpm_extendpcr

Tool that extends a digest into a TPM PCR

_updown

Default script called by the updown plugin on tunnel up/down events

xfrmi

Create an XFRM interface