HTTPS/CORS improvements: Enable CORS for player connections, secure session cookies, add certificate endpoint, nginx CORS headers
This commit is contained in:
Deployment System
@@ -0,0 +1,395 @@
|
||||
# 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](./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](./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](./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](./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
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### I want to...
|
||||
|
||||
**Understand how the player works:**
|
||||
→ Read [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md) Section 3
|
||||
|
||||
**Find where HTTPS requests happen:**
|
||||
→ Read [KIWY_PLAYER_HTTPS_QUICK_REF.md](./KIWY_PLAYER_HTTPS_QUICK_REF.md) "Where HTTPS Requests Are Made"
|
||||
|
||||
**Implement self-signed cert support:**
|
||||
→ Follow [KIWY_PLAYER_SSL_PATCHES.md](./KIWY_PLAYER_SSL_PATCHES.md) step by step
|
||||
|
||||
**See a visual diagram:**
|
||||
→ Read [KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md](./KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md)
|
||||
|
||||
**Understand the problem:**
|
||||
→ Read [KIWY_PLAYER_HTTPS_QUICK_REF.md](./KIWY_PLAYER_HTTPS_QUICK_REF.md) "The Problem with Self-Signed Certificates"
|
||||
|
||||
**Check specific code lines:**
|
||||
→ Read [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md) Section 3 "All HTTPS Request Points"
|
||||
|
||||
**See the recommended solution:**
|
||||
→ Read [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md) Section 6 "Option 2: Custom CA Certificate Bundle"
|
||||
|
||||
---
|
||||
|
||||
## Implementation Path
|
||||
|
||||
### For Production Deployment (Recommended)
|
||||
|
||||
1. **Review the analysis**
|
||||
- Read [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md) sections 1-5
|
||||
- Understand current limitations and proposed solution
|
||||
|
||||
2. **Plan the implementation**
|
||||
- Review [KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md](./KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md) deployment scenarios
|
||||
- Decide on environment-specific configurations
|
||||
|
||||
3. **Implement patches**
|
||||
- Follow [KIWY_PLAYER_SSL_PATCHES.md](./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)
|
||||
|
||||
4. **Deploy certificates**
|
||||
- Export certificate from DigiServer
|
||||
- Place in `config/ca_bundle.crt`
|
||||
- Verify using [KIWY_PLAYER_SSL_PATCHES.md](./KIWY_PLAYER_SSL_PATCHES.md) Test section
|
||||
|
||||
5. **Test thoroughly**
|
||||
- Test with self-signed server
|
||||
- Test with production server (verify backward compatibility)
|
||||
- Monitor player logs for SSL errors
|
||||
|
||||
6. **Document**
|
||||
- Update player README with SSL certificate setup instructions
|
||||
- Document certificate rotation procedures
|
||||
|
||||
### For Quick Testing (Development)
|
||||
|
||||
1. Review [KIWY_PLAYER_HTTPS_QUICK_REF.md](./KIWY_PLAYER_HTTPS_QUICK_REF.md) "Quickest Fix"
|
||||
2. Use `SSLConfig.disable_verification()` temporarily
|
||||
3. ⚠️ **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`
|
||||
```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](./KIWY_PLAYER_HTTPS_QUICK_REF.md) "SSL Error Troubleshooting"
|
||||
|
||||
**Problem:** Player won't connect to DigiServer
|
||||
**Solution:** See [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md) Section 5
|
||||
|
||||
**Problem:** Not sure if patches are applied correctly
|
||||
**Solution:** See [KIWY_PLAYER_SSL_PATCHES.md](./KIWY_PLAYER_SSL_PATCHES.md) "Testing After Patches"
|
||||
|
||||
**Problem:** Need to rollback changes
|
||||
**Solution:** See [KIWY_PLAYER_SSL_PATCHES.md](./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)
|
||||
|
||||
### Related Documentation
|
||||
- [Python requests SSL verification](https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification)
|
||||
- [OpenSSL certificate export](https://www.ssl.com/article/exporting-certificate-from-browser/)
|
||||
- [Requests CA bundle documentation](https://docs.python-requests.org/en/latest/user/advanced/)
|
||||
|
||||
---
|
||||
|
||||
## 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](./KIWY_PLAYER_HTTPS_ANALYSIS.md)
|
||||
- **How to implement changes:** See [KIWY_PLAYER_SSL_PATCHES.md](./KIWY_PLAYER_SSL_PATCHES.md)
|
||||
- **Specific code locations:** See [KIWY_PLAYER_HTTPS_QUICK_REF.md](./KIWY_PLAYER_HTTPS_QUICK_REF.md)
|
||||
- **Visual understanding:** See [KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md](./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
|
||||
|
||||
1. **Read the main analysis:** Start with [KIWY_PLAYER_HTTPS_ANALYSIS.md](./KIWY_PLAYER_HTTPS_ANALYSIS.md)
|
||||
2. **Review your requirements:** Decide if you need self-signed certificate support
|
||||
3. **Plan implementation:** Use [KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md](./KIWY_PLAYER_ARCHITECTURE_DIAGRAM.md) for deployment scenarios
|
||||
4. **Apply patches:** Follow [KIWY_PLAYER_SSL_PATCHES.md](./KIWY_PLAYER_SSL_PATCHES.md) step by step
|
||||
5. **Test thoroughly:** Verify with both production and self-signed servers
|
||||
6. **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
|
||||
|
||||
Reference in New Issue
Block a user