feat: add ssh key authentication support

Author: shivanshuraj1333

README.md

@@ -271,6 +271,34 @@ conn := clickhouse.OpenDB(&clickhouse.Options{
 })
 ```
 
+## SSH Authentication (Native Protocol)
+
+ClickHouse-go supports SSH key-based authentication (requires ClickHouse server with SSH auth enabled).
+
+**Options struct:**
+```go
+conn, err := clickhouse.Open(&clickhouse.Options{
+    Addr: []string{"127.0.0.1:9000"},
+    Auth: clickhouse.Auth{
+        Database: "default",
+        Username: "default",
+    },
+    SSHKeyFile:       "/path/to/id_ed25519",
+    SSHKeyPassphrase: "your_passphrase_if_any",
+})
+```
+
+**DSN parameters:**
+- `ssh_key_file` — path to SSH private key (RSA, ECDSA, Ed25519)
+- `ssh_key_passphrase` — passphrase for encrypted key (optional)
+
+Example DSN:
+```
+clickhouse://default@127.0.0.1:9000/default?ssh_key_file=/path/to/id_ed25519&ssh_key_passphrase=your_passphrase_if_any
+```
+
+See [`examples/ssh_auth.go`](examples/ssh_auth.go) for a complete example.
+
 ## Client info
 
 

clickhouse_options.go

@@ -162,6 +162,10 @@ type Options struct {
 	// Use this instead of Auth.Username and Auth.Password if you're using JWT auth.
 	GetJWT GetJWTFunc
 
+	// SSH authentication
+	SSHKeyFile       string // path to SSH private key file
+	SSHKeyPassphrase string // passphrase for SSH key (if encrypted)
+
 	scheme      string
 	ReadTimeout time.Duration
 }
@@ -327,6 +331,10 @@ func (o *Options) fromDSN(in string) error {
 				return fmt.Errorf("clickhouse [dsn parse]: http_proxy: %s", err)
 			}
 			o.HTTPProxyURL = proxyURL
+		case "ssh_key_file":
+			o.SSHKeyFile = params.Get(v)
+		case "ssh_key_passphrase":
+			o.SSHKeyPassphrase = params.Get(v)
 		default:
 			switch p := strings.ToLower(params.Get(v)); p {
 			case "true":

conn_handshake.go

@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"time"
 
+	chssh "github.com/ClickHouse/ch-go/ssh"
 	"github.com/ClickHouse/clickhouse-go/v2/lib/proto"
 )
 
@@ -79,6 +80,61 @@ func (c *connect) handshake(auth Auth) error {
 		c.debugf("[handshake] downgrade client proto")
 	}
 	c.debugf("[handshake] <- %s", c.server)
+
+	// Handle SSH authentication if configured
+	if c.opt.SSHKeyFile != "" {
+		if err := c.performSSHAuthentication(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (c *connect) performSSHAuthentication() error {
+	// Load SSH key
+	sshKey, err := chssh.LoadPrivateKeyFromFile(c.opt.SSHKeyFile, c.opt.SSHKeyPassphrase)
+	if err != nil {
+		return fmt.Errorf("failed to load SSH key: %w", err)
+	}
+
+	// Send SSH challenge request
+	c.buffer.Reset()
+	c.buffer.PutByte(proto.ClientSSHChallengeRequest)
+	if err := c.flush(); err != nil {
+		return fmt.Errorf("send SSH challenge request: %w", err)
+	}
+
+	// Read SSH challenge response
+	packet, err := c.reader.ReadByte()
+	if err != nil {
+		return fmt.Errorf("read SSH challenge response: %w", err)
+	}
+
+	if packet != proto.ServerSSHChallenge {
+		return fmt.Errorf("unexpected packet [%d] from server during SSH authentication", packet)
+	}
+
+	// Read challenge string
+	challenge, err := c.reader.Str()
+	if err != nil {
+		return fmt.Errorf("read SSH challenge string: %w", err)
+	}
+
+	// Sign the challenge
+	signature, err := sshKey.SignString(challenge)
+	if err != nil {
+		return fmt.Errorf("sign SSH challenge: %w", err)
+	}
+
+	// Send SSH challenge response
+	c.buffer.Reset()
+	c.buffer.PutByte(proto.ClientSSHChallengeResponse)
+	c.buffer.PutString(signature)
+	if err := c.flush(); err != nil {
+		return fmt.Errorf("send SSH challenge response: %w", err)
+	}
+
 	return nil
 }
 

conn_handshake_test.go

@@ -0,0 +1,47 @@
+package clickhouse
+
+import (
+	"os"
+	"testing"
+)
+
+func TestSSHAuthenticationOptions(t *testing.T) {
+	t.Run("MissingKeyFile", func(t *testing.T) {
+		opt := &Options{
+			SSHKeyFile: "/nonexistent/path/to/key",
+		}
+		c := &connect{opt: opt}
+		err := c.performSSHAuthentication()
+		if err == nil {
+			t.Fatal("expected error for missing SSH key file")
+		}
+	})
+
+	t.Run("InvalidKeyFile", func(t *testing.T) {
+		f, err := os.CreateTemp("", "invalid_key*")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer os.Remove(f.Name())
+		f.WriteString("not a key")
+		f.Close()
+		opt := &Options{
+			SSHKeyFile: f.Name(),
+		}
+		c := &connect{opt: opt}
+		err = c.performSSHAuthentication()
+		if err == nil {
+			t.Fatal("expected error for invalid SSH key file")
+		}
+	})
+
+	t.Run("WrongPassphrase", func(t *testing.T) {
+		t.Skip("Needs a real encrypted key for full test")
+		// Provide a valid encrypted key and wrong passphrase, expect error
+	})
+
+	t.Run("Integration", func(t *testing.T) {
+		t.Skip("Integration test: requires ClickHouse server with SSH auth enabled and valid key")
+		// Provide valid key, connect, expect success
+	})
+}

examples/ssh_auth.go

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/ClickHouse/clickhouse-go/v2"
+)
+
+func main() {
+	// Using Options struct
+	conn, err := clickhouse.Open(&clickhouse.Options{
+		Addr: []string{"127.0.0.1:9000"},
+		Auth: clickhouse.Auth{
+			Database: "default",
+			Username: "default",
+		},
+		SSHKeyFile:       "/path/to/id_ed25519",
+		SSHKeyPassphrase: "your_passphrase_if_any",
+	})
+	if err != nil {
+		log.Fatalf("failed to open connection: %v", err)
+	}
+	if err := conn.Ping(context.Background()); err != nil {
+		log.Fatalf("failed to ping: %v", err)
+	}
+	fmt.Println("SSH authentication succeeded (Options struct)")
+
+	// Using DSN
+	// dsn := "clickhouse://default@127.0.0.1:9000/default?ssh_key_file=/path/to/id_ed25519&ssh_key_passphrase=your_passphrase_if_any"
+	// conn, err := clickhouse.Open(&clickhouse.Options{})
+	// ...
+}

go.mod

@@ -74,7 +74,9 @@ require (
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0 // indirect
 	go.opentelemetry.io/otel/metric v1.37.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.0.0 // indirect
-	golang.org/x/crypto v0.39.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/crypto v0.40.0 // indirect
+	golang.org/x/sys v0.34.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20240318140521-94a12d6c2237 // indirect
 )
+
+replace github.com/ClickHouse/ch-go => ../ch-go

go.sum

@@ -4,8 +4,6 @@ github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8af
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
 github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
 github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
-github.com/ClickHouse/ch-go v0.66.1 h1:LQHFslfVYZsISOY0dnOYOXGkOUvpv376CCm8g7W74A4=
-github.com/ClickHouse/ch-go v0.66.1/go.mod h1:NEYcg3aOFv2EmTJfo4m2WF7sHB/YFbLUuIWv9iq76xY=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/StackExchange/wmi v0.0.0-20190523213315-cbe66965904d/go.mod h1:3eOhrUMpNV+6aFIbp5/iudMxNCF27Vw2OZgy4xEx0Fg=
@@ -173,8 +171,8 @@ go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 h1:IeMey
 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0/go.mod h1:oVdCUtjq9MK9BlS7TtucsQwUcXcymNiEDjgDD2jMtZU=
 go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE=
 go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E=
-go.opentelemetry.io/otel/sdk v1.36.0 h1:b6SYIuLRs88ztox4EyrvRti80uXIFy+Sqzoh9kFULbs=
-go.opentelemetry.io/otel/sdk v1.36.0/go.mod h1:+lC+mTgD+MUWfjJubi2vvXWcVxyr9rmlshZni72pXeY=
+go.opentelemetry.io/otel/sdk v1.37.0 h1:ItB0QUqnjesGRvNcmAcU0LyvkVyGJ2xftD29bWdDvKI=
+go.opentelemetry.io/otel/sdk v1.37.0/go.mod h1:VredYzxUvuo2q3WRcDnKDjbdvmO0sCzOvVAiY+yUkAg=
 go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
 go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
 go.opentelemetry.io/proto/otlp v1.0.0 h1:T0TX0tmXU8a3CbNXzEKGeU5mIVOdf0oykP+u2lIVU/I=
@@ -183,8 +181,8 @@ golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACk
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
-golang.org/x/crypto v0.39.0 h1:SHs+kF4LP+f+p14esP5jAoDpHU8Gu/v9lFRK6IT5imM=
-golang.org/x/crypto v0.39.0/go.mod h1:L+Xg3Wf6HoL4Bn4238Z6ft6KfEpN0tJGo53AAPC632U=
+golang.org/x/crypto v0.40.0 h1:r4x+VvoG5Fm+eJcxMaY8CQM7Lb0l1lsmjGBQ6s8BfKM=
+golang.org/x/crypto v0.40.0/go.mod h1:Qr1vMER5WyS2dfPHAlsOj01wgLbsyWtFn/aY+5+ZdxY=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
@@ -211,17 +209,17 @@ golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
-golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
+golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.32.0 h1:DR4lr0TjUs3epypdhTOkMmuF5CDFJ/8pOnbzMZPQ7bg=
-golang.org/x/term v0.32.0/go.mod h1:uZG1FhGx848Sqfsq4/DlJr3xGGsYMu/L5GW4abiaEPQ=
+golang.org/x/term v0.33.0 h1:NuFncQrRcaRvVmgRkvM3j/F00gWIAlcmlB8ACEKmGIg=
+golang.org/x/term v0.33.0/go.mod h1:s18+ql9tYWp1IfpV9DmCtQDDSRBUjKaw9M1eAv5UeF0=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
-golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M=
-golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA=
+golang.org/x/text v0.27.0 h1:4fGWRpyh641NLlecmyl4LOe6yDdfaYNrGb2zdfo4JV4=
+golang.org/x/text v0.27.0/go.mod h1:1D28KMCvyooCX9hBiosv5Tz/+YLxj0j7XhWjpSUF7CU=
 golang.org/x/time v0.0.0-20220210224613-90d013bbcef8 h1:vVKdlvoWBphwdxWKrFZEuM0kGgGLxUOYcY4U/2Vjg44=
 golang.org/x/time v0.0.0-20220210224613-90d013bbcef8/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=

lib/proto/const.go

@@ -41,11 +41,13 @@ const (
 )
 
 const (
-	ClientHello  = 0
-	ClientQuery  = 1
-	ClientData   = 2
-	ClientCancel = 3
-	ClientPing   = 4
+	ClientHello                = 0
+	ClientQuery                = 1
+	ClientData                 = 2
+	ClientCancel               = 3
+	ClientPing                 = 4
+	ClientSSHChallengeRequest  = 11
+	ClientSSHChallengeResponse = 12
 )
 
 const (
@@ -80,4 +82,5 @@ const (
 	ServerReadTaskRequest     = 13
 	ServerProfileEvents       = 14
 	ServerTreeReadTaskRequest = 15
+	ServerSSHChallenge        = 18
 )