Repository navigation
Description
Overview
This is Phase 2 of the SSH config parser enhancement roadmap. This phase focuses on adding support for certificate-based PKI authentication and advanced port forwarding control options that are commonly used in enterprise and production environments.
Background
- Part of the larger SSH config parser improvement initiative (see Support various Option syntax and additional SSH config options in parser #42, [Phase 1] Add Include and Match directive support to SSH config parser #43)
- These options are critical for enterprise deployments and advanced networking scenarios
- Widely used in large-scale infrastructure and cloud environments
Options to Implement
1. CertificateFile ⭐⭐⭐⭐
Importance: High - Standard in enterprise PKI environments
Functionality:
- Specify SSH certificate files for authentication
- Works alongside IdentityFile for certificate-based auth
- Supports multiple certificate files
- Eliminates need for authorized_keys management at scale
Use Cases:
- Large-scale enterprise deployments
- PKI-based authentication systems
- Certificate expiration management
- Centralized access control
Example:
Host *.corp.example.com
IdentityFile ~/.ssh/id_rsa
CertificateFile ~/.ssh/id_rsa-cert.pub
Implementation:
- Add
certificate_files: Vec<PathBuf>to SshHostConfig - Parse and validate certificate file paths
- Support tilde expansion and environment variables
2. CASignatureAlgorithms ⭐⭐⭐⭐
Importance: High - Required for certificate validation
Functionality:
- Specify accepted signature algorithms for CA certificates
- Controls which CA signature algorithms are trusted
- Security hardening for certificate-based auth
Example:
Host *
CASignatureAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
Implementation:
- Add
ca_signature_algorithms: Vec<String>to SshHostConfig - Parse comma-separated algorithm list
- Validate algorithm names
3. GatewayPorts ⭐⭐⭐⭐
Importance: High - Critical for remote port forwarding
Functionality:
- Control whether remote port forwardings bind to wildcard address
- Values: yes, no, clientspecified
- Enables external access to forwarded ports
Use Cases:
- Exposing local development servers remotely
- Bypassing NAT/firewalls
- Cloud service tunneling
- Reverse proxy setups
Example:
Host tunnel-server
RemoteForward 8080 localhost:3000
GatewayPorts yes
Implementation:
- Add
gateway_ports: Option<String>to SshHostConfig - Parse yes/no/clientspecified values
- Validation for valid values
4. ExitOnForwardFailure ⭐⭐⭐⭐
Importance: High - Critical for reliability
Functionality:
- Terminate SSH connection if port forwarding fails
- Prevents silent failures in automation
- Ensures forwarding-dependent workflows fail fast
Use Cases:
- Automated deployment scripts
- Database tunneling (must succeed)
- Service-critical port forwards
- CI/CD pipelines
Example:
Host database-tunnel
LocalForward 5432 db.internal:5432
ExitOnForwardFailure yes
Implementation:
- Add
exit_on_forward_failure: Option<bool>to SshHostConfig - Parse yes/no values using existing parse_yes_no function
- Document fail-fast behavior
5. PermitRemoteOpen ⭐⭐⭐
Importance: Medium-High - Security control
Functionality:
- Restrict which remote hosts can be connected via port forwarding
- Security hardening for port forwarding
- Can specify host:port patterns or "none"
Example:
Host jump-host
PermitRemoteOpen db.internal:5432 cache.internal:6379
Implementation:
- Add
permit_remote_open: Vec<String>to SshHostConfig - Parse space-separated host:port patterns
- Support "none" and "any" special values
Additional Options (Lower Priority)
6. HostbasedAuthentication ⭐⭐
Functionality: Enable host-based authentication
Use Case: Trusted host groups, HPC clusters
7. HostbasedAcceptedAlgorithms ⭐⭐
Functionality: Specify accepted algorithms for host-based auth
Use Case: Works with HostbasedAuthentication
Technical Implementation
Files to Modify
Parser:
src/ssh/ssh_config/parser.rs:95-460- Add new option parsing
Types:
src/ssh/ssh_config/types.rs:22-68- Add new fields to SshHostConfig
Resolver:
src/ssh/ssh_config/resolver.rs- Add getter methods for new options
Security:
src/ssh/ssh_config/security.rs- Validate certificate file paths
Implementation Details
// In types.rs
pub struct SshHostConfig {
// ... existing fields ...
// Certificate authentication
pub certificate_files: Vec<PathBuf>,
pub ca_signature_algorithms: Vec<String>,
// Port forwarding controls
pub gateway_ports: Option<String>,
pub exit_on_forward_failure: Option<bool>,
pub permit_remote_open: Vec<String>,
// Host-based authentication
pub hostbased_authentication: Option<bool>,
pub hostbased_accepted_algorithms: Vec<String>,
}// In parser.rs parse_option()
"certificatefile" => {
if args.is_empty() {
anyhow::bail!("CertificateFile requires a value at line {line_number}");
}
let path = secure_validate_path(args[0], "certificate", line_number)?;
host.certificate_files.push(path);
}
"casignaturealgorithms" => {
if args.is_empty() {
anyhow::bail!("CASignatureAlgorithms requires a value at line {line_number}");
}
host.ca_signature_algorithms = args.join(",")
.split(',')
.map(|s| s.trim().to_string())
.collect();
}
"gatewayports" => {
if args.is_empty() {
anyhow::bail!("GatewayPorts requires a value at line {line_number}");
}
let value = args[0].to_lowercase();
if !["yes", "no", "clientspecified"].contains(&value.as_str()) {
anyhow::bail!("Invalid GatewayPorts value at line {line_number}");
}
host.gateway_ports = Some(value);
}
"exitonforwardfailure" => {
if args.is_empty() {
anyhow::bail!("ExitOnForwardFailure requires a value at line {line_number}");
}
host.exit_on_forward_failure = Some(parse_yes_no(args[0], line_number)?);
}
"permitremoteopen" => {
if args.is_empty() {
anyhow::bail!("PermitRemoteOpen requires a value at line {line_number}");
}
host.permit_remote_open.extend(args.iter().map(|s| s.to_string()));
}Testing Requirements
Certificate Authentication Tests:
- Parse CertificateFile with tilde expansion
- Multiple certificate files
- CASignatureAlgorithms parsing
- Invalid algorithm names
Port Forwarding Tests:
- GatewayPorts yes/no/clientspecified
- Invalid GatewayPorts values
- ExitOnForwardFailure parsing
- PermitRemoteOpen patterns
- PermitRemoteOpen "none" and "any"
Integration Tests:
- Certificate + identity file combination
- Port forwarding with GatewayPorts
- Forwarding failure behavior
Success Criteria
- CertificateFile supports multiple files
- CASignatureAlgorithms parses algorithm lists
- GatewayPorts validates yes/no/clientspecified
- ExitOnForwardFailure parses yes/no
- PermitRemoteOpen handles patterns and special values
- All options work with Option=Value syntax (from Support various Option syntax and additional SSH config options in parser #42)
- Test coverage >85%
- Documentation with examples
- No breaking changes
Dependencies
- Requires Support various Option syntax and additional SSH config options in parser #42 (Option=Value syntax) to be completed first
- Independent of [Phase 1] Add Include and Match directive support to SSH config parser #43 (Include/Match) - can be done in parallel
References
- OpenSSH CertificateFile: https://man.openbsd.org/ssh_config#CertificateFile
- OpenSSH CASignatureAlgorithms: https://man.openbsd.org/ssh_config#CASignatureAlgorithms
- OpenSSH GatewayPorts: https://man.openbsd.org/ssh_config#GatewayPorts
- OpenSSH ExitOnForwardFailure: https://man.openbsd.org/ssh_config#ExitOnForwardFailure
- OpenSSH PermitRemoteOpen: https://man.openbsd.org/ssh_config#PermitRemoteOpen
- Related issues: Support various Option syntax and additional SSH config options in parser #42, [Phase 1] Add Include and Match directive support to SSH config parser #43
Priority: High - Enterprise and production use cases
Estimated Complexity: Medium - Straightforward option additions
Activity
feat: Add certificate auth and advanced port forwarding options (#44)