GSoD

Google Season of Documentation (GSoD) Ideas Page

The [1] Libreswan Project is an opensource project that started back in 1995 as the FreeS/WAN project which had as goal to encrypt the internet internet using what we would not call VPNs. It was the first opensource implementation of IPsec. After its funding stopped in 2003, it was forked and continued as the Openswan project. In 2011, it was again renamed - this time due to a lawsuit - to libreswan. Technically, libreswan is an IKE implementation (see RFC 7296). IKE is used to negotiate IPsec VPN tunnels. The IKE software then configures the Operating System's kernel with the right IPsec settings that will do the actual packet encryption over the internet.

A lot has happened in these 25 years. The goals of encrypting the internet is no longer its primary goal. It's main mission is now focused on delivering an enterprise and home VPN product based on IPsec. IPsec is the swiss army knife of VPN technologies. It is extremely versatile and can be used in many different scenarios. To list a few:

• A basic computer-to-computer VPN
• A network-to-network VPN
• branch offices to head office VPN
• cloud / mesh encryption
• Remote Access VPN
• Mobile device VPN
• compute nodes, containers and virtual machines and networking support
• SDWAN (software defined networking) encryption
• opportunistic IPsec (try to encrypt everything, fallback to unencrypted

All these different scenario's require different settings, have their own pitfalls, and require knowledge in specific areas of expertise such as networking, security, cryptography.

All the documentation, test cases, manual pages and other documentation has been written by developers. While some attempts have been made to make this more accessible to newcomers, that is something that is hard to do for a developer with a lot of knowledge on the software, but with limited knowledge on how to write good accessible and readable documentation.

Additionally, developers are not web content providers, and we know that clearly shows on our website as well. It's made by geeks for geeks and is only usable for geeks. The switch the mediawikki was done to allow anyone to contribute to improving documentation but after a few years we have learned that this was false hope. The only people willing to contribute to our wiki were spambots and our own developers.

Additional Information

To get an idea about libreswan and its documentation, we have listed a few links to information below. Note that the IKE and IPsec protocols are developed by the Internet Engineering Task Force (IETF). All specifications of the protocols and their extensions are published as RFCs or draft RFCs. Those documents however are written for software engineers that need to write the code to implement these protocols. So these documents are not very good for newcomers or non-technical people that just want to setup their VPN system(s).

• The Libreswan Wiki
• Red Hat's getting started tutorial
• Guide to IPsec by NIST, the Us government National Institute of Standards and Technology
• NetDev presentation on IPsec/libreswan from 2018
• DevConf presentation on large scale cloud encryption from 2020
• libreswan FAQ
• host-to-host basic configuration example
• SWAN history - see slides 36-49 for some of the 25 years of SWAN History

Project Ideas

New document on authentication methods

Setting up VPN configurations consist of two main parts. The first part is about how different devices authenticate eah other. There are a number of options, with the most common ones being X.509 certificates, PreSharedKeys (PSK) and raw (unsigned) public keys (distributed out of band or via DNSSEC). Managing certificates for a large number of machines or users is actually a dauntintg task for most users, even though it is a relatively simple technical task. This is where our documentation is severely lacking. Some parts of it are in various HOWTO's, but there is no single document where people can go to where they can learn about what is best for them and how to achieve that. Our documentation sometimes just picks one option as example and continues with other configuration options. Other times it just skips this part, or just mentions "use certificates or PSK" without explaining to the user why or how to do this. Sometimes it just states how to use the certificate "generated with other software".

It would be very useful to have a document that explains the different authentication methods. Which ones are best used in what scenario's, and then also explain in great detail how to do this. Then hopefully, we can write and/or rewrite our other documentation by referencing this document.

Basic Networking concepts

Often, we see that people are attempting to use IPsec without the minimal IP knowledge. As a result, they are trying to do something that is technically impossible. One such example is building a VPN tunnel between two parties who use the same IP address network (for example both networks use 192.168.0.*). A short write that explains the following concepts would be very helpful:

• IP address - IPv4 and IPv6
• netmasks, gateways and routers
• IP forwarding, firewalling and NAT
• DNS and domain lookups
• root user and permissions

Basic cryptography concepts

People are often confused about IKE versus ESP crypto parameters.

The ipsec command

The ipsec command is the core libreswan command that handles everything via sub commands. While we have a man page and some help information, a short document about how to use the various ipsec commands would be very valuable.

• Connection management: ipsec auto add|delete|up|down
• Status information: ipsec status|trafficstatus|shuntstatus
• Statistics/Monitoring: ipsec whack globalstats|resetstats
• On the fly reconfiguration: ipsec whack --redirect|--globalredirect|--ddos-mode

Improve or rewrite our basic examples

People still often find our "basic" examples too complicated. It is difficult for developers to fully understand how to document this for non-experts. It would also help if all these examples used a consistent method and layout for writing and diagrams and showing input and output and language.

Certificates for IPsec

There are many ways to generate and maintain certificates. Depending on the type of deployment, this can vary from very simply to very complext requirements. A document guiding the user to other software on how to manage their certificate program would be very useful. Especially useful are the very simple ones, since that is what people often need. While most of the documentation out there consists of magical complicated openssl commands for TLS servers. There are also some specific requirements for IKE/IPsec servers, such as ensuring that the machine name (eg vpn.example.com) appears in a certain way within the certificate.

Trouble shooting

The FAQ tries to explain a number of common problems, but there is no consistent easy to read general troublshooting or debugging document that ties most of these individual issues into one cohesive narrative.

A brief history of the swans

People are often confused about all the different swans: freeswan, openswan, strongswan and libreswan. There is a lot of history and it would be valuable to have a short and clear document about the different implementations and their history. Some of this was written down in a presentation given at NetDev, see slide deck on slides 38 to 49.

Other Ideas

There are probably a lot of other things that are not even clear to us developers that need work. If you see any other issues or something that is very confusing, please contact us at gsod@libreswan.org with your idea and we will give you feedback on your idea.