lablup · inureyes · Oct 23, 2025 · Oct 23, 2025
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -582,6 +582,100 @@ pub fn find_host_config(hosts: &[SshHostConfig], hostname: &str) -> SshHostConfi
 - Security: exec validation, path traversal prevention
 - **Total:** 62 tests passing
 
+#### Supported SSH Configuration Options
+
+bssh supports 40+ SSH configuration directives organized into categories:
+
+**Connection Options:**
+- `HostName` - Remote hostname or IP address
+- `Port` - SSH port (default: 22)
+- `User` - Remote username
+- `ConnectTimeout` - Connection timeout in seconds
+- `ServerAliveInterval` - Keepalive interval
+- `ServerAliveCountMax` - Keepalive retry count
+
+**Authentication Options:**
+- `IdentityFile` - SSH private key file (multiple allowed)
+- `CertificateFile` - SSH certificate file for PKI auth (max 100, Phase 2)
+- `HostbasedAuthentication` - Enable host-based auth (yes/no, Phase 2)
+- `HostbasedAcceptedAlgorithms` - Host-based auth algorithms (max 50, Phase 2)
+- `PubkeyAuthentication` - Enable public key auth
+- `PasswordAuthentication` - Enable password auth
+- `PreferredAuthentications` - Authentication method priority
+
+**Security Options:**
+- `StrictHostKeyChecking` - Host key verification (yes/no/accept-new)
+- `UserKnownHostsFile` - Known hosts file path
+- `HashKnownHosts` - Hash hostnames in known_hosts
+- `CASignatureAlgorithms` - CA signature algorithms (max 50, Phase 2)
+- `HostKeyAlgorithms` - Accepted host key types
+- `PubkeyAcceptedAlgorithms` - Accepted public key types
+
+**Port Forwarding Options:**
+- `LocalForward` - Local port forwarding (-L)
+- `RemoteForward` - Remote port forwarding (-R)
+- `DynamicForward` - SOCKS proxy (-D)
+- `GatewayPorts` - Remote forwarding access control (yes/no/clientspecified, Phase 2)
+- `ExitOnForwardFailure` - Terminate on forwarding failure (yes/no, Phase 2)
+- `PermitRemoteOpen` - Allowed remote forward destinations (max 1000, Phase 2)
+
+**Jump Host Options:**
+- `ProxyJump` - Jump host specification (-J)
+- `ProxyCommand` - Custom proxy command
+
+**PTY and Session Options:**
+- `RequestTTY` - PTY allocation (yes/no/force/auto)
+- `ForwardAgent` - Agent forwarding
+- `ForwardX11` - X11 forwarding
+- `SendEnv` - Environment variables to send
+- `SetEnv` - Environment variables to set
+
+**Option Value Formats:**
+All options support both OpenSSH-compatible syntaxes:
+- `Option Value` - Traditional space-separated format
+- `Option=Value` - Alternative equals-sign format
+
+**Security Limits (Phase 2):**
+- CertificateFile: Maximum 100 entries per configuration
+- CASignatureAlgorithms: Maximum 50 algorithms
+- HostbasedAcceptedAlgorithms: Maximum 50 algorithms
+- PermitRemoteOpen: Maximum 1000 destination entries
+- Path validation prevents usage of sensitive system files
+- Automatic deduplication for multi-valued options
+
+**Configuration Merging Rules:**
+- **Scalar options** (Port, User, HostName): First match wins (SSH-compatible)
+- **Vector options** (IdentityFile, CertificateFile, PermitRemoteOpen): Accumulate across matches with deduplication
+- **Algorithm lists** (CASignatureAlgorithms, HostbasedAcceptedAlgorithms): Later matches override earlier ones
+- CLI arguments always take precedence over config file options
+
+**Example Configuration:**
+```ssh
+# ~/.ssh/config
+
+# Global defaults
+Host *
+    ServerAliveInterval 60
+    ServerAliveCountMax 3
+    HostbasedAuthentication no
+
+# Production servers with certificate authentication
+Host *.prod.example.com
+    User admin
+    CertificateFile ~/.ssh/prod-user-cert.pub
+    CertificateFile ~/.ssh/prod-host-cert.pub
+    CASignatureAlgorithms ssh-ed25519,rsa-sha2-512
+    HostbasedAuthentication yes
+    HostbasedAcceptedAlgorithms ssh-ed25519,rsa-sha2-512
+
+# Secure hosts with strict port forwarding
+Match host *.secure.prod.example.com
+    GatewayPorts clientspecified
+    ExitOnForwardFailure yes
+    PermitRemoteOpen localhost:8080
+    PermitRemoteOpen db.internal:5432
+```
+
 ### 7. SSH Configuration Caching (`ssh/config_cache/*`)
 
 **Status:** Implemented (2025-08-28), Refactored (2025-10-17)

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **SSH Configuration: Certificate Authentication Options**
+  - `CertificateFile` - Specify SSH certificate files for PKI authentication (maximum 100 certificates)
+  - `CASignatureAlgorithms` - Define CA signature algorithms for certificate validation (maximum 50 algorithms)
+  - `HostbasedAuthentication` - Enable/disable host-based authentication
+  - `HostbasedAcceptedAlgorithms` - Specify accepted algorithms for host-based authentication (maximum 50 algorithms)
+
+- **SSH Configuration: Advanced Port Forwarding Control**
+  - `GatewayPorts` - Control remote port forwarding access (yes/no/clientspecified)
+  - `ExitOnForwardFailure` - Terminate connection when port forwarding fails
+  - `PermitRemoteOpen` - Specify allowed destinations for remote TCP port forwarding (maximum 1000 entries)
+
+- **Security Enhancements**
+  - Path validation to prevent usage of sensitive system files (e.g., /etc/passwd, /etc/shadow)
+  - Memory exhaustion prevention with entry limits for certificates and forwarding rules
+  - Algorithm list validation with maximum entry limits
+  - Deduplication for certificate files and remote forwarding destinations
+
+### Changed
+- **SSH Config Parser**: Refactored into modular structure for better maintainability
+  - Split oversized parser.rs (1706 lines) into category-based modules (~200-350 lines each)
+  - Organized option parsing by categories: authentication, security, forwarding, connection, etc.
+  - Improved code organization and maintainability
+
+### Technical Details
+- Enhanced SSH configuration merging logic with proper priority handling
+- Support for both "Option Value" and "Option=Value" syntax
+- Scalar options override in later blocks, vector options accumulate with deduplication
+- Comprehensive test coverage: 265 tests including parser, resolver, integration, and security tests
+
 ## [0.9.1] - 2025-10-14
 
 ### Added

