rt/wrolpi-help
1
0
Fork 0
mirror of https://github.com/wrolpi/wrolpi-help.git synced 2026-10-26 19:01:40 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
wrolpi-help/docs/system/certificates.md

5.9 KiB
Raw Permalink Blame History

HTTPS Certificates

WROLPi uses HTTPS to secure connections between your devices and your WROLPi. Because WROLPi is designed for offline use, it cannot use a public certificate authority like Let's Encrypt. Instead, WROLPi generates its own Root CA certificate which you install once on each device that connects to it.

Why HTTPS?

HTTPS encrypts traffic between your browser and WROLPi. Without it, anyone on your local network could intercept passwords, files, or other data in transit. Many modern browser features also require HTTPS to function. The Kiwix browser requires HTTPS for some media to load.

How It Works

WROLPi uses a two-level certificate system:

  1. Root CA — A long-lived certificate authority stored on the WROLPi media drive. This is generated once and never changes. You install this on your devices so they trust your WROLPi.
  2. Leaf certificate — A short-lived server certificate signed by the Root CA. This is regenerated automatically when your WROLPi's hostname or IP address changes. Because your devices already trust the Root CA, they will automatically trust any new leaf certificate.

First Startup (Temporary Certificate)

On a fresh install, no media drive is mounted yet and no Root CA exists. WROLPi generates a temporary self-signed certificate so that Caddy can serve HTTPS immediately. This allows the browser to reach the Controller for onboarding, though you will see a browser certificate warning that must be accepted.

Once onboarding completes and the repair script runs, proper Root CA and leaf certificates are generated and the temporary certificate is replaced. After installing the Root CA on your devices, the browser warning will not appear again.

Downloading the Root CA Certificate

You can download the Root CA certificate from:

  • The Controller at http://<your-wrolpi-address>/ (or http://<your-wrolpi-address>:8080/ for Docker)
  • The Settings page in the WROLPi interface under Configs
  • Directly at http://<your-wrolpi-address>/ca.crt

Installing the Certificate

After downloading the wrolpi-ca.crt file, follow the instructions for your device:

iOS / iPadOS

  1. Tap the download link, then tap Allow when prompted.
  2. Open Settings > General > VPN & Device Management.
  3. Tap WROLPi Root CA > Install > enter your passcode.
  4. Go to Settings > General > About > Certificate Trust Settings.
  5. Enable full trust for WROLPi Root CA.

Android

  1. Tap the download link.
  2. Open Settings > Security & privacy > More security settings > Encryption & credentials > Install a certificate > CA certificate.
  3. Select the downloaded wrolpi-ca.crt file and confirm.

Menu paths vary by manufacturer. If you can't find it, search for "certificate" in Settings.

macOS

  1. Double-click the downloaded wrolpi-ca.crt file to open Keychain Access.
  2. Add it to the System or login keychain.
  3. Find WROLPi Root CA in the keychain, double-click it.
  4. Expand Trust, set When using this certificate to Always Trust.
  5. Close and enter your password to confirm.

Windows

  1. Double-click the downloaded wrolpi-ca.crt file.
  2. Click Install Certificate > Local Machine > Next.
  3. Select Place all certificates in the following store > Browse > Trusted Root Certification Authorities.
  4. Click Finish.

Linux (Debian / Ubuntu)

  1. Copy the certificate: sudo cp wrolpi-ca.crt /usr/local/share/ca-certificates/
  2. Update the trust store: sudo update-ca-certificates
  3. Restart your browser. Chromium-based browsers (Chrome, Edge) will use the system store automatically.

Firefox on Linux does not use the system trust store by default — see the Firefox section below.

Firefox (all platforms)

Since Firefox 120, Firefox automatically trusts root certificates installed in the OS certificate store on Windows, macOS, and Android. If you've already installed the certificate above, Firefox should work with no extra steps on those platforms.

On Linux (or if auto-trust is disabled), import manually:

  1. Open Firefox, go to Settings > Privacy & Security.
  2. Scroll to Certificates > click View Certificates.
  3. In the Authorities tab, click Import.
  4. Select the downloaded wrolpi-ca.crt file.
  5. Check Trust this CA to identify websites > OK.

Alternatively, enable auto-trust: go to about:config and set security.enterprise_roots.enabled to true.

Security: Man-in-the-Middle (MITM) Mitigation

When you install a Root CA on your device, you are trusting it to vouch for the identity of servers. A compromised or malicious CA could sign certificates for any domain, allowing an attacker to impersonate websites and intercept your traffic. This is a man-in-the-middle (MITM) attack.

WROLPi mitigates this risk with Name Constraints. The Root CA certificate includes a critical nameConstraints extension that restricts which domains and IP addresses it is allowed to sign certificates for. Specifically, the WROLPi Root CA can only sign certificates for:

  • localhost and .local hostnames
  • Private/local IP ranges:
    • 127.0.0.0/8 (loopback)
    • 10.0.0.0/8 (private)
    • 172.16.0.0/12 (private)
    • 192.168.0.0/16 (private)
    • ::1 (IPv6 loopback)
    • fc00::/7 and fe80::/10 (IPv6 private and link-local)

This means that even if someone obtained the WROLPi Root CA private key, they could not use it to create fake certificates for public websites like google.com or your-bank.com. Your browser would reject any such certificate because it violates the name constraints. The WROLPi Root CA is only valid for local network addresses — exactly where your WROLPi lives.

This is a defense-in-depth measure. The Root CA private key is stored on your WROLPi's media drive and never leaves the device.