Add SSL Certificate Verification Control

[busche]

Summary

Adds a new data_source.ssl_ignore configuration option to allow users to disable SSL/TLS certificate verification when connecting to Home Assistant or OpenHAB instances with self-signed or private CA certificates.

Motivation & Use Case

Users deploying Home Assistant or OpenHAB in isolated private networks may use self-signed or internally-signed certificates for HTTPS. Previously, EOS Connect would reject these connections with SSL verification errors, forcing either:

1. Downgrading to unencrypted HTTP (security risk)
2. Using complex workarounds (custom CA bundles, network proxies)

This feature addresses a common real-world scenario in home automation setups where users have legitimate self-signed certificates in trustednetworks but lack Let's Encrypt support (e.g., on internal DNS, behind firewalls).

Changes Made

1. Configuration Schema (src/config_web/schema.py)

• Added data_source.ssl_ignore boolean field (expert level, default: False)
• Field is conditional: only visible when data_source.type is "homeassistant" or "openhab"
• Marked as restart_required for safety (prevents accidental toggles without full startup)

2. LoadInterface Implementation (src/interfaces/load_interface.py)

• Reads ssl_ignore config value in __init__ and stores as instance variable
• Logs security warning when enabled: "[LOAD-IF] ssl_ignore=True: SSL certificate verification is disabled. Only use this with a trusted private network."
• Modified __request_with_retries() to pass verify=not self.ssl_ignore to both:
  • requests.get() calls
  • requests.request() calls

3. Documentation

• README.md: Added security note after Proxmox section explaining the feature, its limitations, and mentioning that custom CA support is planned for future releases
• docs/user-guide/configuration.html: Comprehensive documentation including:
  • Parameter reference table
  • Prominent security warning (red alert box)
  • Troubleshooting section with example SSL errors
  • Step-by-step guidance (preferred: use Let's Encrypt; alternative: enable ssl_ignore)
  • Real-world configuration example
  • Future enhancement note

System Impact

Security Implications:

• Low risk in intended use case: Disabled only in isolated private networks under user's explicit control
• Protected by defaults: Certificate verification is enabled by default; must be explicitly toggled in expert settings
• No global suppression: Unlike some approaches, we do NOT suppress urllib3 warnings globally — user logs will clearly show SSL warnings
• Requires restart: Configuration change requires restart to prevent accidental toggles without full reinitialization

Backward Compatibility:

• ✅ No breaking changes
• ✅ Existing configs unaffected (defaults to False)
• ✅ All 22 existing LoadInterface tests continue to pass

Resource Impact:

• Minimal: Single boolean check per HTTP request
• No additional dependencies added

Testing

Tests Added

1. test_request_with_retries_ssl_verify_false: Verifies that verify=False is passed to requests.get() when ssl_ignore=True
2. test_request_with_retries_ssl_verify_default: Verifies that verify=True (default) is used when ssl_ignore is not set

Test Execution Results

tests/interfaces/test_load_interface.py::test_request_with_retries_ssl_verify_false PASSED
tests/interfaces/test_load_interface.py::test_request_with_retries_ssl_verify_default PASSED

22 passed in 0.48s ✓ All existing tests continue to pass

Coverage

• ✅ Unit tests for both SSL enabled/disabled paths
• ✅ Both requests.get() and requests.request() verified
• ✅ Integration tests with mock HTTP responses
• ✅ No breaking changes to existing functionality

Not Yet Tested / Future Considerations

1. End-to-End Integration Testing

   • Real Home Assistant instance with self-signed certificate
   • Real OpenHAB instance with private CA certificate
   • Verification that data collection succeeds after enabling flag

2. CA Bundle Support (Feature for Future)

   • Currently no mechanism to supply custom root CA certificates
   • Load from REQUESTS_CA_BUNDLE environment variable or system CA store could be added
   • Related: Consider certifi library for enhanced CA handling

3. Wire-Level Testing

   • Pcap/tcpdump verification that HTTPS connection is established without errors
   • Performance impact measurement (negligible expected, but could be validated)

4. Edge Cases Not Yet Covered

   • Certificate expiration scenarios
   • Chain-of-trust failures (could test by intentionally failing verification)
   • Mixed scenarios (ssl_ignore on one interface, strict on another)

5. Documentation in Other Formats

   • Config export/import scenarios (JSON/YAML export should preserve setting)
   • API documentation for REST endpoint /api/config/ (schema already exports the field)

Deployment Notes

• No database migration required (SQLite schema handles new fields automatically)
• No runtime dependencies added
• Restart required for toggle to take effect (enforced by schema)

Related Issues/PRs

• Addresses: Users unable to connect to Home Assistant/OpenHAB with self-signed HTTPS certificates
• Future: Custom CA bundle support
• Future: Configuration UI visual indicator when ssl_ignore is enabled (security awareness)

Checklist

• Code follows project style guidelines
• All existing tests pass
• New tests added for ssl_ignore feature
• Documentation updated (README + configuration.html)
• Security implications documented
• Default behavior is secure (certificate verification enabled)
• No breaking changes to existing APIs
• Config schema updated and exported

---

Ready for review ✅

[busche]

note: especially for real-world testing, I am feeling myself currently unable to do so.

I did my best to address the topic and issues from my point of code-knowledge. Feel free to guide me through real-world testing. Thank you