diff --git a/README.md b/README.md
@@ -368,6 +368,103 @@ clusters:
     user: staging_user
 ```
 
+## SSH Configuration Support
+
+bssh fully supports OpenSSH-compatible configuration files via the `-F` flag or default SSH config locations (`~/.ssh/config`, `/etc/ssh/ssh_config`). In addition to standard SSH directives, bssh supports advanced options for certificate-based authentication and port forwarding control.
+
+### Certificate Authentication Options
+
+These options enable enterprise-grade PKI authentication using SSH certificates:
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| **CertificateFile** | SSH certificate file for PKI authentication (max 100 files) | `CertificateFile ~/.ssh/id_rsa-cert.pub` |
+| **CASignatureAlgorithms** | CA signature algorithms for certificate validation (max 50) | `CASignatureAlgorithms ssh-ed25519,rsa-sha2-512` |
+| **HostbasedAuthentication** | Enable host-based authentication (yes/no) | `HostbasedAuthentication yes` |
+| **HostbasedAcceptedAlgorithms** | Algorithms for host-based auth (max 50) | `HostbasedAcceptedAlgorithms ssh-ed25519,rsa-sha2-512` |
+
+### Port Forwarding Control Options
+
+These options provide fine-grained control over SSH port forwarding:
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| **GatewayPorts** | Control remote port forwarding (yes/no/clientspecified) | `GatewayPorts clientspecified` |
+| **ExitOnForwardFailure** | Terminate connection if port forwarding fails (yes/no) | `ExitOnForwardFailure yes` |
+| **PermitRemoteOpen** | Allowed destinations for remote forwarding (max 1000) | `PermitRemoteOpen localhost:8080` |
+
+### SSH Config Examples
+
+#### Certificate-based Authentication
+
+```ssh-config
+# ~/.ssh/config
+
+# Production servers with certificate authentication
+Host *.prod.example.com
+    User admin
+    CertificateFile ~/.ssh/prod-user-cert.pub
+    CertificateFile ~/.ssh/prod-host-cert.pub
+    CASignatureAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
+    HostbasedAuthentication yes
+    HostbasedAcceptedAlgorithms ssh-ed25519,rsa-sha2-512
+```
+
+#### Strict Port Forwarding Control
+
+```ssh-config
+# Secure hosts with restricted port forwarding
+Host *.secure.prod.example.com
+    GatewayPorts clientspecified
+    ExitOnForwardFailure yes
+    PermitRemoteOpen localhost:8080
+    PermitRemoteOpen db.internal:5432
+    PermitRemoteOpen cache.internal:6379
+```
+
+#### Complete Example with Include and Match
+
+```ssh-config
+# Base security settings
+Host *
+    HostbasedAuthentication no
+    ExitOnForwardFailure no
+
+# Production certificate configuration
+Host *.prod.example.com
+    CertificateFile ~/.ssh/prod-cert.pub
+    CASignatureAlgorithms ssh-ed25519,rsa-sha2-512
+    HostbasedAuthentication yes
+
+# Match directive for secure hosts
+Match host *.secure.prod.example.com
+    GatewayPorts clientspecified
+    ExitOnForwardFailure yes
+    PermitRemoteOpen localhost:8080
+
+# Specific host overrides
+Host web.secure.prod.example.com
+    User webadmin
+    Port 443
+    CertificateFile ~/.ssh/web-specific-cert.pub
+```
+
+### Using SSH Config with bssh
+
+```bash
+# Use default SSH config (~/.ssh/config)
+bssh user@host.prod.example.com
+
+# Use custom SSH config file
+bssh -F ~/custom-ssh-config user@host.prod.example.com
+
+# SSH config works with cluster operations
+bssh -C production "uptime"
+
+# Config options apply to all cluster nodes
+bssh -F ~/.ssh/prod-config -C production upload app.tar.gz /opt/
+```
+
 ## Command-Line Options
 
 ```

