Local SSL Certificates & Networking

Automatic SSL certificate generation with local Certificate Authority, trusted certificates, and automated hosts file management

Overview

Envloom provides automatic HTTPS for local development sites using a self-signed Certificate Authority (CA) and per-site SSL certificates. All certificates are trusted by Windows, eliminating browser warnings.

Local CA

One-time CA generation, trusted system-wide

Per-Site Certs

Automatic certificate generation for each domain

Certificate Architecture

Certificate Hierarchy

┌─────────────────────────────────────┐
│  Envloom Local CA (Root)           │
│  sites/ca/ca.crt                    │
│  Trusted in Windows Cert Store      │
└──────────────┬──────────────────────┘
               │
               ├─► myapp.test.crt (signed by CA)
               ├─► another-site.test.crt (signed by CA)
               └─► example.test.crt (signed by CA)

Envloom uses a persistent local CA. Once trusted, all site certificates are automatically trusted without additional prompts.

Local Certificate Authority

CA Generation

The CA is created automatically the first time you enable SSL for any site:

1. Check for Existing CA

   Envloom looks for sites/ca/ca.crt and sites/ca/ca.key

2. Generate CA (if missing)

   Creates new CA certificate:

   CA generation (src-tauri/src/lib.rs:2622-2638)

   let mut ca_params = CertificateParams::new(vec![]);
   ca_params.distinguished_name = DistinguishedName {
       CommonName: "Envloom Local CA",
       OrganizationName: "Envloom"
   };
   ca_params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
   
   let ca_key = KeyPair::generate();
   let ca_cert = ca_params.self_signed(&ca_key);
   
   // Save to disk
   fs::write("sites/ca/ca.crt", ca_cert.pem());
   fs::write("sites/ca/ca.key", ca_key.serialize_pem());
   
3. Trust CA in Windows

   Automatically installs CA into Windows Trusted Root Certification Authorities:

   certutil -user -addstore Root sites/ca/ca.crt
   

CA Certificate Details

Subject:

• Common Name (CN): Envloom Local CA
• Organization (O): Envloom

Properties:

• Type: Self-signed root CA
• Key: RSA (generated by rcgen crate)
• Validity: Long-lived (typically 10+ years)
• Usage: Certificate signing only

The CA private key (sites/ca/ca.key) is not password-protected. Keep it secure. Do not share it or commit to version control.

Site Certificate Generation

Automatic Creation

When you enable SSL for a site (or create a new site with SSL enabled):

1. Load CA

   Read CA certificate and private key from sites/ca/

2. Create Site Certificate

   Generate new certificate for the domain:

   Site cert generation (src-tauri/src/lib.rs:2644-2674)

   let mut cert_params = CertificateParams::new(vec![
       "myapp.test",
       "www.myapp.test",
       "*.test"  // wildcard for TLD
   ]);
   cert_params.distinguished_name = DistinguishedName {
       CommonName: "myapp.test"
   };
   
   let cert_key = KeyPair::generate();
   let cert = cert_params.signed_by(&cert_key, &ca_cert, &ca_key);
   
   // Save certificate and private key
   fs::write("sites/certs/myapp.test.crt", cert.pem());
   fs::write("sites/certs/myapp.test.key", cert_key.serialize_pem());
   
3. Update Nginx Config

   Write SSL directives to Nginx site config:

   server {
       listen 443 ssl;
       server_name myapp.test;
       ssl_certificate sites/certs/myapp.test.crt;
       ssl_certificate_key sites/certs/myapp.test.key;
       # ...
   }
   
4. Reload Nginx

   Apply configuration changes:

   nginx -s reload
   

Subject Alternative Names (SANs)

Each site certificate includes multiple SANs:

SAN 1: myapp.test
SAN 2: www.myapp.test
SAN 3: *.test (wildcard for all .test domains)

The wildcard SAN (*.test) allows the certificate to be valid for any subdomain of the TLD, not just the specific domain.

SSL Certificate Trust

Windows Trust Store

Envloom uses Windows certutil to install the CA certificate:

Trust certificate (src-tauri/src/lib.rs:2677-2693)

certutil -user -addstore Root "sites/ca/ca.crt"

What this does:

• Adds CA to Current User → Trusted Root Certification Authorities
• Does not require administrator elevation
• Applies to all browsers using Windows certificate store (Edge, Chrome)

Firefox uses its own certificate store and may show warnings. Import sites/ca/ca.crt manually in Firefox settings.

