[ISSUE #213] Supplement HTTPS/(m)TLSv1.3 document for HTTP Admin Server

docs/design-document/01-event-handling-and-integration/02-https.md

@@ -1,30 +1,96 @@
-# HTTPS
+# HTTPS/(m)TLSv1.3
 
-1. Configuration in eventmesh-runtime
+## Enable HTTPS in HTTP Admin Server
 
+### Create a Self-Signed Certificate (mTLS)
+
+EventMesh Runtime currently supports loading SSL certificate files in `jks` format. You can generate a `jks` certificate locally.
+
+```shell
+keytool -genkey -alias eventmesh-admin-server -keyalg RSA -keystore admin-server.jks
 ```
-eventMesh.properties (add the following configurations)
-eventMesh.server.useTls.enabled=true   // Default value: false
 
-Configuring environment variable
--Dssl.server.protocol=TLSv1.1   // Default value: TLSv1.1
--Dssl.server.cer=sChat2.jks     // Place the file in the conPath directory specified by the startup script start.sh
+The value of the `-alias` parameter is the hostname or domain name of your EventMesh Runtime node. You can set up a mapping relationship between the hostname/domain name and the IP address on the router/gateway/DNS server.
+
+Most web clients do not accept traffic from servers with self-signed certificates by default. If you trust this self-signed certificate and its network environment, you can allow the client to receive traffic from this self-signed certificate server.
+
+If you do not trust one-way authentication, you can also use two-way TLS (mTLS) to achieve zero-trust security. You need to configure the public key part of this SSL certificate on the client side, such as a `pem` file. The `jks` certificate can be converted to a `pem` file using the `keytool` command.
+
+After the configuration is complete, the effect is as follows:
+
+![mTLS](../../../static/images/design-document/https/mTLS.png)
+
+### Import Authority Certificate (TLS)
+
+You can convert the `nginx`/`apache` format `pem`/`crt`/`key` certificate issued by the authority into `jks` format and deploy it on the EventMesh Runtime server.
+
+This method can support more web clients, such as browsers, because no configuration is required on the web client side.
+
+After the configuration is complete, the effect is as follows:
+
+![TLS](../../../static/images/design-document/https/TLS.png)
+
+### Configuration on the eventmesh-runtime side
+
+Configure the following items in `eventmesh.properties`:
+
+```properties
+eventMesh.server.admin.useTls.enabled=true # default value false
+eventMesh.server.admin.ssl.protocol=TLSv1.3 # default value TLSv1.3, minimum support TLSv1.1
+eventMesh.server.admin.ssl.cer=admin-server.jks # place the file in the confPath directory specified in the start.sh startup script, by default in the same directory as eventmesh.properties
+eventMesh.server.admin.ssl.pass=eventmesh-admin-server
+```
+
+### JDK/JRE 8 Compatibility
+
+Most mainstream distributions of JDK/JRE 8 support TLSv1.3, such as the following versions:
+
+- [Oracle 8u261](https://www.oracle.com/java/technologies/javase/8u261-relnotes.html#JDK-8145252) or higher (released in July 2020)
+- [Azul Zulu 8u262](https://www.azul.com/newsroom/azul-systems-brings-updated-transport-layer-security-to-java-se-8/) or higher (released in July 2019)
+- [Amazon Corretto 8u272](https://aws.amazon.com/cn/about-aws/whats-new/2020/10/amazon-corretto-quarterly-updates-now-available/) or higher (released in October 2020)
+
+EventMesh has TLSv1.3 enabled by default through `SSLContext` configuration, so you don't need to add the `jdk.tls.client.protocols` JVM option.
+
+If your JDK/JRE 8 version does not support TLSv1.3, you can lower the TLS version of the `eventMesh.server.admin.ssl.protocol` property.
+
+## Enable TLS in SDK
+
+### Configuration on the eventmesh-runtime side
+
+Configure the following items in `eventmesh.properties`:
+
+```properties
+eventMesh.server.useTls.enabled=true # default value false
+eventMesh.server.ssl.protocol=TLSv1.1 # default value TLSv1.1, maximum support TLSv1.3
+eventMesh.server.ssl.cer=sChat2.jks # place the file in the confPath directory specified in the start.sh startup script, by default in the same directory as eventmesh.properties
+eventMesh.server.ssl.pass=sNetty
+```
+
+You can also configure the certificate and key through environment variables:
+
+```properties
+-Dssl.server.protocol=TLSv1.1
+-Dssl.server.cer=sChat2.jks
 -Dssl.server.pass=sNetty
 ```
 
-2. Configuration in eventmesh-sdk-java
+### Configuration on the eventmesh-sdk-java side
 
+```java
+// Create producer
+LiteClientConfig eventMeshHttpClientConfig = new eventMeshHttpClientConfig();
 ```
-// Create a producer
-LiteClientConfig eventMeshHttpClientConfig = new LiteClientConfig();
-...
 
-// Enable TLS
+```java
+// Set to enable TLS
 eventMeshHttpClientConfig.setUseTls(true);
 LiteProducer producer = new LiteProducer(eventMeshHttpClientConfig);
+```
+
+Configure environment variables:
 
-// Configure environment variables
--Dssl.client.protocol=TLSv1.1   // Default value: TLSv1.1
--Dssl.client.cer=sChat2.jks     // Place the file in the conPath directory specified by the application
+```properties
+-Dssl.client.protocol=TLSv1.1
+-Dssl.client.cer=sChat2.jks
 -Dssl.client.pass=sNetty
 ```

i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-event-handling-and-integration/02-https.md

@@ -1,30 +1,96 @@
-# HTTPS
+# HTTPS/(m)TLSv1.3
 
-1. 在 eventmesh-runtime 中配置
+## 在 HTTP Admin Server 中启用 HTTPS
 
+### 创建自签名证书 (mTLS)
+
+EventMesh Runtime 目前支持加载`jks`格式的 SSL 证书文件。您可以在本地生成`jks`证书。
+
+```shell
+keytool -genkey -alias eventmesh-admin-server -keyalg RSA -keystore admin-server.jks
 ```
-eventMesh.properties （添加如下配置）
-eventMesh.server.useTls.enabled=true   // 默认值 false
 
-config env varible
--Dssl.server.protocol=TLSv1.1   // 默认值 TLSv1.1
--Dssl.server.cer=sChat2.jks     // 把文件放到启动脚本 start.sh 指定的 conPath 目录下
--Dssl.server.pass=sNetty
+`-alias`参数的值即为您 EventMesh Runtime 节点的主机名或域名。您可以在路由/网关/DNS 服务器上设置主机名/域名与 IP 地址的映射关系。
+
+大多数 Web 客户端默认不接收来自自签名证书服务器的流量。如果您信任此自签名证书及其所处的网络环境，可以允许客户端接收来自此自签名证书服务器的流量。
+
+如果您不信任单向身份验证，您也可以使用双向 TLS (mTLS) 实现零信任安全。您需要在客户端侧配置此 SSL 证书的公钥部分，例如`pem`文件。`jks`证书可以使用`keytool`命令转换为`pem`文件。
+
+配置完成后，效果如下：
+
+![mTLS](../../../../../../static/images/design-document/https/mTLS.png)
+
+### 导入权威证书 (TLS)
+
+您可以将权威机构签发的`nginx`/`apache`格式的`pem`/`crt`/`key`证书转换为`jks`格式，并部署在 EventMesh Runtime 服务器上。
+
+这种方式可以支持更多的 Web 客户端，例如浏览器，因为无需在 Web 客户端侧进行任何配置。
+
+配置完成后，效果如下：
+
+![TLS](../../../../../../static/images/design-document/https/TLS.png)
+
+###  eventmesh-runtime 侧配置
+
+配置 `eventmesh.properties` 中的以下条目：
+
+```properties
+eventMesh.server.admin.useTls.enabled=true # 默认值 false
+eventMesh.server.admin.ssl.protocol=TLSv1.3 # 默认值 TLSv1.3，最低支持 TLSv1.1
+eventMesh.server.admin.ssl.cer=admin-server.jks # 将文件置于启动脚本 start.sh 中指定的 confPath 目录，默认与 eventmesh.properties 同目录
+eventMesh.server.admin.ssl.pass=eventmesh-admin-server
+```
+
+### JDK/JRE 8 兼容性
+
+大部分主流 JDK/JRE 8 发行版支持 TLSv1.3，例如以下版本：
+
+- [Oracle 8u261](https://www.oracle.com/java/technologies/javase/8u261-relnotes.html#JDK-8145252) 或更高（发布于 2020 年 7 月）
+- [Azul Zulu 8u262](https://www.azul.com/newsroom/azul-systems-brings-updated-transport-layer-security-to-java-se-8/) 或更高（发布于 2019 年 7 月）
+- [Amazon Corretto 8u272](https://aws.amazon.com/cn/about-aws/whats-new/2020/10/amazon-corretto-quarterly-updates-now-available/) 或更高（发布于 2020 年 10 月）
+
+EventMesh 已通过`SSLContext `配置默认启用 TLSv1.3，无需您添加`jdk.tls.client.protocols`JVM 选项。
+
+如果您的 JDK/JRE 8 版本不支持 TLSv1.3，可以降低`eventMesh.server.admin.ssl.protocol`属性的 TLS 版本。
+
+## 在 SDK 中启用 TLS
+
+### eventmesh-runtime 侧配置
+
+配置 `eventmesh.properties` 中的以下条目：
+
+```properties
+eventMesh.server.useTls.enabled=true # 默认值 false
+eventMesh.server.ssl.protocol=TLSv1.1 # 默认值 TLSv1.1，最高支持 TLSv1.3
+eventMesh.server.ssl.cer=sChat2.jks # 将文件置于启动脚本 start.sh 中指定的 confPath 目录，默认与 eventmesh.properties 同目录
+eventMesh.server.ssl.pass=sNetty
 ```
 
-2. 在 eventmesh-sdk-java 中配置
+您也可以通过环境变量来配置证书和密钥：
 
+```properties
+-Dssl.server.protocol=TLSv1.1
+-Dssl.server.cer=sChat2.jks
+-Dssl.server.pass=sNetty
 ```
+
+### eventmesh-sdk-java 侧配置
+
+```java
 // 创建 producer
 LiteClientConfig eventMeshHttpClientConfig = new eventMeshHttpClientConfig();
-...
+```
 
+```java
 // 设置开启 TLS
 eventMeshHttpClientConfig.setUseTls(true);
 LiteProducer producer = new LiteProducer(eventMeshHttpClientConfig);
+```
 
-// 配置环境变量
--Dssl.client.protocol=TLSv1.1   // 默认值 TLSv1.1
--Dssl.client.cer=sChat2.jks     // 把文件放到应用指定的 conPath 目录下
+配置环境变量：
+
+```properties
+-Dssl.client.protocol=TLSv1.1
+-Dssl.client.cer=sChat2.jks
 -Dssl.client.pass=sNetty
-```
+```