diff --git a/docs/developer-guide/Kmeshctl-usage/kmeshctl-secret.md b/docs/developer-guide/Kmeshctl-usage/kmeshctl-secret.md index 13aa636f..85396857 100644 --- a/docs/developer-guide/Kmeshctl-usage/kmeshctl-secret.md +++ b/docs/developer-guide/Kmeshctl-usage/kmeshctl-secret.md @@ -1,27 +1,90 @@ --- -title: kmeshctl secret -sidebar_position: 6 +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 secrets to generate secret configuration data for IPsec +### Use IPsec in Kmesh cluster -```bash -kmeshctl secret [flags] +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 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= ``` -### Examples +If you want to randomly generate a key, you can use the following command ```bash -# Use secrets to generate secret configuration data for IPsec: - Use --key (or -k) with the AEAD algorithm rfc4106(gcm(aes)); the key must be 36 characters long (32 for key and 4 for salt). - A hexadecimal dump is required when the key is entered. - e.g.: kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) - e.g.: kmeshctl secret -k=$(echo -n "{36-character user-defined key here}" | xxd -p -c 64) +kmeshctl secret --key=$(dd if=/dev/urandom count=36 bs=1 2>/dev/null | xxd -p -c 64) ``` -### Options +If you want to use a custom key, you can use the following command -```bash - -h, --help help for secret - -k, --key string key of the encryption +``` bash +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 + +```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) + +```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. This can be observed again through using tcpdump. The initial IPSec SPI version number is 1 + +```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 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