diff --git a/docs/design-document/01-event-handling-and-integration/02-https.md b/docs/design-document/01-event-handling-and-integration/02-https.md index 8dcd90ee37..71af94ce91 100644 --- a/docs/design-document/01-event-handling-and-integration/02-https.md +++ b/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 ``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-event-handling-and-integration/02-https.md b/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-event-handling-and-integration/02-https.md index 5b6cfe9109..0fb5c36a58 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/design-document/01-event-handling-and-integration/02-https.md +++ b/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 -``` \ No newline at end of file +``` diff --git a/static/images/design-document/https/TLS.png b/static/images/design-document/https/TLS.png new file mode 100644 index 0000000000..59c62d25f9 Binary files /dev/null and b/static/images/design-document/https/TLS.png differ diff --git a/static/images/design-document/https/mTLS.png b/static/images/design-document/https/mTLS.png new file mode 100644 index 0000000000..1a1e42a06f Binary files /dev/null and b/static/images/design-document/https/mTLS.png differ