libbsd.txt: Add ipsec.

1 files changed, 128 insertions, 0 deletions

diff --git a/libbsd.txt b/libbsd.txt
index c7a90f64..ba0ab2c4 100644
--- a/libbsd.txt
+++ b/libbsd.txt
@@ -1233,6 +1233,134 @@ workaround is to just restart it every time it exits.
 - The control interface of wpa_supplicant most likely doesn't work. The wpa_cli
   application is not ported.
 
+== IPSec ==
+
+The IPSec support is optional in libbsd. It is disabled in the default build
+set. Please make sure to use a build set with +netipsec = on+.
+
+To use IPSec the following configuration is necessary:
+
+----
+SYSINIT_MODULE_REFERENCE(if_gif);
+SYSINIT_MODULE_REFERENCE(cryptodev);
+RTEMS_BSD_RC_CONF_SYSINT(rc_conf_ipsec)
+RTEMS_BSD_DEFINE_NEXUS_DEVICE(cryptosoft, 0, 0, NULL);
+----
+
+Alternatively you can use the `RTEMS_BSD_CONFIG_IPSEC` which also includes the
+rc.conf support for ipsec. It's still necessary to include a crypto device in
+your config (`cryptosoft` in the above sample).
+
+The necessary initialization steps for a IPSec connection are similar to the
+steps on a FreeBSD-System. The example assumes the following setup:
+
+- RTEMS external IP: 192.168.10.1/24
+- RTEMS internal IP: 10.10.1.1/24
+- remote external IP: 192.168.10.10/24
+- remote internal IP: 172.24.0.1/24
+- shared key: "mysecretkey"
+
+With this the following steps are necessary:
+
+- Create a gif0 device:
+
+----
+SHLL [/] #  ifconfig gif0 create
+----
+
+- Configure the gif0 device:
+
+----
+SHLL [/] # ifconfig gif0 10.10.1.1 172.24.0.1
+SHLL [/] # ifconfig gif0 tunnel 192.168.10.1 192.168.10.10
+----
+
+- Add a route to the remote net via the remote IP:
+
+----
+SHLL [/] # route add 172.24.0.0/24 172.24.0.1
+----
+
+- Call `setkey` with a correct rule set:
+
+----
+SHLL [/] # cat /etc/setkey.conf
+flush;
+spdflush;
+spdadd  10.10.1.0/24 172.24.0.0/24 any -P out ipsec esp/tunnel/192.168.10.1-192.168.10.10/use;
+spdadd 172.24.0.0/24  10.10.1.0/24 any -P in  ipsec esp/tunnel/192.168.10.10-192.168.10.1/use;
+SHLL [/] # setkey -f /etc/setkey.conf
+----
+
+- Start a ike-daemon (racoon) with a correct configuration.
+----
+SHLL [/] # cat /etc/racoon.conf
+path	pre_shared_key "/etc/racoon_psk.txt";
+log	info;
+
+padding # options are not to be changed
+{
+	maximum_length			20;
+	randomize			off;
+	strict_check			off;
+	exclusive_tail			off;
+}
+
+listen  # address [port] that racoon will listen on
+{
+	isakmp				192.168.10.1[500];
+}
+
+remote 192.168.10.10 [500]
+{
+	exchange_mode			main;
+	my_identifier			address 192.168.10.1;
+	peers_identifier		address 192.168.10.10;
+	proposal_check			obey;
+	
+	proposal {
+		encryption_algorithm	3des;
+		hash_algorithm		md5;
+		authentication_method	pre_shared_key;
+		lifetime		time 3600 sec;
+		dh_group		2;
+	}
+}
+
+sainfo (address 10.10.1.0/24 any address 172.24.0.0/24 any)
+{
+	pfs_group			2;
+	lifetime			time 28800 sec;
+	encryption_algorithm		3des;
+	authentication_algorithm	hmac_md5;
+	compression_algorithm		deflate;
+}
+SHLL [/] # cat /etc/racoon_psk.txt
+192.168.10.10	mysecretkey
+SHLL [/] # racoon -F -f /etc/racoon.conf
+----
+
+All commands can be called via the respective API functions. For racoon there is
+a `rtems_bsd_racoon_daemon()` function that forks of racoon as a task.
+
+Alternatively IPSec can also be configured via rc.conf entries:
+
+----
+cloned_interfaces="gif0"
+ifconfig_gif0="10.10.1.1 172.24.0.1 tunnel 192.168.10.1 192.168.10.10"
+ike_enable="YES"
+ike_program="racoon"
+ike_flags="-F -f /etc/racoon.conf"
+ike_priority="250"
+
+ipsec_enable="YES"
+ipsec_file="/etc/setkey.conf"
+----
+
+ATTENTION: It is possible that the first packets slip through the tunnel without
+encryption (true for FreeBSD as well as RTEMS). You might want to set up a
+firewall rule to prevent that.
+
 == Problems to report to FreeBSD ==
 
 The MMAP_NOT_AVAILABLE define is inverted on its usage.  When it is