add mTLS support

Author: HTHou

README.md

@@ -63,6 +63,50 @@ Users can quickly get started by referring to the use cases under the Apache-IoT
 
 For those who wish to delve deeper into the client's usage and explore more advanced features, the samples directory contains additional code samples. 
 
+## TLS and mTLS
+
+Enable TLS by calling `SetUseSsl(true)`. The C# client uses the .NET certificate model and does not read Java truststores directly. If your certificates were generated with the JDK 17 Java/keytool workflow, `client.keystore` is PKCS#12 by default and can be used directly as the client certificate file; use `ca.crt` directly as the trusted root.
+
+| keytool artifact | C# client usage |
+| --- | --- |
+| `ca.crt` | Pass to `SetRootCertificatePath` / `RootCertificatePath` to trust the server certificate |
+| `client.keystore` | Contains the client private key and certificate chain; JDK 17 creates PKCS#12 by default, so pass it directly to `SetClientCertificatePath` |
+| `client.truststore` | Java client truststore; the C# client uses `ca.crt` instead |
+| `server.truststore` | Server-side truststore for trusting client certificates; not a C# client option |
+
+Only convert the keystore first if you are reusing an older JKS file, or if it was explicitly generated with `-storetype JKS`:
+
+```bash
+$KT -importkeystore \
+  -srckeystore client.keystore \
+  -srcstorepass $PWD \
+  -srcalias client \
+  -destkeystore client.p12 \
+  -deststoretype PKCS12 \
+  -deststorepass $PWD \
+  -destkeypass $PWD \
+  -destalias client
+```
+
+C# builder example:
+
+```csharp
+var sessionPool = new SessionPool.Builder()
+    .SetHost("127.0.0.1")
+    .SetPort(6667)
+    .SetUseSsl(true)
+    .SetRootCertificatePath("tls-certs/ca.crt")
+    .SetClientCertificatePath("tls-certs/client.keystore")
+    .SetClientCertificatePassword("IoTDB")
+    .Build();
+```
+
+The ADO.NET connection string supports the same options:
+
+```text
+DataSource=127.0.0.1;Port=6667;UseSsl=True;RootCertificatePath=tls-certs/ca.crt;ClientCertificatePath=tls-certs/client.keystore;ClientCertificatePassword=IoTDB
+```
+
 ## Developer environment requirements for iotdb-client-csharp
 
 ```
@@ -101,4 +145,4 @@ dotnet format
 The CI pipeline will automatically check code formatting on all pull requests. Please ensure your code is properly formatted before submitting a PR.
 
 ## Publish your own client on nuget.org
-You can find out how to publish from this [doc](./PUBLISH.md).
+You can find out how to publish from this [doc](./PUBLISH.md).

README_ZH.md

@@ -61,6 +61,49 @@ dotnet add package Apache.IoTDB
 
 对于希望深入了解客户端用法并探索更高级特性的用户，samples目录包含了额外的代码示例。
 
+## TLS 和 mTLS
+
+通过 `SetUseSsl(true)` 开启 TLS。C# 客户端使用 .NET 的证书模型，不直接读取 Java truststore；如果证书按 JDK 17 的 Java/keytool 文档生成，`client.keystore` 默认就是 PKCS#12，可以直接作为客户端证书文件使用，并直接使用 `ca.crt` 作为信任根。
+
+| keytool 产物 | C# 客户端用法 |
+| --- | --- |
+| `ca.crt` | 传给 `SetRootCertificatePath` / `RootCertificatePath`，用于信任服务端证书 |
+| `client.keystore` | 包含客户端私钥和证书链；JDK 17 默认是 PKCS#12，直接传给 `SetClientCertificatePath` |
+| `client.truststore` | Java 客户端的 truststore；C# 侧用 `ca.crt`，不需要这个文件 |
+| `server.truststore` | 服务端用于信任客户端证书，不是 C# 客户端参数 |
+
+只有在复用旧版 JDK 生成的 JKS 文件，或显式使用 `-storetype JKS` 生成 keystore 时，才需要先转换为 PKCS#12：
+
+```bash
+$KT -importkeystore \
+  -srckeystore client.keystore \
+  -srcstorepass $PWD \
+  -srcalias client \
+  -destkeystore client.p12 \
+  -deststoretype PKCS12 \
+  -deststorepass $PWD \
+  -destkeypass $PWD \
+  -destalias client
+```
+
+C# builder 示例：
+
+```csharp
+var sessionPool = new SessionPool.Builder()
+    .SetHost("127.0.0.1")
+    .SetPort(6667)
+    .SetUseSsl(true)
+    .SetRootCertificatePath("tls-certs/ca.crt")
+    .SetClientCertificatePath("tls-certs/client.keystore")
+    .SetClientCertificatePassword("IoTDB")
+    .Build();
+```
+
+ADO.NET 连接字符串也支持相同配置：
+
+```text
+DataSource=127.0.0.1;Port=6667;UseSsl=True;RootCertificatePath=tls-certs/ca.crt;ClientCertificatePath=tls-certs/client.keystore;ClientCertificatePassword=IoTDB
+```
 
 ## iotdb-client-csharp的开发者环境要求
 
@@ -100,4 +143,4 @@ dotnet format
 CI 流水线会在所有 Pull Request 上自动检查代码格式。请确保在提交 PR 之前代码格式正确。
 
 ## 在 nuget.org 上发布你自己的客户端
-你可以在这个[文档](./PUBLISH.md)中找到如何发布
+你可以在这个[文档](./PUBLISH.md)中找到如何发布

src/Apache.IoTDB.Data/DataReaderExtensions.cs

@@ -32,7 +32,21 @@ public static class DataReaderExtensions
     {
         public static SessionPool CreateSession(this IoTDBConnectionStringBuilder db)
         {
-            return new SessionPool(db.DataSource, db.Port, db.Username, db.Password, db.FetchSize, db.ZoneId, db.PoolSize, db.Compression, db.TimeOut);
+            return new SessionPool.Builder()
+                .SetHost(db.DataSource)
+                .SetPort(db.Port)
+                .SetUsername(db.Username)
+                .SetPassword(db.Password)
+                .SetFetchSize(db.FetchSize)
+                .SetZoneId(db.ZoneId)
+                .SetPoolSize(db.PoolSize)
+                .SetEnableRpcCompression(db.Compression)
+                .SetConnectionTimeoutInMs(db.TimeOut)
+                .SetUseSsl(db.UseSsl)
+                .SetClientCertificatePath(db.ClientCertificatePath)
+                .SetClientCertificatePassword(db.ClientCertificatePassword)
+                .SetRootCertificatePath(db.RootCertificatePath)
+                .Build();
         }
 
         public static List<T> ToObject<T>(this IDataReader dataReader)

src/Apache.IoTDB.Data/IoTDBConnectionStringBuilder.cs

@@ -44,6 +44,10 @@ public class IoTDBConnectionStringBuilder : DbConnectionStringBuilder
         private const string PoolSizeKeyword = "PoolSize";
         private const string ZoneIdKeyword = "ZoneId";
         private const string TimeOutKeyword = "TimeOut";
+        private const string UseSslKeyword = "UseSsl";
+        private const string ClientCertificatePathKeyword = "ClientCertificatePath";
+        private const string ClientCertificatePasswordKeyword = "ClientCertificatePassword";
+        private const string RootCertificatePathKeyword = "RootCertificatePath";
 
         private enum Keywords
         {
@@ -55,7 +59,11 @@ private enum Keywords
             Compression,
             PoolSize,
             ZoneId,
-            TimeOut
+            TimeOut,
+            UseSsl,
+            ClientCertificatePath,
+            ClientCertificatePassword,
+            RootCertificatePath
         }
 
         private static readonly IReadOnlyList<string> _validKeywords;
@@ -70,10 +78,14 @@ private enum Keywords
         private int _port = 6667;
         private int _poolSize = 8;
         private int _timeOut = 10000;
+        private bool _useSsl = false;
+        private string _clientCertificatePath = null;
+        private string _clientCertificatePassword = null;
+        private string _rootCertificatePath = null;
 
         static IoTDBConnectionStringBuilder()
         {
-            var validKeywords = new string[9];
+            var validKeywords = new string[13];
             validKeywords[(int)Keywords.DataSource] = DataSourceKeyword;
             validKeywords[(int)Keywords.Username] = UserNameKeyword;
             validKeywords[(int)Keywords.Password] = PasswordKeyword;
@@ -83,9 +95,13 @@ static IoTDBConnectionStringBuilder()
             validKeywords[(int)Keywords.PoolSize] = PoolSizeKeyword;
             validKeywords[(int)Keywords.ZoneId] = ZoneIdKeyword;
             validKeywords[(int)Keywords.TimeOut] = TimeOutKeyword;
+            validKeywords[(int)Keywords.UseSsl] = UseSslKeyword;
+            validKeywords[(int)Keywords.ClientCertificatePath] = ClientCertificatePathKeyword;
+            validKeywords[(int)Keywords.ClientCertificatePassword] = ClientCertificatePasswordKeyword;
+            validKeywords[(int)Keywords.RootCertificatePath] = RootCertificatePathKeyword;
             _validKeywords = validKeywords;
 
-            _keywords = new Dictionary<string, Keywords>(9, StringComparer.OrdinalIgnoreCase)
+            _keywords = new Dictionary<string, Keywords>(13, StringComparer.OrdinalIgnoreCase)
             {
                 [DataSourceKeyword] = Keywords.DataSource,
                 [UserNameKeyword] = Keywords.Username,
@@ -95,7 +111,11 @@ static IoTDBConnectionStringBuilder()
                 [CompressionKeyword] = Keywords.Compression,
                 [PoolSizeKeyword] = Keywords.PoolSize,
                 [ZoneIdKeyword] = Keywords.ZoneId,
-                [TimeOutKeyword] = Keywords.TimeOut
+                [TimeOutKeyword] = Keywords.TimeOut,
+                [UseSslKeyword] = Keywords.UseSsl,
+                [ClientCertificatePathKeyword] = Keywords.ClientCertificatePath,
+                [ClientCertificatePasswordKeyword] = Keywords.ClientCertificatePassword,
+                [RootCertificatePathKeyword] = Keywords.RootCertificatePath
             };
         }
 
@@ -165,7 +185,31 @@ public virtual string ZoneId
         public virtual int TimeOut
         {
             get => _timeOut;
-            set => base[PoolSizeKeyword] = _timeOut = value;
+            set => base[TimeOutKeyword] = _timeOut = value;
+        }
+
+        public virtual bool UseSsl
+        {
+            get => _useSsl;
+            set => base[UseSslKeyword] = _useSsl = value;
+        }
+
+        public virtual string ClientCertificatePath
+        {
+            get => _clientCertificatePath;
+            set => base[ClientCertificatePathKeyword] = _clientCertificatePath = value;
+        }
+
+        public virtual string ClientCertificatePassword
+        {
+            get => _clientCertificatePassword;
+            set => base[ClientCertificatePasswordKeyword] = _clientCertificatePassword = value;
+        }
+
+        public virtual string RootCertificatePath
+        {
+            get => _rootCertificatePath;
+            set => base[RootCertificatePathKeyword] = _rootCertificatePath = value;
         }
 
         /// <summary>
@@ -246,6 +290,18 @@ public override object this[string keyword]
                     case Keywords.TimeOut:
                         TimeOut = Convert.ToInt32(value, CultureInfo.InvariantCulture);
                         return;
+                    case Keywords.UseSsl:
+                        UseSsl = Convert.ToBoolean(value, CultureInfo.InvariantCulture);
+                        return;
+                    case Keywords.ClientCertificatePath:
+                        ClientCertificatePath = Convert.ToString(value, CultureInfo.InvariantCulture);
+                        return;
+                    case Keywords.ClientCertificatePassword:
+                        ClientCertificatePassword = Convert.ToString(value, CultureInfo.InvariantCulture);
+                        return;
+                    case Keywords.RootCertificatePath:
+                        RootCertificatePath = Convert.ToString(value, CultureInfo.InvariantCulture);
+                        return;
                     default:
                         Debug.WriteLine(false, "Unexpected keyword: " + keyword);
                         return;
@@ -376,6 +432,14 @@ private object GetAt(Keywords index)
                     return ZoneId;
                 case Keywords.TimeOut:
                     return TimeOut;
+                case Keywords.UseSsl:
+                    return UseSsl;
+                case Keywords.ClientCertificatePath:
+                    return ClientCertificatePath;
+                case Keywords.ClientCertificatePassword:
+                    return ClientCertificatePassword;
+                case Keywords.RootCertificatePath:
+                    return RootCertificatePath;
                 default:
                     Debug.Assert(false, "Unexpected keyword: " + index);
                     return null;
@@ -418,6 +482,18 @@ private void Reset(Keywords index)
                 case Keywords.TimeOut:
                     _timeOut = 10000;//10sec.
                     return;
+                case Keywords.UseSsl:
+                    _useSsl = false;
+                    return;
+                case Keywords.ClientCertificatePath:
+                    _clientCertificatePath = null;
+                    return;
+                case Keywords.ClientCertificatePassword:
+                    _clientCertificatePassword = null;
+                    return;
+                case Keywords.RootCertificatePath:
+                    _rootCertificatePath = null;
+                    return;
                 default:
                     Debug.Assert(false, "Unexpected keyword: " + index);
                     return;

src/Apache.IoTDB/SessionPool.Builder.cs

@@ -35,7 +35,9 @@ public class Builder
         private bool _enableRpcCompression = false;
         private int _connectionTimeoutInMs = 500;
         private bool _useSsl = false;
-        private string _certificatePath = null;
+        private string _clientCertificatePath = null;
+        private string _clientCertificatePassword = null;
+        private string _rootCertificatePath = null;
         private string _sqlDialect = IoTDBConstant.TREE_SQL_DIALECT;
         private string _database = "";
         private List<string> _nodeUrls = new List<string>();
@@ -100,9 +102,21 @@ public Builder SetUseSsl(bool useSsl)
             return this;
         }
 
-        public Builder SetCertificatePath(string certificatePath)
+        public Builder SetClientCertificatePath(string clientCertificatePath)
         {
-            _certificatePath = certificatePath;
+            _clientCertificatePath = clientCertificatePath;
+            return this;
+        }
+
+        public Builder SetClientCertificatePassword(string clientCertificatePassword)
+        {
+            _clientCertificatePassword = clientCertificatePassword;
+            return this;
+        }
+
+        public Builder SetRootCertificatePath(string rootCertificatePath)
+        {
+            _rootCertificatePath = rootCertificatePath;
             return this;
         }
 
@@ -136,7 +150,9 @@ public Builder()
             _enableRpcCompression = false;
             _connectionTimeoutInMs = 500;
             _useSsl = false;
-            _certificatePath = null;
+            _clientCertificatePath = null;
+            _clientCertificatePassword = null;
+            _rootCertificatePath = null;
             _sqlDialect = IoTDBConstant.TREE_SQL_DIALECT;
             _database = "";
         }
@@ -146,9 +162,9 @@ public SessionPool Build()
             // if nodeUrls is not empty, use nodeUrls to create session pool
             if (_nodeUrls.Count > 0)
             {
-                return new SessionPool(_nodeUrls, _username, _password, _fetchSize, _zoneId, _poolSize, _enableRpcCompression, _connectionTimeoutInMs, _useSsl, _certificatePath, _sqlDialect, _database);
+                return new SessionPool(_nodeUrls, _username, _password, _fetchSize, _zoneId, _poolSize, _enableRpcCompression, _connectionTimeoutInMs, _useSsl, _clientCertificatePath, _clientCertificatePassword, _rootCertificatePath, _sqlDialect, _database);
             }
-            return new SessionPool(_host, _port, _username, _password, _fetchSize, _zoneId, _poolSize, _enableRpcCompression, _connectionTimeoutInMs, _useSsl, _certificatePath, _sqlDialect, _database);
+            return new SessionPool(_host, _port, _username, _password, _fetchSize, _zoneId, _poolSize, _enableRpcCompression, _connectionTimeoutInMs, _useSsl, _clientCertificatePath, _clientCertificatePassword, _rootCertificatePath, _sqlDialect, _database);
         }
     }
 }