This is an automated email from the ASF dual-hosted git repository.
xuetaoli pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/dubbo-go-samples.git
The following commit(s) were added to refs/heads/main by this push:
new 03a6de28 feat: add TLS example demonstrating encrypted communication
and mutual authentication in Dubbo-Go (#955)
03a6de28 is described below
commit 03a6de2880e8dfe14401fb4eb7426670e2cbb5fd
Author: Xuetao Li <[email protected]>
AuthorDate: Sat Nov 15 11:54:21 2025 +0800
feat: add TLS example demonstrating encrypted communication and mutual
authentication in Dubbo-Go (#955)
---
README.md | 1 +
README_CN.md | 1 +
tls/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
tls/README_CN.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 126 insertions(+)
diff --git a/README.md b/README.md
index 6bbc9a4b..802356f1 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,7 @@
* streaming: Streaming RPC example
* task: Task scheduling and execution example
* timeout: Demonstrates timeout handling in Dubbo-go
+* tls: Demonstrates how to use TLS (based on X.509 certificates) in Dubbo-Go
to enable encrypted communication and/or mutual authentication between a client
and a server.
* transaction/seata-go: Distributed transaction example using seata-go
### Tools
diff --git a/README_CN.md b/README_CN.md
index c4270f44..c57c8827 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -54,6 +54,7 @@
* streaming：流式 RPC 通信示例
* task：任务调度与执行示例
* timeout：Dubbo-go 超时处理示例
+* tls：演示了如何在 Dubbo-Go 中使用 TLS（基于 X.509 证书）实现客户端与服务端之间的加密通信和/或双向认证
* transaction/seata-go：基于 seata-go 的分布式事务示例
### 工具
diff --git a/tls/README.md b/tls/README.md
new file mode 100644
index 00000000..07307c7b
--- /dev/null
+++ b/tls/README.md
@@ -0,0 +1,62 @@
+# TLS Example
+
+## Description
+
+This example demonstrates how to use TLS (based on X.509 certificates) in
Dubbo-Go to enable encrypted communication and/or mutual authentication between
a client and a server. The example includes a simple `greet` service, client
and server sample programs, and scripts for generating test certificates using
X.509.
+
+## Directory Structure
+
+* **client/**: Client example program
+* **server/**: Server example program
+* **proto/**: Proto file and generated code for the `greet` service
+* **x509/**: Scripts and example certificates for generating/storing test
certificates
+
+## Prerequisites
+
+* Go (recommended version 1.18+)
+* On Windows, it is recommended to use Git Bash or WSL to run the certificate
generation script (`x509/create.sh` uses OpenSSL).
+
+## Generating Test Certificates
+
+1. Navigate to the `x509` directory and run the certificate generation script:
+
+ * On Unix-based systems, execute the following command:
+
+ ```bash
+ cd tls/x509 && ./create.sh
+ ```
+ * On Windows, if OpenSSL or Bash is not installed, you can run the script
using WSL/Git Bash or manually generate the certificates using OpenSSL
following the configuration in `x509/openssl.cnf`.
+2. The generated certificates will be stored in the `x509/` directory,
including:
+
+ * `server_ca_*.pem`
+ * `client_ca_*.pem`
+ * `server{1,2}_*.pem`
+ * `client{1,2}_*.pem`
+
+## Running the Example
+
+### 1. Start the Server
+
+In the root project directory, run the following command to start the server:
+
+```bash
+go run ./tls/server/cmd
+```
+
+The server will load the server certificates and CA from the `x509/` directory
and listen on the address specified in the configuration. To customize this,
modify the `server` program or the source code as needed.
+
+### 2. Start the Client
+
+In another terminal, run the following command to start the client:
+
+```bash
+go run ./tls/client/cmd
+```
+
+The client will use the client certificates and CA from the `x509/` directory
to establish a TLS connection with the server and invoke the `greet` service.
+
+## Notes
+
+* The certificate paths and whether mutual authentication is enabled depend on
the files loaded by the example programs. Please check `tls/server/cmd/main.go`
and `tls/client/cmd/main.go` to understand the specific behavior and available
command-line parameters.
+* On Windows, running the `create.sh` script may require WSL/Git Bash or
manually running OpenSSL commands.
+* This example is intended for educational and testing purposes only. The
example certificates should not be used in a production environment.
diff --git a/tls/README_CN.md b/tls/README_CN.md
new file mode 100644
index 00000000..ab1c27dc
--- /dev/null
+++ b/tls/README_CN.md
@@ -0,0 +1,62 @@
+# TLS 示例
+
+## 说明
+
+本示例演示了如何在 Dubbo-Go 中使用 TLS（基于 X.509 证书）实现客户端与服务端之间的加密通信和/或双向认证。示例包括一个简单的
`greet` 服务、客户端与服务端的示例程序，以及用于生成测试证书的 X.509 脚本和示例证书。
+
+## 目录结构
+
+* **client/**: 客户端示例程序
+* **server/**: 服务端示例程序
+* **proto/**: `greet` 服务的 Proto 文件及生成的代码
+* **x509/**: 生成和存放测试证书的脚本和示例证书
+
+## 先决条件
+
+* Go 语言 (建议使用 1.18+ 版本)
+* 在 Windows 系统中，建议使用 Git Bash 或 WSL 来运行证书生成脚本（`x509/create.sh` 使用 OpenSSL）。
+
+## 生成测试证书
+
+1. 进入 `x509` 目录并运行证书生成脚本：
+
+ * 在类 Unix 环境中，执行以下命令：
+
+ ```bash
+ cd tls/x509 && ./create.sh
+ ```
+ * 在 Windows 系统中，如果未安装 Bash 或 OpenSSL，可以通过 WSL/Git Bash 来运行，或者使用 OpenSSL
手动按照 `x509/openssl.cnf` 文件生成证书。
+2. 生成的证书将保存在 `x509/` 目录下，文件包括：
+
+ * `server_ca_*.pem`
+ * `client_ca_*.pem`
+ * `server{1,2}_*.pem`
+ * `client{1,2}_*.pem`
+
+## 如何运行
+
+### 1. 启动服务端
+
+在项目根目录下执行以下命令来启动服务端：
+
+```bash
+go run ./tls/server/cmd
+```
+
+服务端会加载 `x509/` 目录下的服务器证书和 CA，默认监听配置中指定的地址。如果需要自定义配置，请修改 `server` 程序或源代码中的相关内容。
+
+### 2. 启动客户端
+
+在另一个终端执行以下命令来启动客户端：
+
+```bash
+go run ./tls/client/cmd
+```
+
+客户端会使用 `x509/` 目录下的客户端证书和 CA 与服务端建立 TLS 连接，并调用 `greet` 服务。
+
+## 注意事项
+
+* 证书路径和是否启用双向认证的设置取决于示例程序中加载的文件。请查看 `tls/server/cmd/main.go` 和
`tls/client/cmd/main.go` 以了解具体行为和可用的命令行参数。
+* 在 Windows 环境下运行 `create.sh` 脚本时，可能需要 WSL/Git Bash，或手动执行 OpenSSL 命令。
+* 本示例用于教学和测试目的，示例证书不应在生产环境中使用。
