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:**
```json
{
  "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
```json
{
  "server_ip": "your-server.com",
  "port": "443",
  "use_https": true,
  "verify_ssl": true,
  ...
}
```

### Step 2: Restart Player Application
```bash
./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.