[Phase 4] Add remaining useful SSH config options

[inureyes]

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 options

Testing 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