From 452d935554f8abe95ccf037c2e960dca9808b7c3 Mon Sep 17 00:00:00 2001 From: bitcoffee Date: Wed, 8 Jan 2025 12:38:55 +0800 Subject: [PATCH 1/5] ipsec: add ipsec user guide Signed-off-by: bitcoffee --- .../userguide/use_IPsec_in_Kmesh_cluster.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md diff --git a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md new file mode 100644 index 00000000..7749f4de --- /dev/null +++ b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md @@ -0,0 +1,84 @@ +--- +draft: true +linktitle: use IPsec in Kmesh cluster +menu: + docs: + parent: user guide + weight: 21 +title: use IPsec in Kmesh cluster +toc: true +type: docs + +--- + +### Use IPsec in Kmesh cluster + +IPsec is a mature and widely used encryption method for inter node communication. This document explains how to enable IPsec for two Kmesh managed nodes in a Kmesh cluster to encrypt communication data between both parties. + +### How to enable IPsec in Kmesh + +**Step 1: Generate an IPsec pre shared key for Kmesh before starting the Kmesh by kmeshctl. Currently, only the rfc4106 (gcm (AES)) algorithm is supported. key need 36 characters(32 character as algo key, 4 character as salt)** + + root@master:~/kmesh# ./kmeshctl secret --key= + +or + + root@master:~/kmesh# ./kmeshctl secret --k= + +If you want to randomly generate a key, you can use the following command + + root@master:~/kmesh# ./kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) + +If you want use custom key, you can use the following command + + root@master:~/kmesh# ./kmeshctl secret --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) + +**Step 2: Install the specified CRD type** + + root@master:~/kmesh# kubectl apply -f deploy/yaml/crd/kmesh.net_kmeshnodeinfos.yaml + +**Step 3: Add the parameter --enable-ipsec=true to the Kmesh yaml** + + kmesh.yaml + ... + args: + [ + "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", + ] + ... + +**Step 4: Place pods or namespace under the management of Kmesh.** + +Only when both communicating pods are managed by Kmesh, will they enter the encryption process. + + root@master:~/kmesh# kubectl label namespace default istio.io/dataplane-mode=Kmesh + +**Step 5: Test whether the data packet has been encrypted** + +Use tcpdump on nodes to capture packets and check if IPsec has been used during data communication between nodes (determined by ESP packets) + + root@master:~/kmesh# tcpdump -i any |grep ESP + ... + 14:19:24.143654 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da88), length 80 + 14:19:24.143690 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da89), length 80 + 14:19:24.143707 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c037), length 80 + 14:19:24.143738 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c038), length 172 + ... + +**Step 6: Replace pre shared key** + +After a period of time, the pre shared key of the cluster can be changed. After changing the pre shared key, the ESP SPI number of the IPsec used for communication between nodes will be increased by 1 compared to the previous version. You can be observed again through tcpdump. The initial IPSec SPI version number is 1 + + root@master:~/kmesh# tcpdump -i any |grep ESP + ... + 14:26:33.782665 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa1), length 80 + 14:26:33.782666 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa2), length 80 + 14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d2), length 80 + 14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d3), length 80 + ... + +### Note + +1、 IPsec encryption uses mark `0xe0` and `0xd0` as markers for IPsec encryption and decryption. Please ensure that no conflicting Makr is used on the host network, otherwise unknown behavior may occur + +2、Please ensure that `address MASQ` is not used on packets encrypted with IPsec. After address MASQ, IPsec cannot accurately match encryption and decryption rules, which can result in packet loss From 6e7cc6a08587bea399189304c73ccf7470982ccc Mon Sep 17 00:00:00 2001 From: aicee Date: Fri, 25 Jul 2025 16:31:47 +0800 Subject: [PATCH 2/5] modified ipsec userguide accordding to the review of pr105 Signed-off-by: aicee --- .../userguide/use_IPsec_in_Kmesh_cluster.md | 38 ++++++++----------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md index 7749f4de..8f74d03c 100644 --- a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md +++ b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md @@ -18,26 +18,20 @@ IPsec is a mature and widely used encryption method for inter node communication ### How to enable IPsec in Kmesh **Step 1: Generate an IPsec pre shared key for Kmesh before starting the Kmesh by kmeshctl. Currently, only the rfc4106 (gcm (AES)) algorithm is supported. key need 36 characters(32 character as algo key, 4 character as salt)** - - root@master:~/kmesh# ./kmeshctl secret --key= - -or - - root@master:~/kmesh# ./kmeshctl secret --k= +``` bash +kmeshctl secret --key= +``` If you want to randomly generate a key, you can use the following command - - root@master:~/kmesh# ./kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) - +```bash +kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) +``` If you want use custom key, you can use the following command +``` bash +kmeshctl secret --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) +``` - root@master:~/kmesh# ./kmeshctl secret --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) - -**Step 2: Install the specified CRD type** - - root@master:~/kmesh# kubectl apply -f deploy/yaml/crd/kmesh.net_kmeshnodeinfos.yaml - -**Step 3: Add the parameter --enable-ipsec=true to the Kmesh yaml** +**Step 2: Add the parameter --enable-ipsec=true to the Kmesh yaml** kmesh.yaml ... @@ -47,13 +41,13 @@ If you want use custom key, you can use the following command ] ... -**Step 4: Place pods or namespace under the management of Kmesh.** +**Step 3: Place pods or namespace under the management of Kmesh.** Only when both communicating pods are managed by Kmesh, will they enter the encryption process. - - root@master:~/kmesh# kubectl label namespace default istio.io/dataplane-mode=Kmesh - -**Step 5: Test whether the data packet has been encrypted** +``` bash +kubectl label namespace default istio.io/dataplane-mode=Kmesh +``` +**Step 4: Test whether the data packet has been encrypted** Use tcpdump on nodes to capture packets and check if IPsec has been used during data communication between nodes (determined by ESP packets) @@ -65,7 +59,7 @@ Use tcpdump on nodes to capture packets and check if IPsec has been used during 14:19:24.143738 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c038), length 172 ... -**Step 6: Replace pre shared key** +**Step 5: Replace pre shared key** After a period of time, the pre shared key of the cluster can be changed. After changing the pre shared key, the ESP SPI number of the IPsec used for communication between nodes will be increased by 1 compared to the previous version. You can be observed again through tcpdump. The initial IPSec SPI version number is 1 From fa0c23dab1533a8a083cf371e42e73c0bc7e2cd9 Mon Sep 17 00:00:00 2001 From: aicee Date: Mon, 28 Jul 2025 09:18:46 +0800 Subject: [PATCH 3/5] revise ipsec userguide Signed-off-by: aicee --- .../userguide/use_IPsec_in_Kmesh_cluster.md | 72 +++++++++++-------- 1 file changed, 42 insertions(+), 30 deletions(-) diff --git a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md index 8f74d03c..6b154a36 100644 --- a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md +++ b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md @@ -1,11 +1,11 @@ --- draft: true -linktitle: use IPsec in Kmesh cluster +linktitle: Use IPsec in Kmesh cluster menu: docs: parent: user guide weight: 21 -title: use IPsec in Kmesh cluster +title: Use IPsec in Kmesh cluster toc: true type: docs @@ -13,66 +13,78 @@ type: docs ### Use IPsec in Kmesh cluster -IPsec is a mature and widely used encryption method for inter node communication. This document explains how to enable IPsec for two Kmesh managed nodes in a Kmesh cluster to encrypt communication data between both parties. +IPsec is a mature and widely used encryption method for inter-node communication. This document explains how to enable IPsec to encrypt communication data between Kmesh-managed nodes. ### How to enable IPsec in Kmesh -**Step 1: Generate an IPsec pre shared key for Kmesh before starting the Kmesh by kmeshctl. Currently, only the rfc4106 (gcm (AES)) algorithm is supported. key need 36 characters(32 character as algo key, 4 character as salt)** +**Step 1: Generate an IPsec pre-shared key for Kmesh before starting Kmesh. Currently, only the rfc4106 (gcm(AES)) algorithm is supported. The key must be 36 bytes (32 bytes for the algorithm key and 4 bytes for the salt), provided as a 72-character hexadecimal string.** + ``` bash kmeshctl secret --key= ``` If you want to randomly generate a key, you can use the following command + ```bash kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) ``` -If you want use custom key, you can use the following command + +If you want to use a custom key, you can use the following command + ``` bash -kmeshctl secret --key=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) +kmeshctl secret --key=$(echo -n "{36-bytes user-defined key here}" | xxd -p -c 64) ``` **Step 2: Add the parameter --enable-ipsec=true to the Kmesh yaml** - kmesh.yaml - ... - args: - [ - "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", - ] - ... +```plaintext +kmesh.yaml +... + args: + [ + "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", + ] +... +``` **Step 3: Place pods or namespace under the management of Kmesh.** Only when both communicating pods are managed by Kmesh, will they enter the encryption process. + ``` bash kubectl label namespace default istio.io/dataplane-mode=Kmesh ``` + **Step 4: Test whether the data packet has been encrypted** Use tcpdump on nodes to capture packets and check if IPsec has been used during data communication between nodes (determined by ESP packets) - root@master:~/kmesh# tcpdump -i any |grep ESP - ... - 14:19:24.143654 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da88), length 80 - 14:19:24.143690 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da89), length 80 - 14:19:24.143707 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c037), length 80 - 14:19:24.143738 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c038), length 172 - ... +```plaintext +tcpdump -i any |grep ESP +... +14:19:24.143654 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da88), length 80 +14:19:24.143690 ? Out IP master > node1: ESP(spi=0x00000001,seq=0x3da89), length 80 +14:19:24.143707 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c037), length 80 +14:19:24.143738 ? In IP node1 > master: ESP(spi=0x00000001,seq=0x3c038), length 172 +... +``` **Step 5: Replace pre shared key** -After a period of time, the pre shared key of the cluster can be changed. After changing the pre shared key, the ESP SPI number of the IPsec used for communication between nodes will be increased by 1 compared to the previous version. You can be observed again through tcpdump. The initial IPSec SPI version number is 1 +After a period of time, the pre-shared key of the cluster can be changed. After changing the pre-shared key, the ESP SPI number of the IPsec used for communication between nodes will be increased by 1 compared to the previous version. This can be observed again through using tcpdump. The initial IPSec SPI version number is 1 - root@master:~/kmesh# tcpdump -i any |grep ESP - ... - 14:26:33.782665 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa1), length 80 - 14:26:33.782666 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa2), length 80 - 14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d2), length 80 - 14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d3), length 80 - ... +```plaintext +root@master:~/kmesh# tcpdump -i any |grep ESP +... +14:26:33.782665 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa1), length 80 +14:26:33.782666 ? Out IP master > node1: ESP(spi=0x00000002,seq=0x1aaa2), length 80 +14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d2), length 80 +14:26:33.782667 ? In IP node1 > master: ESP(spi=0x00000002,seq=0x183d3), length 80 +... +``` ### Note -1、 IPsec encryption uses mark `0xe0` and `0xd0` as markers for IPsec encryption and decryption. Please ensure that no conflicting Makr is used on the host network, otherwise unknown behavior may occur +1. IPsec encryption uses mark `0xe0` and `0xd0` as markers for IPsec encryption and decryption. Please ensure that no conflicting Makr is used on the host network, otherwise unknown behavior may occur -2、Please ensure that `address MASQ` is not used on packets encrypted with IPsec. After address MASQ, IPsec cannot accurately match encryption and decryption rules, which can result in packet loss +2. Please ensure that `address MASQ` is not used on packets encrypted with IPsec. After address MASQ, IPsec cannot accurately match encryption and decryption rules, which can result in packet loss From 0188b2b63396c7a7db12b9cd8fb9e7eb699c9fbe Mon Sep 17 00:00:00 2001 From: aicee Date: Mon, 28 Jul 2025 09:21:36 +0800 Subject: [PATCH 4/5] revise ipsec userguide Signed-off-by: aicee --- content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md index 6b154a36..69ae8889 100644 --- a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md +++ b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md @@ -40,10 +40,10 @@ kmeshctl secret --key=$(echo -n "{36-bytes user-defined key here}" | xxd -p -c 6 ```plaintext kmesh.yaml ... - args: - [ - "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", - ] +args: +[ + "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", +] ... ``` From f06c1c5ae179a8a13f1cb7204f46d23f091b3ccc Mon Sep 17 00:00:00 2001 From: aicee Date: Mon, 25 Aug 2025 10:04:01 +0800 Subject: [PATCH 5/5] fix markdownlint err Signed-off-by: aicee --- .../docs/userguide/use_IPsec_in_Kmesh_cluster.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md index 69ae8889..85396857 100644 --- a/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md +++ b/content/en/docs/userguide/use_IPsec_in_Kmesh_cluster.md @@ -17,7 +17,7 @@ IPsec is a mature and widely used encryption method for inter-node communication ### How to enable IPsec in Kmesh -**Step 1: Generate an IPsec pre-shared key for Kmesh before starting Kmesh. Currently, only the rfc4106 (gcm(AES)) algorithm is supported. The key must be 36 bytes (32 bytes for the algorithm key and 4 bytes for the salt), provided as a 72-character hexadecimal string.** +#### Step 1: Generate an IPsec pre-shared key for Kmesh before starting Kmesh. Currently, only the rfc4106 (gcm(AES)) algorithm is supported. The key must be 36 bytes (32 bytes for the algorithm key and 4 bytes for the salt), provided as a 72-character hexadecimal string ``` bash kmeshctl secret --key= @@ -35,19 +35,19 @@ If you want to use a custom key, you can use the following command kmeshctl secret --key=$(echo -n "{36-bytes user-defined key here}" | xxd -p -c 64) ``` -**Step 2: Add the parameter --enable-ipsec=true to the Kmesh yaml** +#### Step 2: Add the parameter --enable-ipsec=true to the Kmesh yaml ```plaintext kmesh.yaml ... args: [ - "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", + "./start_kmesh.sh --mode=dual-engine --enable-bypass=false --enable-ipsec=true", ] ... ``` -**Step 3: Place pods or namespace under the management of Kmesh.** +#### Step 3: Place pods or namespace under the management of Kmesh Only when both communicating pods are managed by Kmesh, will they enter the encryption process. @@ -55,7 +55,7 @@ Only when both communicating pods are managed by Kmesh, will they enter the encr kubectl label namespace default istio.io/dataplane-mode=Kmesh ``` -**Step 4: Test whether the data packet has been encrypted** +#### Step 4: Test whether the data packet has been encrypted Use tcpdump on nodes to capture packets and check if IPsec has been used during data communication between nodes (determined by ESP packets) @@ -69,7 +69,7 @@ tcpdump -i any |grep ESP ... ``` -**Step 5: Replace pre shared key** +#### Step 5: Replace pre shared key After a period of time, the pre-shared key of the cluster can be changed. After changing the pre-shared key, the ESP SPI number of the IPsec used for communication between nodes will be increased by 1 compared to the previous version. This can be observed again through using tcpdump. The initial IPSec SPI version number is 1 @@ -85,6 +85,6 @@ root@master:~/kmesh# tcpdump -i any |grep ESP ### Note -1. IPsec encryption uses mark `0xe0` and `0xd0` as markers for IPsec encryption and decryption. Please ensure that no conflicting Makr is used on the host network, otherwise unknown behavior may occur +1. IPsec encryption uses mark `0xe0` and `0xd0` as markers for IPsec encryption and decryption. Please ensure that no conflicting Mark is used on the host network, otherwise unknown behavior may occur 2. Please ensure that `address MASQ` is not used on packets encrypted with IPsec. After address MASQ, IPsec cannot accurately match encryption and decryption rules, which can result in packet loss