strongSwan 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 at GitHub:
git clone https://github.com/strongswan/strongswan.gitThe repository is currently also mirrored to git.strongswan.org.
Browsing the Source Code¶
The Git repository can be browsed directly at GitHub, Gitweb is also still available, and the integrated repository browser (slower) too.
Source Code Documentation¶
The newer parts of strongSwan use 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 yourself 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:
| TESTS_PLUGINS | A space-separated list of plugins to load (not implemented by all test runners). Since 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. Since 5.2.0. |
| TESTS_RUNNERS | A comma-separated list of test runners to run. Since 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. Since 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). Since 5.9.0. |
| TESTS_CASES_EXCLUDE | A comma-separated list of test cases excluded from running. Since 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). Since 5.9.0. |
| TESTS_FUNCTIONS_EXCLUDE | A comma-separated list of test functions excluded from running. Since 5.9.0. |
| TESTS_VERBOSITY | The log level used when running the tests (-1 to 4, see LoggerConfiguration), defaults to -1. |
| 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 (requires configuring with --enable-coverage, which is not recommended for production builds as it disables all optimizations).
The unit tests also run automatically for every commit:
And the code base is automatically analyzed:
Testing Environment¶
Our integration and regression testing environment helps us ensure the quality of future releases.
The results for the latest release are published online.
Components¶
The src directory in the strongSwan distribution contains the following components:
| aikgen | Utility to generate an Attestation Identity Key bound to a TPM |
| charon | The IKE keying daemon |
| charon-cmd | A command line IKE client |
| charon-nm | The back end for the NetworkManager plugin |
| charon-svc | A Windows IKE service |
| charon-systemd | An IKE daemon similar to charon, but is 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 |
| dumm | An experimental UML testing framework |
| frontends/android | VPN client for Android 4+ |
| frontends/gnome | NetworkManager plugin |
| frontends/osx | charon-xpc helper daemon for the native Mac OS X 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 | Contains IMCs, IMVs and code shared by them |
| libipsec | An IPsec implementation used by kernel-libipsec and the Android app |
| libpts | Contains code for TPM-based remote attestation 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 | Contains IF-TNCCS implementations |
| libtncif | Contains IF-IMC/IMV code |
| 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 | PT-TLS protocol client |
| scepclient | Utility to enroll certificates using the SCEP protocol |
| 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 vici interface |
| tpm_extendpcr | Tool that extends a digest into a TPM PCR |
| _updown[_espmark] | Default script called by the updown plugin on tunnel up/down events |
Removed Components¶
| Removed with 5.5.1 | |
| frontends/maemo | Maemo applet |
| Removed with 5.4.0 | |
| libhydra | Contained daemon-specific code and plugins used by the charon and starter daemons |
| Removed with 5.0.0 | |
| pluto | The old IKEv1 keying daemon. |
| libfreeswan | The deprecated library used by pluto. |
| whack | Command line utility to control pluto via the whack protocol. |