Security Best Practices¶

This guide covers security considerations for aiohomematic and the Homematic(IP) Local integration.

Overview¶

aiohomematic communicates with your Homematic backend (CCU/Homegear) using XML-RPC and JSON-RPC protocols. Securing this communication protects your smart home from unauthorized access.

CCU, OpenCCU (RaspberryMatic), and Homegear have had serious security vulnerabilities in the past, including unauthenticated remote code execution. Never expose your backend to the internet and keep firmware updated.

Known Backend Vulnerabilities¶

Critical: Never Expose to Internet¶

Homematic backends (CCU2, CCU3, OpenCCU, Homegear) are not designed for internet exposure. Historical vulnerabilities include:

Required Actions¶

1. Keep firmware updated - Install security patches immediately
2. Never port-forward CCU ports - Use VPN for remote access
3. Isolate on separate VLAN - Limit blast radius of potential compromise
4. Enable authentication - Even on internal network
5. Remove unused add-ons - XML-API, CUxD have had vulnerabilities

Checking Your Version¶

CCU/OpenCCU:

1. CCU WebUI → Settings → Control Panel → System
2. Check firmware version
3. Compare with latest OpenCCU release

Homegear:

homegear -v

Security Advisories¶

Monitor these sources for new vulnerabilities:

• OpenCCU Security Advisories
• eQ-3 CVE List
• Homegear GitHub

Authentication¶

CCU Authentication¶

Always enable authentication on your CCU:

1. CCU WebUI → Settings → Control Panel → Security
2. Enable Authentication
3. Create a dedicated user for Home Assistant

User Requirements¶

Password Requirements¶

Only these characters are supported in passwords:

A-Z  a-z  0-9  . ! $ ( ) : ; # -

Not supported:

• Umlauts: Ä ä Ö ö Ü ü ß
• Other special characters: @ & * % ^ ~
• Unicode characters

These work in CCU WebUI but fail via XML-RPC.

TLS Configuration¶

Enabling TLS¶

1. Enable TLS on CCU first:

2. CCU WebUI → Settings → Control Panel → Security

3. Enable HTTPS

4. Configure integration:

5. Enable "Use TLS" in integration settings
6. Set "Verify TLS" based on certificate type

Certificate Types¶

TLS Ports¶

Network Security¶

Firewall Configuration¶

Inbound to CCU (from Home Assistant):

Inbound to Home Assistant (from CCU):

Network Segmentation¶

Recommended network architecture:

Internet
    │
    ▼
┌─────────────────┐
│  Router/FW      │  ← No inbound from internet
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐  ┌───────┐
│  IoT  │  │ Main  │
│ VLAN  │  │ LAN   │
│       │  │       │
│ CCU   │  │  HA   │  ← Allow CCU ↔ HA only
│       │  │       │
└───────┘  └───────┘

Docker Security¶

For Docker installations:

Recommended: Use network_mode: host

Alternative (Bridge Network):

1. Set callback_host to Docker host IP
2. Only expose callback port (not all CCU ports)
3. Use internal Docker network where possible

services:
  homeassistant:
    network_mode: host # Recommended for callback support
    # OR with bridge:
    ports:
      - "8123:8123" # HA UI
      - "43439:43439" # Callback port only

Secrets Management¶

Never Commit Credentials¶

Exclude from version control:

# .gitignore
*.env
secrets.yaml
credentials.json

Home Assistant Secrets¶

Use secrets.yaml:

# secrets.yaml (not in version control)
ccu_password: your-secure-password

# configuration.yaml
homematic:
  password: !secret ccu_password

Environment Variables¶

For standalone library use:

import os
from aiohomematic.api import HomematicAPI

async with HomematicAPI.connect(
    host=os.environ["CCU_HOST"],
    username=os.environ["CCU_USER"],
    password=os.environ["CCU_PASSWORD"],
) as api:
    ...

Access Control¶

Principle of Least Privilege¶

• Create dedicated CCU user for Home Assistant
• Don't use main admin account
• Disable CCU user when not in use (maintenance)

Network Access¶

• Restrict CCU management interface to trusted IPs
• Use VPN for remote access (not port forwarding)
• Monitor CCU access logs

Security Checklist¶

Common Security Issues¶

Issue: "Authentication failed"¶

Causes:

• Wrong username/password
• Password contains unsupported characters
• User lacks admin privileges

Solution:

1. Verify credentials in CCU WebUI
2. Check password for special characters
3. Verify user role is Administrator

Issue: Callbacks not working¶

Causes:

• Firewall blocking CCU → HA
• Incorrect callback_host setting

Solution:

1. Ensure CCU can reach HA on callback port
2. Set callback_host to HA's IP (not localhost)
3. Check Docker network configuration

Reporting Security Issues¶

Report security vulnerabilities privately:

1. Do not open public GitHub issues for security bugs
2. Contact maintainers directly via GitHub security advisories
3. Allow time for fix before public disclosure

Related Documentation¶

• Troubleshooting - Connection issues
• CUxD and CCU-Jack - MQTT security
• User Guide - Configuration