diff --git a/docs/man/bssh.1 b/docs/man/bssh.1
@@ -284,6 +284,107 @@ clusters:
     user: staging_user
 .fi
 
+.SH SSH CONFIGURATION OPTIONS
+.B bssh
+supports OpenSSH-compatible configuration via the
+.B -F
+flag or default SSH config files (~/.ssh/config, /etc/ssh/ssh_config).
+
+In addition to standard SSH configuration directives, bssh supports advanced options for
+certificate-based authentication and port forwarding control:
+
+.SS Certificate Authentication Options
+.TP
+.B CertificateFile
+Specifies a file containing the SSH certificate for PKI authentication.
+Can be specified multiple times (maximum 100 certificates).
+.br
+Example:
+.I CertificateFile ~/.ssh/id_rsa-cert.pub
+
+.TP
+.B CASignatureAlgorithms
+Specifies the signature algorithms that will be used for certificate validation.
+Comma-separated list of algorithms (maximum 50 entries).
+.br
+Example:
+.I CASignatureAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
+
+.TP
+.B HostbasedAuthentication
+Enables or disables host-based authentication. Default is no.
+.br
+Example:
+.I HostbasedAuthentication yes
+
+.TP
+.B HostbasedAcceptedAlgorithms
+Specifies the signature algorithms that will be accepted for host-based authentication.
+Comma-separated list (maximum 50 entries).
+.br
+Example:
+.I HostbasedAcceptedAlgorithms ssh-ed25519,rsa-sha2-512
+
+.SS Port Forwarding Control Options
+.TP
+.B GatewayPorts
+Specifies whether remote hosts are allowed to connect to ports forwarded for the client.
+Possible values:
+.RS
+.IP \[bu] 2
+.B yes
+- Remote hosts can connect to forwarded ports
+.IP \[bu] 2
+.B no
+- Only localhost connections allowed (default)
+.IP \[bu] 2
+.B clientspecified
+- Client can specify which addresses may connect
+.RE
+.IP
+Example:
+.I GatewayPorts clientspecified
+
+.TP
+.B ExitOnForwardFailure
+Specifies whether the connection should be terminated if port forwarding fails.
+Default is no.
+.br
+Example:
+.I ExitOnForwardFailure yes
+
+.TP
+.B PermitRemoteOpen
+Specifies the destinations to which remote TCP port forwarding is permitted.
+Can be specified multiple times (maximum 1000 entries).
+Format: host:port or host:* to allow any port.
+.br
+Example:
+.I PermitRemoteOpen localhost:8080
+.br
+.I PermitRemoteOpen db.internal:5432
+
+.SS SSH Config Example with New Options
+.nf
+# ~/.ssh/config
+
+# Production servers with certificate authentication
+Host *.prod.example.com
+    User admin
+    CertificateFile ~/.ssh/prod-user-cert.pub
+    CertificateFile ~/.ssh/prod-host-cert.pub
+    CASignatureAlgorithms ssh-ed25519,rsa-sha2-512
+    HostbasedAuthentication yes
+    HostbasedAcceptedAlgorithms ssh-ed25519,rsa-sha2-512
+
+# Secure hosts with strict port forwarding
+Host *.secure.prod.example.com
+    GatewayPorts clientspecified
+    ExitOnForwardFailure yes
+    PermitRemoteOpen localhost:8080
+    PermitRemoteOpen db.internal:5432
+.fi
+
 .SH BACKEND.AI INTEGRATION
 When running inside a Backend.AI multi-node session, bssh automatically detects cluster configuration
 from environment variables: