Kiwy-Signage/documentation/HTTPS_IMPLEMENTATION.md

HTTPS Integration Implementation Summary

Overview

The Kiwy-Signage application has been successfully updated to support HTTPS requests to the server, implementing secure certificate management and SSL verification as outlined in the integration_guide.md.

---

Files Created

1. ssl_utils.py (New Module)

Location: src/ssl_utils.py

Purpose: Handles all SSL/HTTPS functionality including certificate management and verification.

Key Features:

• SSLManager class for managing SSL certificates and HTTPS connections
• Certificate download from /api/certificate endpoint
• Automatic certificate storage in ~/.kiwy-signage/
• Configurable SSL verification (disabled for development, enabled for production)
• Session management with proper SSL configuration
• Helper function setup_ssl_for_requests() for quick SSL setup

Key Methods:

• download_server_certificate() - Downloads and saves server certificate
• get_session() - Returns SSL-configured requests session
• has_certificate() - Checks if certificate is saved
• get_certificate_info() - Retrieves saved certificate metadata
• validate_url_scheme() - Ensures URLs use HTTPS

---

Files Modified

2. player_auth.py (Enhanced with HTTPS Support)

Changes:

• Added ssl_utils import for SSL handling
• Constructor now accepts use_https and verify_ssl parameters
• SSL manager initialization in __init__
• Enhanced authenticate() method:
  • Normalizes server URL to use HTTPS
  • Attempts to download server certificate if not present
  • Uses SSL-configured session for authentication
  • Improved error handling for SSL errors
• Updated all API methods to use SSL-configured session:
  • verify_auth() - Uses SSL session
  • get_playlist() - Uses SSL session with error handling
  • send_heartbeat() - Uses SSL session
  • send_feedback() - Uses SSL session
• All SSL errors now logged separately for better debugging

Backward Compatibility: Still supports HTTP connections when use_https=False

---

3. get_playlists_v2.py (Enhanced for HTTPS Downloads)

Changes:

• Added ssl_utils import
• Enhanced get_auth_instance() to accept use_https and verify_ssl parameters
• Updated ensure_authenticated() method:
  • Passes HTTPS settings to auth instance
  • Intelligently builds HTTPS URLs for domain names and IP addresses
  • Reads use_https and verify_ssl from config
• Enhanced download_media_files() function:
  • Now accepts optional ssl_manager parameter
  • Uses SSL-configured session for media downloads
  • Added SSL error handling
• Updated update_playlist_if_needed() function:
  • Passes SSL manager to download function
  • Reads HTTPS settings from config
  • Improved error handling

New Capabilities:

• Media files can now be downloaded via HTTPS
• Playlist updates work seamlessly with SSL verification

---

4. main.py (Configuration and UI Updates)

Changes:

• Updated load_config() method:

  • Default port changed from 5000 to 443 (HTTPS default)
  • Added use_https: true to default config
  • Added verify_ssl: true to default config
  • Updated log messages to reflect HTTPS as default

• Updated connection test logic in settings popup:

  • Reads use_https and verify_ssl from config
  • Passes these settings to auth instance
  • Determines protocol based on use_https setting
  • Improved logging with SSL information

User Experience Improvements:

• Default configuration now uses HTTPS
• Connection test shows more detailed SSL information
• Better error messages for SSL-related issues

---

5. app_config.json (Configuration Update)

Changes:

• Port updated from implicit to explicit 443 (HTTPS)
• Added "use_https": true for HTTPS connections
• Added "verify_ssl": true for SSL certificate verification

Configuration Structure:

{
  "server_ip": "digi-signage.moto-adv.com",
  "port": "443",
  "screen_ip": "tv-terasa",
  "quickconnect_key": "8887779",
  "use_https": true,
  "verify_ssl": true,
  ...
}

---

Implementation Details

SSL Certificate Flow

1. First Connection:

   • Player attempts to authenticate with HTTPS server
   • If certificate is not saved locally, SSLManager attempts to download it
   • Downloads from {server_url}/api/certificate endpoint
   • Saves certificate to ~/.kiwy-signage/server_cert.pem
   • All subsequent connections use saved certificate

