Repository navigation
Description
Overview
This is Phase 4 (final) of the SSH config parser enhancement roadmap. This phase focuses on adding support for remaining useful SSH config options that improve security, user experience, and edge-case compatibility. These are lower priority but still valuable for comprehensive OpenSSH compatibility.
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, [Phase 2] Add certificate authentication and advanced port forwarding options #44, [Phase 3] Add command execution and automation options (LocalCommand, RemoteCommand, etc) #45)
- These options complete the most commonly used subset of OpenSSH config
- Improves compatibility with existing SSH configurations
- Brings total coverage to ~70-80% of OpenSSH options
Options to Implement
Host Key Verification & Security
1. NoHostAuthenticationForLocalhost ⭐⭐⭐
Importance: Medium - Common in development environments
Functionality:
- Skip host key verification for localhost connections
- Convenient for local development and testing
- Reduces known_hosts clutter
Example:
Host localhost 127.0.0.1 ::1
NoHostAuthenticationForLocalhost yes
Implementation:
- Add
no_host_authentication_for_localhost: Option<bool>to SshHostConfig - Parse yes/no values
2. HashKnownHosts ⭐⭐⭐
Importance: Medium - Security enhancement
Functionality:
- Hash hostnames in known_hosts file
- Prevents hostname disclosure if file is compromised
- Recommended for security-conscious users
Example:
Host *
HashKnownHosts yes
Implementation:
- Add
hash_known_hosts: Option<bool>to SshHostConfig - Parse yes/no values
- Document security benefits
3. CheckHostIP ⭐⭐
Importance: Low-Medium - Deprecated but still used
Status: Deprecated in OpenSSH 8.5+ (2021)
Reason: Still appears in many legacy configs
Functionality:
- Check host IP address in known_hosts
- Detects DNS spoofing
- Disabled by default in modern OpenSSH
Example:
Host *
CheckHostIP no
Implementation:
- Add
check_host_ip: Option<bool>to SshHostConfig - Parse yes/no values
- Document deprecation status
4. VisualHostKey ⭐⭐
Importance: Low - User convenience
Functionality:
- Display ASCII art representation of host key
- Helps users visually verify host identity
- Useful for security-conscious users
Example:
Host *
VisualHostKey yes
Implementation:
- Add
visual_host_key: Option<bool>to SshHostConfig - Parse yes/no values
5. HostKeyAlias ⭐⭐⭐
Importance: Medium - Useful for load balancers
Functionality:
- Use specified alias for host key lookup
- Multiple hosts share same key
- Useful for load-balanced services
Example:
Host lb-node-*
HostKeyAlias lb.example.com
Implementation:
- Add
host_key_alias: Option<String>to SshHostConfig - Parse hostname string
Authentication Options
6. NumberOfPasswordPrompts ⭐⭐
Importance: Low-Medium - User experience
Functionality:
- Control password retry attempts
- Default is 3 in OpenSSH
- Useful for automation (set to 1)
Example:
Host automated-host
NumberOfPasswordPrompts 1
Implementation:
- Add
number_of_password_prompts: Option<u32>to SshHostConfig - Parse integer value
- Validate reasonable range (1-10)
7. HostbasedAuthentication ⭐⭐
Importance: Low-Medium - Specialized use case
Functionality:
- Enable host-based authentication
- Trusted host groups
- Common in HPC clusters
Example:
Host *.cluster.local
HostbasedAuthentication yes
Implementation:
- Add
hostbased_authentication: Option<bool>to SshHostConfig - Parse yes/no values
Network & Connection Options
8. BindInterface ⭐⭐
Importance: Medium - Multi-homing
Functionality:
- Bind to specific network interface
- Alternative to BindAddress
- Useful for VPN scenarios
Example:
Host vpn-only
BindInterface tun0
Implementation:
- Add
bind_interface: Option<String>to SshHostConfig - Parse interface name
9. IPQoS ⭐⭐
Importance: Low - QoS control
Functionality:
- Set IP type-of-service/DSCP values
- Interactive vs bulk traffic prioritization
- Values: af11, af12, af13, etc.
Example:
Host *
IPQoS lowdelay throughput
Implementation:
- Add
ipqos: Option<String>to SshHostConfig - Parse QoS values (two values: interactive and bulk)
10. RekeyLimit ⭐⭐
Importance: Low - Security tuning
Functionality:
- Control SSH key renegotiation
- Format: "data [time]"
- Default: "default none"
Example:
Host *
RekeyLimit 1G 1h
Implementation:
- Add
rekey_limit: Option<String>to SshHostConfig - Parse limit string (no validation of format)
X11 Forwarding Options
11. ForwardX11Timeout ⭐⭐
Functionality: X11 forwarding timeout
Example: ForwardX11Timeout 1h
12. ForwardX11Trusted ⭐⭐
Functionality: Trust X11 forwarding
Example: ForwardX11Trusted yes
Advanced Options
13. EnableSSHKeysign ⭐
Importance: Low - Specialized
Functionality: Enable ssh-keysign for HostbasedAuthentication
Example: EnableSSHKeysign yes
14. VerifyHostKeyDNS ⭐⭐
Importance: Low-Medium - SSHFP records
Functionality: Verify host keys using DNS SSHFP records
Example: VerifyHostKeyDNS yes
15. UpdateHostKeys ⭐⭐
Importance: Low-Medium - Key rotation
Functionality: Accept updated host keys
Example: UpdateHostKeys ask
Options Intentionally Excluded
The following options are not recommended for implementation due to low usage or security concerns:
- Protocol - SSH protocol 1 is obsolete
- Cipher/MAC/KEX family - Already covered by existing options
- XAuthLocation - System-specific, rarely used
- VersionAddendum - Cosmetic, rarely used
- EnableEscapeCommandline - Complex edge case
- ObscureKeystrokeTiming - Highly specialized
- Tunnel/TunnelDevice - Layer 2/3 tunneling (rare)
- PKCS11Provider - Hardware token (complex, low usage)
- SecurityKeyProvider - FIDO2 keys (modern, but specialized)
Technical Implementation
Files to Modify
Parser:
src/ssh/ssh_config/parser.rs:95-460- Add ~15 new option cases
Types:
src/ssh/ssh_config/types.rs:22-68- Add ~15 new fields
Resolver:
src/ssh/ssh_config/resolver.rs- Add getter methods
Implementation Pattern
// In types.rs - add fields
pub struct SshHostConfig {
// ... existing fields ...
// Host key verification
pub no_host_authentication_for_localhost: Option<bool>,
pub hash_known_hosts: Option<bool>,
pub check_host_ip: Option<bool>,
pub visual_host_key: Option<bool>,
pub host_key_alias: Option<String>,
pub verify_host_key_dns: Option<String>,
pub update_host_keys: Option<String>,
// Authentication
pub number_of_password_prompts: Option<u32>,
pub hostbased_authentication: Option<bool>,
pub enable_ssh_keysign: Option<bool>,
// Network
pub bind_interface: Option<String>,
pub ipqos: Option<String>,
pub rekey_limit: Option<String>,
// X11
pub forward_x11_timeout: Option<String>,
pub forward_x11_trusted: Option<bool>,
}// In parser.rs - add parsing cases (example)
"nohostauthenticationforlocalhost" => {
if args.is_empty() {
anyhow::bail!("NoHostAuthenticationForLocalhost requires a value at line {line_number}");
}
host.no_host_authentication_for_localhost = Some(parse_yes_no(args[0], line_number)?);
}
"hashknownhosts" => {
if args.is_empty() {
anyhow::bail!("HashKnownHosts requires a value at line {line_number}");
}
host.hash_known_hosts = Some(parse_yes_no(args[0], line_number)?);
}
"hostkeyalias" => {
if args.is_empty() {
anyhow::bail!("HostKeyAlias requires a value at line {line_number}");
}
host.host_key_alias = Some(args[0].to_string());
}
"numberofpasswordprompts" => {
if args.is_empty() {
anyhow::bail!("NumberOfPasswordPrompts requires a value at line {line_number}");
}
let num: u32 = args[0].parse().with_context(|| {
format!("Invalid NumberOfPasswordPrompts value '{}' at line {}", args[0], line_number)
})?;
if num < 1 || num > 10 {
tracing::warn!("NumberOfPasswordPrompts {} at line {} is outside typical range 1-10", num, line_number);
}
host.number_of_password_prompts = Some(num);
}
"bindinterface" => {
if args.is_empty() {
anyhow::bail!("BindInterface requires a value at line {line_number}");
}
host.bind_interface = Some(args[0].to_string());
}
// ... continue for other optionsTesting Requirements
Host Key Verification:
- NoHostAuthenticationForLocalhost parsing
- HashKnownHosts parsing
- CheckHostIP parsing with deprecation note
- VisualHostKey parsing
- HostKeyAlias string storage
- VerifyHostKeyDNS yes/no/ask values
- UpdateHostKeys yes/no/ask values
Authentication:
- NumberOfPasswordPrompts integer parsing and range
- HostbasedAuthentication yes/no
- EnableSSHKeysign yes/no
Network:
- BindInterface string parsing
- IPQoS value parsing
- RekeyLimit string parsing
X11:
- ForwardX11Timeout duration parsing
- ForwardX11Trusted yes/no
Success Criteria
- All 15 priority options parsed correctly
- NumberOfPasswordPrompts validates range
- CheckHostIP includes deprecation note
- 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
- Total SSH config coverage reaches ~70-80%
Coverage Summary
After Phase 4 completion:
- Phase 1: Include, Match (structural)
- Phase 2: Certificates, port forwarding (7 options)
- Phase 3: Command execution (7 options)
- Phase 4: Remaining useful options (15 options)
- Original: 42 options
- Total: ~71 options (~69% of OpenSSH 103 options)
Remaining 32 options are highly specialized or obsolete.
Dependencies
- Requires Support various Option syntax and additional SSH config options in parser #42 (Option=Value syntax) to be completed
- Independent of other phases
- Can be developed in parallel
References
- OpenSSH ssh_config manual: https://man.openbsd.org/ssh_config
- Relevant option documentation in man page
- 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, [Phase 2] Add certificate authentication and advanced port forwarding options #44, [Phase 3] Add command execution and automation options (LocalCommand, RemoteCommand, etc) #45
Priority: Low-Medium - Nice-to-have completeness
Estimated Complexity: Low - Straightforward option additions, no complex logic
Activity
feat: implement Phase 4 SSH config options
[Phase 4] Add remaining useful SSH config options (lablup#55)