From 40891cb9f9f6a9a7af1dfbdc4215fffdf5231e78 Mon Sep 17 00:00:00 2001
From: Gris Ge <fge@redhat.com>
Date: Thu, 14 Dec 2023 21:05:46 +0800
Subject: [PATCH] Add IPsec document

Signed-off-by: Gris Ge <fge@redhat.com>
---
 devel/yaml_api.md | 65 +++++++++++++++++++++++++++++++++++++++
 features/ipsec.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++
 index.md          |  1 +
 3 files changed, 144 insertions(+)
 create mode 100644 features/ipsec.md

diff --git a/devel/yaml_api.md b/devel/yaml_api.md
index 2cadb44..88fc16c 100644
--- a/devel/yaml_api.md
+++ b/devel/yaml_api.md
@@ -67,6 +67,7 @@
         * [IP over InfiniBand Interface](#ip-over-infiniband-interface)
         * [Virtual Routing and Forwarding (VRF) Interface](#virtual-routing-and-forwarding-vrf-interface)
         * [Linux Virtual Ethernet(veth) Interface](#linux-virtual-ethernetveth-interface)
+        * [IPsec Encryption](#ipsec-encryption)
     * [Routes](#routes)
     * [Route Rules](#route-rules)
     * [DNS Resolver](#dns-resolver)
@@ -1351,6 +1352,70 @@ interfaces:
     peer: veth1peer
 ```
 
+### IPsec Encryption
+
+New feature in 2.2.21
+
+Nmstate is using [Libreswan][libreswan_url] daemon and
+`NetworkManager-libreswan` for IPsec encryption communication.
+
+This is an example of X509 based authentication IPsec connection:
+
+```yml
+---
+interfaces:
+- name: hosta_conn
+  type: ipsec
+  ipv4:
+    enabled: true
+    dhcp: true
+  libreswan:
+    right: 192.0.2.252
+    rightid: '@hostb.example.org'
+    left: 192.0.2.251
+    leftid: '%fromcert'
+    leftcert: hosta.example.org
+    ikev2: insist
+```
+
+The `libreswan` section, nmstate provides these properties:
+ * `ipsec-interface`: String 'yes' or 'no' or unsigned integer.
+ * `authby`: Authentication method. Normally you don't need to set it.
+ * `dpddelay`: Integer.
+ * `dpdtimeout`: Integer.
+ * `dpdaction`: String.
+ * `ikelifetime`: String.
+ * `salifetime`: String.
+ * `ikev2`: String.
+ * `ike`: String.
+ * `esp`: String.
+ * `right`: String.
+ * `rightid`: String.
+ * `rightrsasigkey`: String.
+ * `left`: String.
+ * `leftid`: String.
+ * `leftrsasigkey`: String.
+ * `leftcert`: String.
+ * `ikev2`: String.
+ * `psk`: String. The Pre-Shared-Key. Please consider to use x509/PKI
+   authentication in production system. In query, this property will be
+   shown as `<_password_hid_by_nmstate>` for security concern.
+
+Except the `psk` property, all other properties are libreswan specific options,
+please refer to the manpage of `ipsec.conf` for detail meaning of them.
+
+By default, nmstate will not create any virtual NIC representing the encrypted
+communication, they can be check via `ip xfrm policy` command. The IP provided
+by IPsec remote will be assigned the interface hosting the underneath network
+flow.
+
+If you prefer a logical interface holding encrypted communication, please set
+`ipsec-interface` to `'yes'` or a unsigned integer number, then a xfrm logical
+interface named `ipsec<number` will be created holding the IP retrieved from
+IPsec remote.
+
+You may also check [IPsec example page](../features/ipsec.md) for use cases.
+
 ## Routes
 
 The `routes` top section of network state contains two type routes:
diff --git a/features/ipsec.md b/features/ipsec.md
new file mode 100644
index 0000000..07c6a5b
--- /dev/null
+++ b/features/ipsec.md
@@ -0,0 +1,78 @@
+<!-- vim-markdown-toc GFM -->
+
+    * [IPsec x509/PKI authentication example](#ipsec-x509pki-authentication-example)
+* [IPsec RSA authentication example](#ipsec-rsa-authentication-example)
+* [IPsec PSK authentication example](#ipsec-psk-authentication-example)
+
+<!-- vim-markdown-toc -->
+
+#### IPsec x509/PKI authentication example
+
+```yml
+---
+interfaces:
+- name: hosta_conn
+  type: ipsec
+  ipv4:
+    enabled: true
+    dhcp: true
+  libreswan:
+    ipsec-interface: "99"
+    left: 192.0.2.251
+    leftid: '%fromcert'
+    leftcert: hosta.example.org
+    right: 192.0.2.151
+    rightid: '%fromcert'
+    ikev2: insist
+    ikelifetime: 24h
+    salifetime: 24h
+```
+
+The PKI key should be imported by `ipsec import` command or other NSS tools.
+
+### IPsec RSA authentication example
+
+
+```yml
+---
+interfaces:
+- name: hosta_conn
+  type: ipsec
+  ipv4:
+    enabled: true
+    dhcp: true
+  libreswan:
+    ipsec-interface: "99"
+    leftrsasigkey: 0sAwEAAesFfVZqFzRA9F
+    left: 192.0.2.250
+    leftid: 'hosta-rsa.example.org'
+    right: 192.0.2.150
+    rightrsasigkey: 0sAwEAAesFfVZqFzRA9E
+    rightid: 'hostb-rsa.example.org'
+    ikev2: insist
+```
+
+The `rightrsasigkey` and `leftrsasigkey` could be retrieved by
+`ipsec showhostkey --right --ckaid <CKAID>` command.
+
+### IPsec PSK authentication example
+
+```yml
+---
+interfaces:
+  - name: hosta_conn
+    type: ipsec
+    ipv4:
+      enabled: true
+      dhcp: true
+    libreswan:
+      ipsec-interface: "99"
+      right: 192.0.2.153
+      rightid: 'hostb-psk.example.org'
+      left: 192.0.2.250
+      leftid: 'hosta-psk.example.org'
+      psk: "JjyNzrnHTnMqzloKaMuq2uCfJvSSUqTYdAXqD2U2OCFyVIJUUEHmXihBbPrUcmik"
+      ikev2: insist
+```
+
+The PSK method should be only used for test/develop purpose.
diff --git a/index.md b/index.md
index a4c8231..0fc7190 100644
--- a/index.md
+++ b/index.md
@@ -32,6 +32,7 @@ NetworkManager acts as the main (and currently the only) provider supported.
 - [Conditional compiling](./features/conditional_compile.md)
 - [Refer SR-IOV VF via PF name and VF ID](./features/iface_vf_id.md)
 - [Refer Interface using MAC Address](./features/mac_identifier.md)
+- [IPsec](./features/ipsec.md)
 
 ## Example output