🪪 Certificate Configuration Guide

This guide explains the certificate status (cert status) displayed in the app and helps you understand what each status means, what actions you should take, and which settings to configure based on your environment.

Certificate Status Overview

The app displays the connection security status for each server. Here are all possible statuses:

Status	Security Level	Description
HTTPS Verified	Highest	Valid CA-signed certificate
HTTPS Pinned	High	Certificate fingerprint verified
Don’t check SSL certificate	Low	All certificate validation disabled
HTTPS Untrusted Allowed	Low	Untrusted certificates or incomplete chains accepted
HTTP	None	Unencrypted connection
HTTPS Pin Mismatch	Error	Pinned fingerprint doesn’t match
HTTPS Untrusted Blocked	Error	Self-signed certificate rejected

---

Certificate Status Details

HTTPS Verified

What it means:

• The server has a valid SSL certificate signed by a trusted Certificate Authority (CA)
• This is the most secure and recommended configuration

When this appears:

• Server uses a certificate from Let’s Encrypt, DigiCert, or other trusted CAs
• “Allow untrusted certificates” is OFF

User action:

• No action needed. This is the ideal state.

Recommended for:

• Production environments
• Servers accessible over the internet
• Users with reverse proxy setups using Let’s Encrypt

---

HTTPS Pinned

What it means:

• The app has saved (pinned) the server’s certificate fingerprint
• Each connection verifies the fingerprint matches the saved value
• Provides protection against certificate tampering or MITM attacks

When this appears:

• “Allow untrusted certificates” is ON
• You’ve connected and pinned the certificate fingerprint

User action:

• Verify the fingerprint matches your server’s actual certificate (out-of-band verification recommended)
• If you regenerate your server’s certificate, you’ll need to update the pin

Recommended for:

• Self-signed certificate users who want additional security
• Users who can verify the certificate fingerprint manually

Tip

You can view and update the pinned fingerprint from the server’s menu by selecting “View certificate” or “Update”.

---

Don’t check SSL certificate

What it means:

• All SSL/TLS certificate validation is disabled
• The app accepts any certificate without verification

When this appears:

• “Don’t check SSL certificate” option is ON

User action:

• Use only on trusted local networks
• Consider setting up a proper certificate instead

Caution

This setting bypasses all security checks. Only use this when absolutely necessary and on trusted networks.

Recommended for:

• Pi-hole running in Docker without proper TLS termination
• Temporary troubleshooting
• Isolated local networks with no external access

---

HTTPS Untrusted Allowed

What it means:

• The server’s certificate is not trusted by this device
• The app is configured to accept untrusted certificates
• No certificate pinning is active
• Common causes: self-signed certificate, incomplete certificate chain (e.g., using cert.pem instead of fullchain.pem)

When this appears:

• Server uses a self-signed certificate or an incomplete certificate chain
• “Allow untrusted certificates” is ON
• Certificate has not been pinned yet

User action:

• For better security, pin the certificate fingerprint when prompted
• Or consider getting a CA-signed certificate

---

HTTP

What it means:

• Connection is unencrypted
• Data is transmitted in plain text

When this appears:

• Server URL uses http:// scheme

User action:

• Consider enabling HTTPS on your Pi-hole server for better security
• Acceptable only on isolated local networks

Caution

HTTP connections transmit your API token/password in plain text. Anyone on the same network could potentially intercept this data.

---

HTTPS Pin Mismatch

What it means:

• The server’s certificate fingerprint doesn’t match the pinned value
• Connection is blocked for security

When this appears:

• Server certificate was renewed or regenerated
• Potential MITM attack (rare but possible)

User action:

1. Verify if you recently changed your server’s certificate
2. If intentional change: Update the pinned fingerprint from server settings
3. If unexpected: Investigate before updating the pin

Danger

If you didn’t change your certificate, this could indicate a security issue. Verify your server’s certificate before updating the pin.

---

HTTPS Untrusted Blocked

What it means:

• The server’s certificate is not trusted by this device
• “Allow untrusted certificates” is OFF
• Connection is blocked

When this appears:

• Attempting to connect to a server with a self-signed certificate or an incomplete certificate chain (e.g., using cert.pem instead of fullchain.pem)
• App default settings are in effect

User action:

• Enable “Allow untrusted certificates” in server settings as a workaround
• Or fix the root cause: use a CA-signed certificate, or ensure the full chain is served (use fullchain.pem)

---

Default App Settings

By default, the app has:

• Allow untrusted certificates: ON
• Don’t check SSL certificate: OFF

Note

If your Pi-hole server uses a valid CA-signed certificate (e.g., Let’s Encrypt), you should turn OFF “Allow untrusted certificates” to achieve the “HTTPS Verified” status.

---

After App Update: Backward Compatibility

v1.8.0 Update Notice

This backward compatibility behavior applies only when updating to v1.8.0.

