View source for Documentation: Libreswan Opportunistic IPsec using LetsEncrypt

== Introduction ==

Libreswan Opportunistic IPsec using LetsEncrypt is a project to create a program <code>letsencrypt</code> in <code>ipsec</code> which allows establishing the Opportunistic Encryption connections between two hosts.
The <code>letsencrypt</code> program allows using various available utilities required to establish and control an Opportunistic connection. The letsencrypt program has several features, and can be used by running a specified {command} with a specified [argument].

e.g. <code>ipsec letsencrypt --help</code> lists all the available commands and how to use them.

The man page for the program is available at <code>man ipsec letsencrypt</code>. The program creates a secure Opportunistic Connection between the hosts commonly referred to as client and server. The client connects to the server and remains anonymous, whereas the server is authenticated before connecting to it, i.e., server is not anonymous. The server uses Let's Encrypt certificates for authentication and encryption purposes. Once the initial phase of authentication and handshaking completes, the secure connection establishes, and all the traffic (traffic can be through multiple applications) between the two hosts is now encrypted.

== Prerequisite ==

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

1. IPsec - [https://github.com/libreswan/libreswan/ Libreswan]

2. certutil

3. wget

4. certbot * 

5. OpenSSL *

<code>* Required only for hosts acting as servers. Not required for hosts acting as clients.</code>

== Installation ==

To use the program, one needs to have IPsec (Libreswan) installed. Libreswan installation instructions are available [https://github.com/libreswan/libreswan/blob/master/README.md here]

== Available [arguments] ==

<code>ipsec letsencrypt [arguments]</code>

Available [arguments]

<pre>--server, --client, --test, --generate-certificate hostname, --renew hostname, --help, --disable</pre>

Note - To get the list of all acceptable arguments run <code>ipsec letsencrypt --help</code>

== Configuration Used ==

There are 2 default configurations, one for the server (<code>oe-letsencrypt-server.conf</code>) and other for the client (<code>oe-letsencrypt-client.conf</code>).

1. The server configuration (<code>oe-letsencrypt-server.conf</code>) is as follows:

'''Note - please add your server dns name in the place of''' <code>leftcert=YourServerDNSName</code>. E.g. <code>leftcert=letsencrypt.libreswan.org</code>

<pre>
conn clear-or-private
        leftid=%fromcert
        leftrsasigkey=%cert
        # name of your generated letsencrypt certificate e.g. letsencrypt.libreswan.org
        leftcert=YourServerDNSName
        leftauth=rsasig
        left=%defaultroute
        #leftmodecfgclient=yes
        #
        rightid=%null
        rightauth=null
        right=%opportunisticgroup
        #
        negotiationshunt=passthrough
        failureshunt=passthrough
        type=tunnel
        ikev2=insist
        sendca=issuer
        auto=add
        #
        rightaddresspool=100.64.0.1-100.64.255.254
        rightmodecfgclient=yes
</pre>


2. The client configuration (<code>oe-letsencrypt-client.conf</code>) is as follows:

<pre>
conn private-or-clear
    rightid=%fromcert
    rightrsasigkey=%cert
    rightauth=rsasig
    right=%opportunisticgroup
    rightmodecfgclient=yes
    rightcat=yes
    # Any CA will do because we only load the LetsEncrypt CA
    rightca=%any
    #
    left=%defaultroute
    leftid=%null
    leftauth=null
    leftmodecfgclient=yes
    leftcat=yes
    #
    narrowing=yes
    type=tunnel
    ikev2=insist
    negotiationshunt=drop
    failureshunt=passthrough
    keyingtries=1
    retransmit-timeout=3s
    auto=ondemand
</pre>

* The default configuration file <code>private-or-clear</code> present in /etc/ipsec.d/policies/ contains the following lines:
<pre>
# The libreswan letsenccrypt test server - this can be left enabled at all times
193.110.157.131/32
# Attempt OE IPsec using letsencrypt for the entire Internet - Comment out to disable
0.0.0.0/0
</pre>

If you are trying to connect to a server, you should add the IP of the server to this file OR another configuration file which is in use.

Note - The OE attempt to the entire internet is enabled by default. Which means, for every host, you try to connect the OE connection establishing is always attempted. You can disable this by commenting the line <code>0.0.0.0/0</code> .

== Functions of various [arguments] ==

Note - OE refers to Opportunistic Encryption.


1. <code>ipsec letsencrypt --client</code> 

2. <code>ipsec letsencrypt --server</code>

It is run for the initial setup when installing the project for the first time. The [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 the user.

Note - The command creates a secure Opportunistic Connection between the hosts commonly referred to as client and server. The client connects to the server and remains anonymous, whereas the server is authenticated before connecting to it. The server is not anonymous. The server uses Let's Encrypt certificates for authentication and encryption purposes.

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --client
Installing for Client.
Downloading the letsencrypt certificates
Importing the downloaded certificates into the database
Saving the required configuration
To confirm the success try running 'ipsec letsencrypt --test' on the client
</pre>


3. <code>ipsec letsencrypt --test</code>

For testing the configuration/connections. The [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.

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --test
Existing OE Connections Found. Please stop the connections using 'ipsec restart' and try again.
006 #4: "private-or-clear#193.110.157.131/32"[2] 100.64.0.1/32=== ...193.110.157.131, type=ESP, add_time=1565535553,
inBytes=0, outBytes=252, id='CN=letsencrypt.libreswan.org', lease=100.64.0.1/32
</pre>


4. <code>ipsec letsencrypt --generate-certificate hostname</code>

Note - hostname refers to the name of the host. e.g. <code>libreswan.org</code>. 

For generating the certificate. The [argument] generates 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.

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --generate-certificate letsencrypt.libreswan.org
Saving debug log to /var/log/letsencrypt/letsencrypt.libreswan.org
Plugins selected: Authenticator webroot, Installer None
Starting new HTTPS connection (1): acme-v02.api.letsencrypt.org
Please enter in your domain name(s) (comma and/or space separated)  (Enter 'c'
to cancel): letsencrypt.libreswan.org
Cert not yet due for renewal

You have an existing certificate that has the same domains or certificate name you requested and isn't close to expiry.
(ref: /etc/letsencrypt/renewal/letsencrypt.libreswan.org.conf)

What would you like to do?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: Keep the existing certificate for now
2: Renew & replace the cert (limit ~5 per 7 days)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Renewing an existing certificate

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/letsencrypt.libreswan.org/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/letsencrypt.libreswan.org/privkey.pem
   Your cert will expire on 2019-11-03. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

Enter Export Password:
Verifying - Enter Export Password:
Importing the certificate in database.
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

isrgrootx1                                                   CT,,
trustid-x3-root                                              CT,,
letsencryptauthorityx3                                       ,,   
lets-encrypt-x3-cross-signed                                 ,,   
letsencrypt.libreswan.org                                    u,u,u
To confirm the success try running 'ipsec letsencrypt -t' on the client
</pre>


5. <code>ipsec letsencrypt --renew hostname</code>

Note - 

1. hostname refers to the name of the host. e.g. <code>libreswan.org</code>. 

2. The above command is an alias to  <code>certbot renew --deploy-hook 'ipsec letsencrypt --update-certificate hostname'</code>

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.

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --renew letsencrypt.org
Saving debug log to /var/log/letsencrypt/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/letsencrypt.libreswan.org.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cert not yet due for renewal

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The following certs are not due for renewal yet:
  /etc/letsencrypt/live/letsencrypt.libreswan.org/fullchain.pem expires on 2019-11-03 (skipped)
No renewals were attempted.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Enter Export Password:
Verifying - Enter Export Password:
Importing the certificate in the database.
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL
Displaying the certificates installed in the database.

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

isrgrootx1                                                   CT,,
trustid-x3-root                                              CT,,
letsencryptauthorityx3                                       ,,   
lets-encrypt-x3-cross-signed                                 ,,   
letsencrypt.libreswan.org                                    u,u,u
To confirm the success try running 'ipsec letsencrypt -t' on the client
</pre>

6. <code>ipsec letsencrypt --disable</code>

The command disables the IPsec service by deleting all the configuration files present in /etc/ipsec.d/ directory. However, for it to take effect, one needs to restart the IPsec service.

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --disable
Please restart the IPsec service using 'ipsec restart' for changes to take effect.
</pre>


7. <code>ipsec letsencrypt --help</code>

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

Sample Output -
<pre>
[root@linux]# ipsec letsencrypt --help
Usage: ipsec letsencrypt [arguments]
Available [arguments]
--server, --client, --test, --generate-certificate hostname, --renew hostname, --help, --disable

--client :  For initial client setup.
usage: 'ipsec letsencrypt --client'

--server :  For initial server setup.
usage: 'ipsec letsencrypt --server'

--test  :  For testing the configuration/connections.
usage: 'ipsec letsencrypt --test'

--generate-certificate hostname :  For generating the certificate.
usage: 'ipsec letsencrypt --generate-certificate hostname'

--renew hostname: For updating the generated certificate (keeping the private key same) use the following command.
usage: 'ipsec letsencrypt --renew hostname'

--disable :  For disabling IPsec service.
usage: 'ipsec letsencrypt --disable'
</pre>


== Testing and Debugging ==

* To see all the active IPsec OE tunnels (and the amount of traffic encrypted)
<pre>
sudo ipsec whack --trafficstatus
</pre>

Sample Output -
<pre>
006 #4: "private-or-clear#193.110.157.131/32"[2] 100.64.0.1/32=== ...193.110.157.131, type=ESP, add_time=1565535553,
inBytes=0, outBytes=252, id='CN=letsencrypt.libreswan.org', lease=100.64.0.1/32
</pre>

Note - Inactive tunnels are torn down (once an hour) 

* To see all the IP addresses that were tried, but did not offer IPsec OE
<pre>
sudo ipsec whack --shuntstatus
</pre>

Sample Output -
<pre>
000 Bare Shunt list:
000  
</pre>

* To see the inside state of the libreswan pluto daemon
<pre>
sudo ipsec status
</pre>

Sample Output -
<pre>
000 using kernel interface: netkey
.
.
.
.
000 #4: "private-or-clear#193.110.157.131/32"[2] 100.64.0.1/32=== ...193.110.157.131 esp.affba9fa@193.110.157.131 
esp.a390a2a8@192.168.43.235 tun.0@193.110.157.131 tun.0@192.168.43.235 ref=0 refhim=0 Traffic: ESPin=0B ESPout=252B! ESPmax=0B 
000  
000 Bare Shunt list:
000  
</pre>

* To restart IPsec OE

Note - It will destroy all your existing OE connections.
<pre>
sudo ipsec restart
</pre>

* To verify IPsec (Libreswan) installation and check configuration files
<pre>
sudo ipsec verify
</pre>

Sample Output -
<pre>
Verifying installed system and configuration files

Version check and ipsec on-path                       [OK]
Libreswan 3.29 (netkey) on 5.1.20-300.fc30.x86_64
Checking for IPsec support in kernel                  [OK]
 NETKEY: Testing XFRM related proc values
         ICMP default/send_redirects                  [OK]
         ICMP default/accept_redirects                [OK]
         XFRM larval drop                             [OK]
Pluto ipsec.conf syntax                               [OK]
Checking rp_filter                                    [OK]
Checking that pluto is running                        [OK]
 Pluto listening for IKE on udp 500                   [OK]
 Pluto listening for IKE/NAT-T on udp 4500            [OK]
 Pluto ipsec.secret syntax                            [OK]
Checking 'ip' command                                 [OK]
Checking 'iptables' command                           [OK]
Checking 'prelink' command does not interfere with FIPS    [OK]
Checking for obsolete ipsec.conf options              [OK]
</pre>

* To delete the configuration files present in /etc/ipsec.d
<pre>
sudo ipsec letsencrypt --disable
</pre>

* Manual debug version of OE request 
<pre>
sudo ipsec restart
sleep 5
sudo ipsec whack --oppohere YOURIP --oppothere REMOTEIP 
</pre>

e.g. 
<pre>
sudo ipsec restart
sleep 5
ipsec whack --oppohere 169.149.111.125 --oppothere 193.110.157.131
</pre>

Sample Output -
<pre>
002 initiate on demand from 142.93.216.119:0 to 193.110.157.131:0 proto=0 because: whack
133 "private-or-clear#193.110.157.131/32"[1] ...193.110.157.131 #1: initiate
002 "private-or-clear#193.110.157.131/32"[1] ...193.110.157.131: constructed local IKE proposals for private-or-clear#193.110.157.131/326,
.
.
.
HMAC_SHA2_256_128; ESN=DISABLED 5:ESP:ENCR=AES_CBC_128;INTEG=HMAC_SHA1_96;ESN=DISABLED (default)
002 "private-or-clear#193.110.157.131/32"[1] ...193.110.157.131 #2: certificate verified OK: CN=letsencrypt.libreswan.org
003 "private-or-clear#193.110.157.131/32"[1] ...193.110.157.131 #2: Authenticated using RSA
002 "private-or-clear#193.110.157.131/32"[1] ...193.110.157.131 #2: negotiated connection [142.93.216.119-142.93.216.119:0-65535 0] -> 
[193.110.157.131-193.110.157.131:0-65535 0]
</pre>


== Common Errors ==

* no routed template covers this pair error while running the command <code>sudo ipsec whack --oppohere 76.10.157.68 --oppothere 1.2.3.4</code>

This is due to the fact that the target IP address (1.2.3.4) is not covered by <code>/etc/ipsec.d/policies/private*</code>

* Failed to establish an OE connection.

If you get this error, one of the possible reasons might be, you have more than one configuration(.conf) files in the /etc/ipsec.d directory.