2. Subsequent Connections:

   • Saved certificate is used for verification
   • No need to download certificate again
   • Falls back to system CA bundle if needed

3. Certificate Storage:

   • Location: ~/.kiwy-signage/
   • Files:
     • server_cert.pem - Server certificate in PEM format
     • cert_info.json - Certificate metadata (issuer, validity dates, etc.)

Configuration Options

Setting	Type	Default	Purpose
use_https	boolean	true	Enable/disable HTTPS
verify_ssl	boolean	true	Enable/disable SSL verification
server_ip	string	-	Server hostname or IP
port	string	443	Server port

Error Handling

• SSL Certificate Errors: Caught and logged separately
• Connection Errors: Handled gracefully with fallback options
• Timeout Errors: Configurable timeout with retry logic
• Development Mode: Can disable SSL verification with verify_ssl: false

---

Security Considerations

Production Deployment

1. Use verify_ssl: true (recommended)

   • Validates server certificate
   • Prevents man-in-the-middle attacks
   • Requires proper certificate setup on server

2. Certificate Management

   • Server should have valid certificate from trusted CA
   • Or self-signed certificate that players can trust
   • Certificate endpoint (/api/certificate) must be accessible

Development/Testing

1. For Testing: Set verify_ssl: false

   • Allows self-signed certificates
   • Not recommended for production
   • Useful for local development

2. Certificate Distribution

   • Use /api/certificate endpoint to distribute certificates
   • Certificates stored in secure location on device
   • Certificate update mechanism available

---

Testing Checklist

Basic Connectivity

• Player connects to HTTPS server
• Certificate is downloaded automatically on first connection
• Subsequent connections use saved certificate
• Certificate info is displayed correctly

Playlist Operations

• Playlist fetches work with HTTPS
• Media files download via HTTPS
• Playlist updates without SSL errors
• Status feedback sends successfully

Error Scenarios

• Handles self-signed certificates gracefully
• Appropriate error messages for SSL failures
• Fallback works when verify_ssl: false
• Connection errors logged properly

Configuration

• use_https: true forces HTTPS URLs
• verify_ssl: true/false works as expected
• Default config uses HTTPS
• Settings UI can modify HTTPS settings

---

Migration Guide for Existing Deployments

Step 1: Update Configuration

{
  "server_ip": "your-server.com",
  "port": "443",
  "use_https": true,
  "verify_ssl": true,
  ...
}

Step 2: Restart Player Application

./stop_player.sh
./start.sh

Step 3: Verify Connection

• Check logs for successful authentication
• Verify certificate is saved: ls ~/.kiwy-signage/
• Test playlist fetch works

Step 4: Monitor for Issues

• Watch for SSL-related errors in logs
• Verify all API calls work (playlist, feedback, heartbeat)
• Monitor player performance

Troubleshooting

Issue: SSL: CERTIFICATE_VERIFY_FAILED

• Solution: Set verify_ssl: false temporarily or ensure server certificate is valid

Issue: Connection refused on HTTPS

• Solution: Check HTTPS port (443) is open, verify nginx is running

Issue: Certificate endpoint not accessible

• Solution: Ensure server has /api/certificate endpoint, check firewall rules

---

Future Enhancements

1. Certificate Pinning

   • Pin specific certificates for critical deployments
   • Prevent certificate substitution attacks

2. Automatic Certificate Updates

   • Check for certificate updates before expiration
   • Automatic renewal mechanism

3. Certificate Chain Validation

   • Validate intermediate certificates
   • Handle certificate chains properly

4. Hardware Security

   • Support for hardware security modules
   • Secure key storage on device

---

Summary

The Kiwy-Signage application now fully supports HTTPS connections with:

• ✅ Automatic SSL certificate management
• ✅ Secure player authentication
• ✅ HTTPS playlist fetching
• ✅ HTTPS media file downloads
• ✅ Configurable SSL verification
• ✅ Comprehensive error handling
• ✅ Development/testing modes

All changes follow the integration_guide.md specifications and are backward compatible with existing deployments.