In v1.8.0, the SSL verification settings were restructured. To prevent existing connections from breaking, servers that had “Allow untrusted certificates” enabled before the update are automatically migrated to a less strict configuration.

For better security, we strongly recommend reviewing each affected server and switching back to the certificate pinning approach.

If you had “Allow untrusted certificates” enabled before updating the app, the update will automatically enable both “Allow untrusted certificates” and “Don’t check SSL certificate” for backward compatibility.

As a result, all your HTTPS servers will display the “Don’t check SSL certificate” status, and a warning banner will appear:

Caution

After the app update, if “Allow untrusted certificates” was ON before the update, all HTTPS servers will show the “Don’t check SSL certificate” status. This configuration is less secure than the certificate pinning approach.

If it was OFF before the update, no changes are applied— your servers will remain in either “HTTPS Verified” or “HTTPS Untrusted Blocked” status.

How to Fix This

1. Open the server details screen for the affected server
2. Turn OFF “Don’t check SSL certificate”
3. Save the settings
4. The “Allow untrusted certificates” confirmation modal will appear
5. Verify the certificate fingerprint and tap “Confirm”

After confirming, the server will show the “HTTPS Pinned” status, which provides stronger security than “Don’t check SSL certificate”.

Pi-hole in Docker: Special Considerations

If you’re running Pi-hole in Docker, you may encounter connection issues even with “Allow untrusted certificates” enabled.

This happens because the Pi-hole Docker container’s built-in web server certificate cannot be properly validated by the app’s TLS implementation.

Solution 1: Disable Certificate Checking (Simple)

1. In server settings, enable “Don’t check SSL certificate”
2. Save and reconnect

Caution

Only use this on trusted local networks. This disables all certificate validation.

Solution 2: Use a Reverse Proxy (Recommended)

Set up a reverse proxy (nginx, Caddy, Traefik, etc.) in front of Pi-hole:

1. Configure the reverse proxy to handle TLS termination
2. Use either a free, valid certificate from Let’s Encrypt or a self-signed certificate on the reverse proxy.
3. Connect to Pi-hole through the reverse proxy URL

Benefits:

• Achieve “HTTPS Verified” or “HTTPS Pinned” status
• Proper certificate management
• Better security overall

Example with Caddy:

pihole.local {
    reverse_proxy pihole:80
    tls internal
}

---

Recommended Configuration by Use Case

Use Case	Recommended Setting	Expected Status
Valid CA certificate with full chain (Let’s Encrypt + fullchain.pem)	Allow untrusted certificates: OFF	HTTPS Verified
Let’s Encrypt with incomplete chain (cert.pem)	Fix server to use fullchain.pem — or enable Allow untrusted certificates: ON as a workaround	HTTPS Verified / HTTPS Pinned
Self-signed certificate	Allow untrusted certificates: ON, Pin the cert	HTTPS Pinned
Docker without reverse proxy	Don’t check SSL certificate: ON	Don’t check SSL
Local HTTP only	-	HTTP

---

SSL Error with a Valid Let’s Encrypt Certificate (Incomplete Chain)

If you’re using a valid Let’s Encrypt certificate but still get SSL errors in the app, the most common cause is an incomplete certificate chain.

Unlike web browsers, which can automatically fetch missing intermediate certificates, Flutter’s HTTP client requires the server to provide the complete chain. This typically happens when the server is configured with cert.pem instead of fullchain.pem.

Symptoms:

• SSL error when connecting through the app
• The connection works fine in a web browser
• The certificate appears valid when viewed in a browser

Solution 1: Fix the certificate chain (Recommended)

Pi-hole requires a single combined PEM file containing both the certificate and the private key. The key point is to use fullchain.pem (not cert.pem) when creating this file.

Pi-hole v6 (pihole.toml or environment variable):

Create the combined PEM with the full chain:

cat /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
    /etc/letsencrypt/live/yourdomain.com/privkey.pem \
    > /etc/pihole/tls.pem

Then set the path in pihole.toml:

[webserver.tls]
cert = "/etc/pihole/tls.pem"

After updating, restart Pi-hole and reconnect — the status should change to HTTPS Verified.

Solution 2: Enable “Allow untrusted certificates” (Workaround)

If you cannot fix the server configuration immediately:

1. Open server settings and expand Advanced Options
2. Enable “Allow untrusted certificates”
3. Pin the certificate fingerprint when prompted

Caution

This is a temporary workaround. Fixing the certificate chain on the server side is strongly recommended for proper security.

---

Troubleshooting

Having issues with certificate configuration? Check out the FAQ for common questions and solutions:

• Q2. SSL error with a valid Let’s Encrypt certificate
• Q3. “Connection failed” with self-signed certificate
• Q4. Certificate pin mismatch after server certificate update
• Q5. Warning banner about unverified certificates keeps appearing