Browser Trust Verification

After enabling SSL:

1. Open Site in Browser

   Navigate to https://myapp.test

2. Check Certificate

   Click the padlock icon in the address bar:

   • Issuer: Envloom Local CA
   • Subject: myapp.test
   • Valid: ✓ (green padlock, no warnings)
3. Verify Chain

   View certificate details:

   Certificate Hierarchy:
   └─ Envloom Local CA (Trusted Root)
      └─ myapp.test
   

Manual Trust (if needed)

If the CA is not automatically trusted:

Windows (Manual)

1. Double-click sites/ca/ca.crt
2. Click Install Certificate…
3. Choose Current User
4. Select Place all certificates in the following store
5. Browse → Trusted Root Certification Authorities
6. Click OK → Finish

Firefox

1. Open Firefox → Settings
2. Search for “certificates”
3. Click View Certificates…
4. Go to Authorities tab
5. Click Import…
6. Select sites/ca/ca.crt
7. Check Trust this CA to identify websites
8. Click OK

SSL Management Actions

Enable SSL for Existing Site

1. Open Site Detail

   Click on a site in the Sites page

2. Toggle SSL

   Enable the SSL toggle switch

3. Automatic Actions

   Envloom:

   1. Generates site certificate (if not exists)
   2. Regenerates Nginx config with SSL directives
   3. Reloads Nginx
4. Verify

   Visit https://{domain} to confirm HTTPS is working

Regenerate Certificate

If a certificate expires or becomes corrupt:

1. Site Detail Page

   Navigate to the site in Sites

2. Regenerate SSL

   Click Regenerate SSL button

3. Certificate Replaced

   Envloom:

   1. Deletes old sites/certs/{domain}.crt and .key
   2. Generates new certificate signed by CA
   3. Reloads Nginx

Regeneration does not recreate the CA. The same CA is reused, so browsers continue trusting new certificates.

Bulk SSL Actions (Tray Menu)

From the system tray, under Nginx submenu:

• SSL all on: Enable SSL for all sites
• SSL all off: Disable SSL for all sites

Bulk actions apply to all registered sites immediately. Use with caution.

Hosts File Management

Automatic Hosts Entries

Envloom manages C:\Windows\System32\drivers\etc\hosts to map domains to 127.0.0.1.

Envloom Hosts Block

Envloom creates a managed block in the hosts file:

Example hosts file

# Envloom generated Hosts - DO NOT REMOVE THIS MARK
127.0.0.1 myapp.test
127.0.0.1 another-site.test
127.0.0.1 example.test
# /Envloom

# Herd generated Hosts - DO NOT REMOVE THIS MARK
127.0.0.1 herd-site.test
# /Herd

Envloom respects the Herd block and will not modify entries inside it. Both tools can coexist peacefully.

Reconciliation Logic

1. Find or Create Block

   Locate # Envloom generated Hosts marker, or create it if missing

2. Sync Active Sites

   Add missing domains for active sites, remove entries for deleted sites

3. Move Orphaned Entries

   If an Envloom domain appears outside the block, move it inside:

   Before reconciliation

   127.0.0.1 myapp.test
   # Envloom generated Hosts - DO NOT REMOVE THIS MARK
   127.0.0.1 another-site.test
   # /Envloom
   
   # After reconciliation
   # Envloom generated Hosts - DO NOT REMOVE THIS MARK
   127.0.0.1 myapp.test
   127.0.0.1 another-site.test
   # /Envloom
   

UAC Elevation for Hosts

Modifying the hosts file requires admin rights:

1. First Attempt (Direct Write)

   Envloom tries to write directly to the hosts file

2. If Denied (Elevation)

   Generates elevated script:

   sites/hosts-update-elevated.cmd

   @echo off
   powershell -NoProfile -ExecutionPolicy Bypass -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c','%~dp0hosts-update.cmd' -Verb RunAs -Wait"
   
3. UAC Prompt

   Windows shows UAC dialog asking for admin approval

4. Apply Changes

   Once approved, the script writes to the hosts file

If you deny the UAC prompt, hosts entries will not be updated. Sites will not be accessible via domain name (use 127.0.0.1 directly).

Manual Hosts Editing

If UAC elevation fails, manually add entries:

1. Open Notepad as Administrator
2. Open C:\Windows\System32\drivers\etc\hosts
3. Add lines:
   127.0.0.1 myapp.test
   127.0.0.1 another-site.test
   
