# 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