From 6e99fb03ebdaf882b9d9aee1a94b5c1fa1d6fc1a Mon Sep 17 00:00:00 2001 From: Jeongkyu Shin Date: Thu, 23 Oct 2025 18:24:32 +0900 Subject: [PATCH] docs: Add comprehensive documentation for Phase 2 SSH config options Update all documentation files to reflect the new certificate authentication and advanced port forwarding options added in PR #52: Certificate Authentication Options: - CertificateFile: SSH certificate files for PKI auth (max 100) - CASignatureAlgorithms: CA signature algorithms (max 50) - HostbasedAuthentication: Enable/disable host-based auth - HostbasedAcceptedAlgorithms: Accepted algorithms (max 50) Port Forwarding Control Options: - GatewayPorts: Control remote forwarding (yes/no/clientspecified) - ExitOnForwardFailure: Terminate on forwarding failure - PermitRemoteOpen: Allowed forwarding destinations (max 1000) Files Updated: - docs/man/bssh.1: Added SSH CONFIGURATION OPTIONS section - README.md: Added SSH Configuration Support section with examples - CHANGELOG.md: Updated Unreleased section with Phase 2 features - ARCHITECTURE.md: Added Supported SSH Configuration Options subsection All security features, limits, and best practices are documented. Examples demonstrate real-world usage scenarios. --- ARCHITECTURE.md | 94 ++++++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 30 ++++++++++++++ README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++ docs/man/bssh.1 | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 322 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b05dd045..1df1e76d 100644 --- 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 index ad7a342c..5accd38f 100644 --- 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 index 2a4b413b..5703db1d 100644 --- 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 index 6cb5f6d3..b06a15ab 100644 --- 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: