Documentation: Libreswan Opportunistic IPsec using LetsEncrypt

Introduction

letsencrypt invokes several of the utilities involved in controlling the Opportunistic Encryption system, running the specified {command} with the specified [argument] as if it had been invoked directly. More information about the utility is available at Libreswan Opportunistic IPsec using LetsEncrypt .

Prerequisite

The following packages are required to avail full features of the `letsencrypt` program:

1. IPsec - Libreswan

2. certutil

3. wget

4. certbot *

5. openssl *

* Required only for hosts acting as servers. Not required for hosts acting as clients.

Installation

To use the program one needs to have IPsec (Libreswan) installed. Libreswan installation instructions are available here

Available [arguments]

-server, -client, test, generatecertificate hostname, updatecertificate hostname, help, -t, -gc hostname, -uc hostname, -h

Note - To get the list of all acceptable arguments run ipsec letsencrypt -h OR ipsec letsencrypt help

Functions of various [arguments]

Note - OE refers to Opportunistic Encryption.

1. ipsec letsencrypt -client OR ipsec letsencrypt -server

For the initial setup, it is to be run when installing the project for the first time. This [argument] performs the following tasks:

• performs the 1st time server/client Installation.
• checks if the command is run as root.
• Sets and restores the secure umask at appropriate locations.
• Creates temporary directories for downloading the certificates.
• Checks for any existing OE connections.
• Downloads the LetsEncrypt CA and intermediate certificates.
• Checks if NSS database exists.
• Initializes the NSS database and import the LetsEncrypt certificates in it.
• Saves the required client/server configuration in the /etc/ipsec.d directory.
• Restores the security context of the saved configuration using restorecon (if it is available on the system).
• Establishes a secure OE connection by sending pings to the letsencrypt.libreswan.org server.
• Checks for the success of establishing the OE connection.
• Displays OE connection status to user.

2. ipsec letsencrypt test OR ipsec letsencrypt -t

For testing the configuration/connections. This [argument] checks for the success of establishing an OE connection, and performs the following tasks:

• Check for any existing OE connections.
• checks if the command is run as root.
• Establish an OE connection.
• Sending pings to the letsencrypt.libreswan.org server.
• Checking the success of establishing OE connection.
• Displaying connection status to the user.

3. ipsec letsencrypt generatecertificate hostname OR ipsec letsencrypt -gc hostname

Note - hostname refers to the name of the host. e.g. libreswan.org.

For generating the certificate. This [argument] is used for Generating the certificate using Certbot, and performing the following tasks:

• Check if certbot is installed.
• checks if the command is run as root.
• Sets and restores the secure umask at appropriate locations.
• Creates temporary directories for downloading the certificates.
• Generating #pkcs12 file and importing it in the nss database.
• Displays the certificates installed in nss database.
• Generates the certbot configuration for reusing the private key.
• Creates a crontab for automatic certificate renewals.

4. certbot renew --deploy-hook 'ipsec letsencrypt -ug hostname'

Note - hostname refers to the name of the host. e.g. libreswan.org.

For updating the generated certificate (keeping the private key same). This [argument] is used to update the certificate keeping the private key same, and performs the following tasks:

• checks if the command is run as root.
• Updating the certificate using Certbot keeping the private key same.
• Sets and restores the secure umask at appropriate locations.
• Creates temporary directories for downloading the certificates.
• Generating #pkcs12 file.
• Importing the certificate in nss database.
• Displaying the certificates installed in nss database.
• Restarting the IPsec to load the latest updated certificate.

5. ipsec letsencrypt -h OR ipsec letsencrypt help

For providing information regarding various {commands} and [arguments].