Files

Deployment System c4e43ce69b HTTPS/CORS improvements: Enable CORS for player connections, secure session cookies, add certificate endpoint, nginx CORS headers

2026-01-16 22:29:49 +02:00

13 KiB

Raw Permalink Blame History

Kiwy-Signage Player HTTPS/SSL Analysis - Complete Documentation

Overview

This documentation provides a comprehensive analysis of how the Kiwy-Signage player (https://gitea.moto-adv.com/ske087/Kiwy-Signage.git) handles HTTPS connections and SSL certificate verification, along with implementation guides for adding self-signed certificate support.

Analysis Date: January 16, 2026
Player Version: Latest from repository
Server Compatibility: DigiServer v2

Key Findings

Current State

✅ HTTPS Support: Yes, fully functional for CA-signed certificates
❌ Self-Signed Certificates: NOT supported without code modifications
❌ Custom CA Bundles: NOT supported without code modifications
✅ SSL Verification: Enabled by default (uses requests library defaults)
⚠️ Hardcoded Settings: None (relies entirely on requests library)

Architecture

HTTP Client: Python requests library (v2.32.4)
HTTPS Requests: 6 locations in 2 main files
Certificate Verification: Implicit verify=True (default behavior)
Configuration: Via config/app_config.json (no SSL options currently)

Documentation Files

1. 📋 KIWY_PLAYER_HTTPS_ANALYSIS.md

Main technical analysis document - Start here for comprehensive understanding

Contents:

Executive summary
HTTP client library details
Main connection files and locations
HTTPS connection architecture
Certificate verification code analysis
Current SSL/certificate behavior
Required changes for self-signed support
Testing instructions
Summary tables and references

Read this if you need: Full technical details, code references, line numbers

2. ⚡ KIWY_PLAYER_HTTPS_QUICK_REF.md

Quick reference guide - Use this for quick lookups and summaries

Contents:

Quick facts and key statistics
Where HTTPS requests are made (code locations)
What gets sent over HTTPS (data flow)
The problem with self-signed certificates
How to enable self-signed certificate support
Configuration files overview
Network flow diagrams
SSL error troubleshooting
Testing instructions

Read this if you need: Quick answers, quick start, troubleshooting

3. 🔧 KIWY_PLAYER_SSL_PATCHES.md

Implementation guide with exact code patches - Use this to implement the changes

Contents:

Complete PATCH 1: Create ssl_config.py (NEW FILE)
Complete PATCH 2: Modify src/player_auth.py (7 changes)
Complete PATCH 3: Modify src/get_playlists_v2.py (2 changes)
PATCH 4: Extract server certificate
PATCH 5: Using environment variables
Testing procedures after patches
Implementation checklist
Rollback instructions

Read this if you need: To implement self-signed certificate support

4. 📐 KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md

Visual architecture and flow diagrams - Use this to understand the system visually

Contents:

Current architecture before patches (with ASCII diagrams)
New architecture after patches
Certificate resolution flow
File structure before/after
Deployment scenarios (production, self-signed, dev)
Request flow sequence diagram
Error handling flow
Security comparison table

Read this if you need: Visual understanding, deployment planning

I want to...

Understand how the player works: → Read KIWY_PLAYER_HTTPS_ANALYSIS.md Section 3

Find where HTTPS requests happen: → Read KIWY_PLAYER_HTTPS_QUICK_REF.md "Where HTTPS Requests Are Made"

Implement self-signed cert support: → Follow KIWY_PLAYER_SSL_PATCHES.md step by step

See a visual diagram: → Read KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md

Understand the problem: → Read KIWY_PLAYER_HTTPS_QUICK_REF.md "The Problem with Self-Signed Certificates"

Check specific code lines: → Read KIWY_PLAYER_HTTPS_ANALYSIS.md Section 3 "All HTTPS Request Points"

See the recommended solution: → Read KIWY_PLAYER_HTTPS_ANALYSIS.md Section 6 "Option 2: Custom CA Certificate Bundle"

Implementation Path

For Production Deployment (Recommended)

Review the analysis
- Read KIWY_PLAYER_HTTPS_ANALYSIS.md sections 1-5
- Understand current limitations and proposed solution
Plan the implementation
- Review KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md deployment scenarios
- Decide on environment-specific configurations
Implement patches
- Follow KIWY_PLAYER_SSL_PATCHES.md
- Create src/ssl_config.py
- Modify src/player_auth.py (7 changes)
- Modify src/get_playlists_v2.py (2 changes)
Deploy certificates
- Export certificate from DigiServer
- Place in config/ca_bundle.crt
- Verify using KIWY_PLAYER_SSL_PATCHES.md Test section
Test thoroughly
- Test with self-signed server
- Test with production server (verify backward compatibility)
- Monitor player logs for SSL errors
Document
- Update player README with SSL certificate setup instructions
- Document certificate rotation procedures

For Quick Testing (Development)

Review KIWY_PLAYER_HTTPS_QUICK_REF.md "Quickest Fix"
Use SSLConfig.disable_verification() temporarily
⚠️ Never use in production

File Summary

File	Purpose	Length	Best For
KIWY_PLAYER_HTTPS_ANALYSIS.md	Main technical document	~400 lines	Complete understanding
KIWY_PLAYER_HTTPS_QUICK_REF.md	Quick reference	~300 lines	Quick lookups
KIWY_PLAYER_SSL_PATCHES.md	Implementation guide	~350 lines	Applying changes
KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md	Visual diagrams	~400 lines	Visual learning

Key Statistics

Current Implementation

HTTP Client Library: requests v2.32.4
HTTPS Request Locations: 6 (5 in player_auth.py, 1 in get_playlists_v2.py)
Lines With Certificate Handling: 0 (all use implicit defaults)
SSL Configuration Options: 0 (all use system defaults)
Custom CA Support: ❌ Not implemented

After Patches

New Files: 1 (ssl_config.py)
Modified Files: 2 (player_auth.py, get_playlists_v2.py)
Code Lines Added: ~60 (new module)
Code Lines Modified: ~8 (in existing modules)
New Dependencies: 0 (uses existing requests library)
Breaking Changes: 0 (fully backward compatible)

Code Locations

src/player_auth.py:

Line 95: requests.post(auth_url, ...)
Line 157: requests.post(verify_url, ...)
Line 178: requests.get(playlist_url, ...)
Line 227: requests.post(heartbeat_url, ...)
Line 254: requests.post(feedback_url, ...)

src/get_playlists_v2.py:

Line 159: requests.get(file_url, ...)

Configuration

Current Configuration (No SSL Options)

File: config/app_config.json

{
  "server_ip": "digi-signage.moto-adv.com",
  "port": "443",
  "screen_name": "tv-terasa",
  "quickconnect_key": "8887779",
  "orientation": "Landscape",
  "touch": "True",
  "max_resolution": "1920x1080",
  "edit_feature_enabled": true
}

After Patches - New Files

New: config/ca_bundle.crt (Certificate file)

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1/iNAZwqDMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
... (certificate content)
-----END CERTIFICATE-----

New: src/ssl_config.py (Module for SSL configuration)

Architecture Overview

Before Patches

Player Application
  ├─ main.py (GUI)
  ├─ player_auth.py (Auth)
  └─ get_playlists_v2.py (Playlists)
        │
        ├─ requests.post/get(..., timeout=30)
        │  └─ Uses default: verify=True
        │     └─ Only works with CA-signed certs
        │
        └─ Python requests library
           └─ System CA certificates
              ├─ Production certs: ✅ Works
              └─ Self-signed certs: ❌ Fails

After Patches

Player Application
  ├─ main.py (GUI)
  ├─ player_auth.py (Auth) [MODIFIED]
  ├─ get_playlists_v2.py (Playlists) [MODIFIED]
  └─ ssl_config.py [NEW]
        │
        ├─ requests.post/get(..., verify=ca_bundle)
        │  └─ Uses SSLConfig.get_verify_setting()
        │     └─ Works with multiple cert types
        │
        └─ Python requests library
           ├─ Custom CA: 'config/ca_bundle.crt'
           ├─ Env var: REQUESTS_CA_BUNDLE
           ├─ System certs: True
           │
           ├─ Production certs: ✅ Works
           ├─ Self-signed certs: ✅ Works (with ca_bundle.crt)
           └─ Custom CA: ✅ Works (with env var)

Security Considerations

Current Implementation ✅

✅ SSL certificate verification enabled
✅ Works securely with CA-signed certificates
✅ No hardcoded insecure defaults
✅ Uses Python best practices

Self-Signed Support (After Patches) ✅

✅ Maintains security with custom CA verification
✅ No downgrade to insecure verify=False
✅ Backward compatible with production
✅ Supports environment-specific configurations

NOT Recommended

❌ Using verify=False in production
❌ Disabling SSL verification permanently
❌ Ignoring certificate errors
❌ Man-in-the-middle attack risks

Troubleshooting

Common Issues

Problem: "certificate verify failed" Solution: See KIWY_PLAYER_HTTPS_QUICK_REF.md "SSL Error Troubleshooting"

Problem: Player won't connect to DigiServer Solution: See KIWY_PLAYER_HTTPS_ANALYSIS.md Section 5

Problem: Not sure if patches are applied correctly Solution: See KIWY_PLAYER_SSL_PATCHES.md "Testing After Patches"

Problem: Need to rollback changes Solution: See KIWY_PLAYER_SSL_PATCHES.md "Rollback Instructions"

References

Source Repository

URL: https://gitea.moto-adv.com/ske087/Kiwy-Signage.git
Main Files:
- src/player_auth.py - Authentication and API communication
- src/get_playlists_v2.py - Playlist management
- src/main.py - GUI application
- config/app_config.json - Configuration

Python Libraries Used

requests v2.32.4 - HTTP client with SSL support
kivy ≥2.3.0 - GUI framework
aiohttp v3.9.1 - Async HTTP (not used for auth)

Changelog

2026-01-16 - Initial Analysis

Complete HTTPS analysis of Kiwy-Signage player
Identified 6 locations making HTTPS requests
Documented lack of self-signed certificate support
Created 4 comprehensive documentation files
Provided ready-to-apply code patches
Created visual architecture diagrams

Support and Questions

If you have questions about:

How HTTPS works in the player: See KIWY_PLAYER_HTTPS_ANALYSIS.md
How to implement changes: See KIWY_PLAYER_SSL_PATCHES.md
Specific code locations: See KIWY_PLAYER_HTTPS_QUICK_REF.md
Visual understanding: See KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md

Document Status

Document	Status	Last Updated	Completeness
KIWY_PLAYER_HTTPS_ANALYSIS.md	✅ Complete	2026-01-16	100%
KIWY_PLAYER_HTTPS_QUICK_REF.md	✅ Complete	2026-01-16	100%
KIWY_PLAYER_SSL_PATCHES.md	✅ Complete	2026-01-16	100%
KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md	✅ Complete	2026-01-16	100%

Next Steps

Read the main analysis: Start with KIWY_PLAYER_HTTPS_ANALYSIS.md
Review your requirements: Decide if you need self-signed certificate support
Plan implementation: Use KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md for deployment scenarios
Apply patches: Follow KIWY_PLAYER_SSL_PATCHES.md step by step
Test thoroughly: Verify with both production and self-signed servers
Deploy: Roll out to player devices and monitor logs

Created: January 16, 2026
For: DigiServer v2 Integration
Repository: https://gitea.moto-adv.com/ske087/Kiwy-Signage.git

13 KiB Raw Permalink Blame History

Kiwy-Signage Player HTTPS/SSL Analysis - Complete Documentation

Overview

Key Findings

Current State

Architecture

Documentation Files

1. 📋 KIWY_PLAYER_HTTPS_ANALYSIS.md

2. ⚡ KIWY_PLAYER_HTTPS_QUICK_REF.md

3. 🔧 KIWY_PLAYER_SSL_PATCHES.md

4. 📐 KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md

Quick Navigation

I want to...

Implementation Path

For Production Deployment (Recommended)

For Quick Testing (Development)

File Summary

Key Statistics

Current Implementation

After Patches

Code Locations

Configuration

Current Configuration (No SSL Options)

After Patches - New Files

Architecture Overview

Before Patches

After Patches

Security Considerations

Current Implementation ✅

Self-Signed Support (After Patches) ✅

NOT Recommended

Troubleshooting

Common Issues

References

Source Repository

Python Libraries Used

Related Documentation

Changelog

2026-01-16 - Initial Analysis

Support and Questions

Document Status

Next Steps

13 KiB

Raw Permalink Blame History