4. Save and close

Envloom will detect manual entries outside the block and move them inside on next reconciliation.

Nginx SSL Configuration

HTTP to HTTPS Redirect

When SSL is enabled, Envloom creates two server blocks:

HTTP redirect + HTTPS server

# HTTP server (port 80) - redirect to HTTPS
server {
    listen 80;
    server_name myapp.test;
    access_log logs/nginx/sites/myapp.test.access.log;
    error_log logs/nginx/sites/myapp.test.error.log;
    return 301 https://$host$request_uri;
}

# HTTPS server (port 443)
server {
    listen 443 ssl;
    server_name myapp.test;
    access_log logs/nginx/sites/myapp.test.access.log;
    error_log logs/nginx/sites/myapp.test.error.log;
    
    ssl_certificate     sites/certs/myapp.test.crt;
    ssl_certificate_key sites/certs/myapp.test.key;
    
    root C:/path/to/myapp/public;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass 127.0.0.1:9083;
    }
}

Both HTTP and HTTPS share the same access and error logs.

Disabling SSL

When you disable SSL for a site:

1. Nginx config regenerated with only the HTTP server block (no redirect, no SSL directives)
2. Certificate files remain in sites/certs/ (not deleted)
3. Nginx reloaded to apply changes

Disabling SSL does not delete certificate files. They are reused if you re-enable SSL.

Security Considerations

CA Private Key Protection

Critical: The CA private key (sites/ca/ca.key) can sign certificates for any domain.

Best practices:

• Do not share ca.key with anyone
• Do not commit to version control
• Keep it local to your development machine
• Consider adding sites/ca/ca.key to .gitignore

Certificate Validity

Self-signed certificates do not expire automatically like Let’s Encrypt:

• Validity period: Controlled by rcgen library (typically 1-10 years)
• No auto-renewal: Manually regenerate if needed
• Browser warnings: Will appear if certificate becomes invalid or corrupted

Network Exposure

All Envloom services bind to 127.0.0.1 (localhost only). They are not accessible from other machines on your network.

If you need to expose sites to other devices (e.g., mobile testing):

1. Modify Nginx config to listen on 0.0.0.0
2. Configure Windows Firewall to allow inbound on port 80/443
3. Use your local IP address (e.g., https://192.168.1.100)
4. Import CA certificate on the remote device

CLI Commands

SSL management from CLI

# Enable SSL for current site
cd /path/to/project
loom ssl on

# Disable SSL for current site
loom ssl off

# Regenerate certificate (UI only)
# Use desktop app to regenerate

Troubleshooting

Browser Shows “Not Secure”

1. CA not trusted: Verify CA is in Windows certificate store
   • Open certmgr.msc (Certificate Manager)
   • Navigate to Trusted Root Certification Authorities → Certificates
   • Look for “Envloom Local CA”
2. Firefox: Import CA manually (see Manual Trust)
3. Certificate expired: Regenerate certificate from site detail page
4. Wrong certificate: Ensure Nginx is using correct .crt and .key files

”ERR_CERT_COMMON_NAME_INVALID”

1. Domain mismatch: Verify site domain matches certificate CN/SAN
2. Hosts file: Ensure domain resolves to 127.0.0.1
3. Nginx config: Check server_name directive matches domain
4. Regenerate: Create new certificate for the correct domain

Hosts File Not Updating

1. UAC denied: Accept elevation prompt when it appears
2. File locked: Close editors that have hosts file open
3. Permissions: Ensure you have admin rights
4. Manual edit: Add entries manually as administrator
5. DNS cache: Flush DNS cache: ipconfig /flushdns

Certificate Generation Fails

1. CA missing: Check sites/ca/ca.crt and ca.key exist
2. Disk full: Ensure space in sites/certs/ directory
3. Permissions: Verify write access to sites/ directory
4. Recreate CA: Delete sites/ca/ and enable SSL to regenerate

Nginx SSL Test Fails

1. Config syntax: Run nginx -t manually
   cd bin/nginx/current
   nginx.exe -t
   
2. Certificate paths: Verify paths in sites/{domain}.conf are correct
3. Missing files: Ensure .crt and .key exist in sites/certs/
4. Port conflict: Check if port 443 is already in use:
   netstat -ano | findstr :443
   

Related Documentation

Site Management

Create and link sites with SSL

Services

Manage Nginx service lifecycle