iOS/docs/mTLS.md

mTLS (Mutual TLS) Support

⚠️ EXPERIMENTAL FEATURE

This feature is experimental and may change or be removed in future versions. Use at your own risk and report any issues you encounter.

What is mTLS?

Mutual TLS (mTLS) is a security protocol where both the client and server authenticate each other using certificates. Unlike standard TLS where only the server presents a certificate, mTLS requires the client to also present a valid certificate.

This is commonly used to:

• Secure Home Assistant access behind a reverse proxy (nginx, Traefik, etc.)
• Add an extra layer of authentication beyond username/password
• Restrict access to devices with trusted certificates only

How It Works

┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│   iOS App    │  mTLS   │    Nginx     │  HTTP   │     Home     │
│              │◄───────►│   (Proxy)    │◄───────►│  Assistant   │
│ + Client Cert│         │ + Server Cert│         │              │
└──────────────┘         └──────────────┘         └──────────────┘

1. Server Certificate: The reverse proxy (e.g., nginx) presents its SSL certificate
2. Client Certificate: The iOS app presents its client certificate (.p12 file)
3. Mutual Verification: Both sides verify each other's certificates
4. Secure Connection: Once verified, traffic flows through encrypted tunnel

Setup Requirements

1. Generate Certificates

You'll need:

• A Certificate Authority (CA) certificate
• A server certificate signed by the CA
• A client certificate signed by the CA (exported as .p12)

Example using OpenSSL:

# Create CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -subj "/CN=My Home CA"

# Create Server Certificate
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/CN=homeassistant.local"
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

# Create Client Certificate
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/CN=ios-app"
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

# Export client certificate as .p12 (for iOS)
openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt -certfile ca.crt -password pass:your_password

2. Configure Reverse Proxy (nginx example)

server {
    listen 8443 ssl;
    server_name homeassistant.local;

    # Server certificate
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;

    # mTLS - require client certificate
    ssl_client_certificate /path/to/ca.crt;
    ssl_verify_client on;

    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://homeassistant:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

3. Transfer Client Certificate to iOS

Transfer the .p12 file to your iOS device via:

• AirDrop
• iCloud Drive
• Email attachment
• Any file sharing method

Using mTLS in the App

During Onboarding

1. Enter your Home Assistant URL (e.g., https://homeassistant.local:8443)
2. If the server requires mTLS, you'll see a prompt to import a client certificate
3. Tap "Import Certificate" and select your .p12 file
4. Enter the password used when creating the .p12 file
5. Continue with normal login flow

Certificate Storage

• Certificates are stored securely in the iOS Keychain
• The certificate reference is saved with your server configuration
• Certificates persist across app reinstalls (stored in Keychain)

Troubleshooting

"SSL Handshake Failed" or Connection Errors

• Verify your client certificate is signed by the same CA configured on the server
• Check that the .p12 file includes the full certificate chain
• Ensure the certificate hasn't expired

"Certificate Required" but No Prompt

• Make sure you're using HTTPS, not HTTP
• Verify the server is actually requiring client certificates (ssl_verify_client on)

WebSocket Connection Issues

• Check that your proxy configuration supports WebSocket upgrade
• Verify the proxy passes through the client certificate for WebSocket connections

Webhook Errors

• Webhooks use a separate connection that also requires the client certificate
• If webhooks fail with 400/401 errors, verify the certificate is properly configured

Technical Details

The app handles mTLS at three different layers:

1. Alamofire (HTTP requests): Uses ClientCertificateSessionDelegate to provide client certificates for API calls

2. HAKit/Starscream (WebSocket): Uses FoundationTransport with custom SSL stream configuration for the WebSocket connection to Home Assistant

3. WebhookManager (Background uploads): Uses ConnectionInfo.evaluate() to handle client certificate challenges for webhook requests

Limitations

• watchOS: mTLS is not supported on Apple Watch due to platform limitations
• Local Push: May not work with mTLS configurations
• Siri/Shortcuts: May have limited functionality with mTLS

Security Considerations

• Keep your .p12 file and password secure
• Use strong passwords when exporting certificates
• Rotate certificates periodically
• Revoke compromised certificates immediately by updating your CA

---

Need Help?

If you encounter issues with mTLS:

1. Check the app logs (Settings → Debug → Export Logs)
2. Verify your certificate chain with: openssl verify -CAfile ca.crt client.crt
3. Test your nginx configuration: nginx -t

---

This documentation is for the experimental mTLS feature in the Home Assistant iOS app.