SSL/TLS Setup Guide for KrakenHashes¶

This guide explains how to set up and trust the self-signed SSL certificates used by KrakenHashes on various platforms.

Overview¶

KrakenHashes uses self-signed certificates by default to secure communications between components. When you first access the web interface, your browser will warn you about the untrusted certificate. This is expected behavior for self-signed certificates.

To avoid these warnings, you need to install the KrakenHashes Certificate Authority (CA) certificate as a trusted root certificate on your system.

Required: the addresses your certificate must cover¶

Add every address your agents and browsers use in Admin → Settings → Server Certificate, then click Apply & Reissue. The change takes effect immediately:

• The certificate is reissued under the existing certificate authority, so every already-enrolled agent keeps working with the ca.crt it already has.
• The backend picks up the new certificate on the next connection. No restart is required.
• Agents that were failing reconnect on their own within 30 seconds.

Only private and VPN addresses are accepted — RFC 1918 (10.x, 172.16–31.x, 192.168.x), CGNAT (100.64–127.x), link-local, and IPv6 ULA. Public, internet-routable addresses are rejected: KrakenHashes stores cracked credentials and must never be reachable from the internet.

netbird status | grep 'NetBird IP'   # NetBird
ip -o -4 addr show wt0               # NetBird interface
ip -o -4 addr show                   # any VPN interface

If an agent is already failing, the address it is trying to reach appears automatically under Discovered addresses on that page, reported by the agent itself, so you can add it with one click.

Downloading the CA Certificate¶

The CA certificate can be downloaded from: - Via the web interface: click the download icon in the application header, or go to Settings > Security and click Download CA certificate. Both download https://your-server/ca.crt from the same origin as the web UI, so they work through a VPN or reverse proxy without any extra ports. - HTTPS endpoint: https://your-server/ca.crt (same origin as the web UI) - HTTP endpoint: http://your-server/ca.crt on port 80, or http://your-server:1337/ca.crt directly from the backend. Port 1337 is the agent bootstrap port and should only be reachable by agents (see the Security guide); users should prefer the HTTPS endpoint.

Save the file as krakenhashes-ca.crt for the following instructions.

Installation Instructions by Platform¶

Linux Systems¶

Debian/Ubuntu¶

1. Copy the CA certificate to the system certificate directory:

   sudo cp krakenhashes-ca.crt /usr/local/share/ca-certificates/
   

2. Update the certificate store:

   sudo update-ca-certificates
   

3. You should see output indicating the certificate was added:

   Updating certificates in /etc/ssl/certs...
   1 added, 0 removed; done.
   

Fedora/RHEL/CentOS/Rocky Linux¶

1. Copy the CA certificate to the trust anchors directory:

   sudo cp krakenhashes-ca.crt /etc/pki/ca-trust/source/anchors/
   

2. Update the trust store:

   sudo update-ca-trust
   

Arch Linux¶

Using trust anchor command (Recommended):

# This is the official Arch way - it handles everything automatically
sudo trust anchor --store krakenhashes-ca.crt

Note: The trust anchor --store command automatically: - Places the certificate in /etc/ca-certificates/trust-source/anchors/ - Updates the trust database with update-ca-trust - Handles p11-kit integration properly

Additional Step for Chrome/Chromium on Linux¶

Chrome and Chromium browsers maintain their own certificate store on Linux. After installing the system certificate, you also need to:

1. Install the certificate in the NSS database:

   certutil -d sql:$HOME/.pki/nssdb -A -t "CP,CP," -n "KrakenHashes Root CA" -i krakenhashes-ca.crt
   

2. Restart Chrome/Chromium for the changes to take effect.

To verify the certificate was installed:

certutil -d sql:$HOME/.pki/nssdb -L

To remove the certificate later if needed:

certutil -d sql:$HOME/.pki/nssdb -D -n "KrakenHashes Root CA"

Windows¶

Using Certificate Manager (GUI)¶

1. Press Win + R, type certmgr.msc, and press Enter
2. Navigate to "Trusted Root Certification Authorities" > "Certificates"
3. Right-click on "Certificates" and select "All Tasks" > "Import..."
4. Follow the Certificate Import Wizard:
5. Click "Next"
6. Browse and select the krakenhashes-ca.crt file
7. Click "Next"
8. Ensure "Place all certificates in the following store" is selected with "Trusted Root Certification Authorities"
9. Click "Next" and then "Finish"
10. When prompted with a security warning, click "Yes" to install the certificate

Using PowerShell (Administrator)¶

# Import the certificate to the Trusted Root store
Import-Certificate -FilePath "C:\path\to\krakenhashes-ca.crt" -CertStoreLocation Cert:\LocalMachine\Root

Using Command Prompt (Administrator)¶

certutil -addstore "Root" "C:\path\to\krakenhashes-ca.crt"

macOS¶

Using Keychain Access (GUI)¶

1. Double-click the krakenhashes-ca.crt file
2. Keychain Access will open
3. Select "System" keychain (you may need to authenticate)
4. The certificate will be added but marked as untrusted
5. Double-click on the "KrakenHashes Root CA" certificate
6. Expand the "Trust" section
7. Change "When using this certificate" to "Always Trust"
8. Close the window and authenticate to save changes

Using Command Line¶

# Add certificate to system keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain krakenhashes-ca.crt

Verification¶

After installing the certificate, you can verify it's working:

1. Browser Test: Navigate to https://your-server:31337 - you should no longer see certificate warnings
2. Command Line Test:

   curl https://your-server:31337/health
   # Should work without certificate errors
   

Certificate Details¶

The self-signed certificates generated by KrakenHashes include:

• CA Certificate: Valid for 10 years (3650 days)
• Server Certificate: Valid for 1 year (365 days)
• Key Size: 4096-bit RSA (configurable)
• Extensions:
• SubjectKeyIdentifier and AuthorityKeyIdentifier for proper chain validation
• BasicConstraints properly set (CA:TRUE for CA, CA:FALSE for server)
• Appropriate KeyUsage and ExtendedKeyUsage flags

Environment Variables¶

You can customize certificate generation with these environment variables:

• KH_ADDITIONAL_DNS_NAMES: Comma-separated additional DNS names (e.g., "krakenhashes.local,kraken.internal"). Seeds the first certificate only — see below.
• KH_ADDITIONAL_IP_ADDRESSES: Comma-separated additional IP addresses (e.g., "192.168.1.100,10.0.0.50"). Seeds the first certificate only — see below.
• KH_KEY_SIZE: RSA key size (2048 or 4096, default: 4096)
• KH_SERVER_CERT_VALIDITY: Server certificate validity in days (default: 365)
• KH_CA_CERT_VALIDITY: CA certificate validity in days (default: 3650)

Security Considerations¶

1. Self-signed certificates are suitable for:
2. Development environments
3. Internal networks
4. Testing and staging

5. Environments where you control all clients

6. For production use, consider:

7. Using certificates from a trusted CA (Let's Encrypt, etc.)
8. Implementing proper certificate rotation

9. Using the certbot mode if you have a public domain

10. Certificate Storage:

11. Private keys are stored with 0600 permissions
12. Certificates are stored in the configured certs directory
13. Default location: ~/.krakenhashes/certs/ or /etc/krakenhashes/certs/ in Docker

Regenerating Certificates¶

To add or remove addresses (the normal case)¶

Use Admin → Settings → Server Certificate, edit the address lists, and click Apply & Reissue.

This reissues only the server certificate, signed by the existing certificate authority. Nothing else has to change:

To rotate the certificate authority (rare)¶

Only necessary if the CA private key may have been exposed. Use the Rotate CA action under Advanced on the same page; it requires typing a confirmation phrase and takes a timestamped backup of the existing material first.

Afterwards every agent must re-fetch the CA. Agents do this automatically the next time a handshake fails, but any browser or operating system that installed the old CA must install the new ca.crt by hand.

Verifying what the certificate actually covers¶

openssl s_client -connect your-backend:31337 </dev/null 2>/dev/null \
  | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

The backend also logs its coverage at startup, so docker logs answers the same question without openssl.

Certificate Modes¶

KrakenHashes supports three TLS modes:

1. self-signed (default): Automatically generates and manages certificates
2. provided: Use your own certificates from any CA - Detailed Guide
3. certbot: Automated ACME certificate management (Let's Encrypt or custom CA) - Custom ACME Guide

To change modes, set the KH_TLS_MODE environment variable.

Choosing a Mode¶

• Self-Signed: Best for development, testing, and isolated environments
• Provided: Best for commercial CAs, existing certificates, or external certificate management
• Certbot: Best for automated certificate lifecycle with ACME-compatible CAs

Certbot Mode (Automated ACME)¶

This mode provides automated certificate management using the ACME protocol. It supports: - Let's Encrypt (default) - Public CA with 90-day certificates - Custom ACME servers - Internal PKI like Smallstep, HashiCorp Vault, etc.

See the Custom ACME Server Guide for using internal PKI systems.

Let's Encrypt Setup¶

This setup uses Let's Encrypt with Cloudflare DNS-01 challenge, ideal for internal applications that aren't publicly accessible.

Prerequisites¶

1. Domain Name: You need to own a domain (e.g., zerkersec.io)
2. Cloudflare Account: Your domain must be managed by Cloudflare
3. API Token: Create a Cloudflare API token with proper permissions

Step 1: Create Cloudflare API Token¶

1. Log in to your Cloudflare dashboard
2. Go to My Profile → API Tokens
3. Click Create Token
4. Use the Custom token template with these permissions:
5. Zone → DNS → Edit
6. Zone → Zone → Read (optional but recommended)
7. Under Zone Resources, select:
8. Include → Specific zone → Your domain (e.g., zerkersec.io)
9. Click Continue to summary and Create Token
10. Save the token securely - you won't be able to see it again!

Step 2: DNS Configuration¶

Create an A record for your subdomain:

1. In Cloudflare dashboard, go to your domain
2. Navigate to DNS → Records
3. Add a new A record:
4. Type: A
5. Name: kraken (or your chosen subdomain)
6. IPv4 address: Your internal IP (e.g., 10.0.0.100)
7. Proxy status: DNS only (gray cloud)
8. TTL: Auto

Note: The IP address doesn't need to be publicly accessible. Certbot only needs to verify domain ownership via DNS TXT records.

Step 3: Configure KrakenHashes¶

Edit your .env file:

# Change TLS mode to certbot
KH_TLS_MODE=certbot

# Certbot Configuration
KH_CERTBOT_DOMAIN=kraken.zerkersec.io    # Your full domain
KH_CERTBOT_EMAIL=admin@zerkersec.io      # Your email for Let's Encrypt
KH_CERTBOT_STAGING=true                  # Start with staging for testing!
KH_CERTBOT_AUTO_RENEW=true               # Enable automatic renewal

# Cloudflare Configuration
CLOUDFLARE_API_TOKEN=your-token-here     # The token from Step 1

# Update frontend URLs to use your domain
REACT_APP_API_URL=https://kraken.zerkersec.io:31337
REACT_APP_WS_URL=wss://kraken.zerkersec.io:31337

# Update CORS to allow your domain
CORS_ALLOWED_ORIGIN=https://kraken.zerkersec.io

Step 4: Initial Setup with Staging¶

Important: Always test with Let's Encrypt staging environment first to avoid rate limits!

1. Stop existing containers:

   docker-compose down
   

2. Start with certbot mode:

   docker-compose up -d
   

3. Monitor the logs:

   docker-compose logs -f krakenhashes
   

4. Look for messages indicating successful certificate generation:

   Obtaining certificates for domain: kraken.zerkersec.io
   Successfully obtained certificates
   

Step 5: Verify Staging Certificates¶

1. Check certificate files:

   ls -la kh-backend/config/certs/live/kraken.zerkersec.io/
   

2. You should see:

3. fullchain.pem - Certificate chain
4. privkey.pem - Private key
5. chain.pem - Intermediate certificates

6. cert.pem - Domain certificate

7. Test the application (you'll get a browser warning for staging certificates)

Step 6: Switch to Production¶

Once staging certificates work:

1. Update .env:

   KH_CERTBOT_STAGING=false
   

2. Remove staging certificates:

   rm -rf kh-backend/config/certs/live/*
   rm -rf kh-backend/config/certs/archive/*
   rm -rf kh-backend/config/certs/renewal/*
   

3. Restart to get production certificates:

   docker-compose down
   docker-compose up -d
   

Certificate Renewal¶

Certificates are automatically renewed:

• Renewal checks run twice daily (3 AM and 3 PM)
• Certificates renew when less than 30 days remain
• Services reload automatically after renewal

Manual Renewal:

docker exec <krakenhashes-container> /usr/local/bin/certbot-renew.sh

Monitor Renewal:

docker exec <krakenhashes-container> tail -f /var/log/krakenhashes/certbot-renew.log

Certbot Troubleshooting¶

Common Issues¶

1. "CLOUDFLARE_API_TOKEN environment variable is required"
2. Ensure the token is set in your .env file

3. Token must have DNS:Edit permissions

4. "Failed to obtain certificates"

5. Check Cloudflare API token permissions
6. Verify domain ownership

7. Check certbot logs: docker exec <krakenhashes-container> cat /etc/krakenhashes/certs/logs/letsencrypt.log

8. Browser still shows certificate warnings

9. Ensure you switched from staging to production
10. Clear browser cache

11. Verify certificates: docker exec <krakenhashes-container> openssl x509 -in /etc/krakenhashes/certs/live/kraken.zerkersec.io/cert.pem -text -noout

12. Rate Limits

13. Let's Encrypt has rate limits (50 certificates per domain per week)
14. Always test with staging first
15. See: https://letsencrypt.org/docs/rate-limits/

Certificate Information¶

View certificate details:

# Inside container
docker exec <krakenhashes-container> certbot certificates --config-dir /etc/krakenhashes/certs

# Certificate expiry
docker exec <krakenhashes-container> openssl x509 -enddate -noout -in /etc/krakenhashes/certs/live/kraken.zerkersec.io/cert.pem

Additional Domains¶

To add more domains/subdomains:

1. Add them to KH_ADDITIONAL_DNS_NAMES in .env:

   KH_ADDITIONAL_DNS_NAMES=kraken.zerkersec.io,api.zerkersec.io,*.kraken.zerkersec.io
   

2. Ensure all domains are in Cloudflare and accessible by your API token

3. Restart the container to obtain certificates for all domains

Migration from Self-Signed¶

If migrating from self-signed certificates:

1. Back up existing certificates (optional)
2. Update .env as shown above
3. Restart containers
4. Update any clients/browsers that have the old CA certificate cached

Troubleshooting¶

Common Issues and Solutions¶

An agent reports the certificate does not cover its address¶

The agent prints something like:

Cannot verify the KrakenHashes server certificate for 192.168.1.50:31337.

The server's certificate does not list this address.
  You are connecting to : 192.168.1.50:31337
  The certificate covers: IP:127.0.0.1, DNS:localhost

This is a server-side setting. Renewing this agent's certificates will not fix it.

This is a server-side problem. Deleting the agent's certificates, re-running the claim, or reinstalling the agent will not help — the address is missing from the server's certificate.

Fix it in Admin → Settings → Server Certificate: the address will already be listed under Discovered addresses (the agent reports it over the plain-HTTP bootstrap port, which still works when TLS does not). Add it and click Apply & Reissue. The agent reconnects on its own within 30 seconds; no agent restart is needed.

To confirm what the server currently presents:

openssl s_client -connect your-backend:31337 </dev/null 2>/dev/null \
  | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

Browser Still Shows Certificate Warnings¶

1. Certificate not properly installed:
2. Verify the certificate is in the correct store (Trusted Root, not Personal or Intermediate)
3. Check that you installed the CA certificate, not the server certificate

4. Some browsers cache certificate decisions - try clearing browser data or using incognito mode

5. Browser-specific issues:

6. Chrome/Edge: May require restart after certificate installation
7. Firefox: Has its own certificate store - you may need to import via Firefox settings

8. Safari: Requires explicit trust settings in Keychain Access

9. Certificate regenerated:

10. If the backend regenerated certificates, you need to reinstall the new CA certificate
11. Remove the old certificate first to avoid conflicts

ERR_SSL_KEY_USAGE_INCOMPATIBLE (Chrome/Edge)¶

This error indicates the certificate doesn't have the correct key usage flags. The updated certificate generation should prevent this, but if you encounter it:

1. Ensure you're running the latest version with the certificate improvements
2. Delete existing certificates and let them regenerate
3. As a temporary workaround on Windows:

   # Create registry key to disable the check (use with caution)
   New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Microsoft\Edge" -Name "RSAKeyUsageForLocalAnchorsEnabled" -Value 0 -PropertyType DWORD
   # For Chrome:
   New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Google\Chrome" -Name "RSAKeyUsageForLocalAnchorsEnabled" -Value 0 -PropertyType DWORD
   

Certificate Not Trusted on Linux¶

1. Check certificate format:

   # Verify it's a valid PEM certificate
   openssl x509 -in krakenhashes-ca.crt -text -noout
   

2. Verify installation:

   # Check if certificate is in the trust store
   trust list | grep -i krakenhashes
   
   # For Debian/Ubuntu, check the symlink was created
   ls -la /etc/ssl/certs/ | grep krakenhashes
   

3. SELinux issues (RHEL/Fedora):

   # Check for SELinux denials
   sudo ausearch -m avc -ts recent
   
   # If needed, restore context
   sudo restorecon -v /etc/pki/ca-trust/source/anchors/krakenhashes-ca.crt
   

Certificate Chain Issues¶

1. Verify the full chain is being sent:

   # Check what certificates the server is presenting
   openssl s_client -connect your-server:31337 -showcerts
   

2. Validate certificate chain:

   # Download server certificate
   echo | openssl s_client -connect your-server:31337 -servername your-server 2>/dev/null | \
     openssl x509 > server.crt
   
   # Verify against CA
   openssl verify -CAfile krakenhashes-ca.crt server.crt
   

Connection Refused or Timeout¶

1. Check the service is running:

   # Check if ports are listening
   netstat -tlnp | grep -E "1337|31337"
   # or
   ss -tlnp | grep -E "1337|31337"
   

2. Firewall rules:

   # Check firewall status
   sudo iptables -L -n | grep -E "1337|31337"
   # or for firewalld
   sudo firewall-cmd --list-all
   

3. Docker networking (if using Docker):

4. Ensure ports are properly mapped in docker-compose.yml
5. Check Docker network connectivity

Diagnostic Commands¶

View Certificate Details¶

# View CA certificate details
openssl x509 -in krakenhashes-ca.crt -text -noout

# Check certificate dates
openssl x509 -in krakenhashes-ca.crt -noout -dates

# Check certificate subject and issuer
openssl x509 -in krakenhashes-ca.crt -noout -subject -issuer

Test TLS Connection¶

# Test with curl (verbose)
curl -v https://your-server:31337/health

# Test with openssl
openssl s_client -connect your-server:31337 -CAfile krakenhashes-ca.crt

# Test cipher suites
nmap --script ssl-enum-ciphers -p 31337 your-server

Browser Certificate Debugging¶

1. Chrome: Navigate to chrome://settings/certificates to manage certificates
2. Firefox: Navigate to about:preferences#privacy > View Certificates
3. Edge: Navigate to edge://settings/privacy > Manage certificates

Removing Old Certificates¶

If you need to remove old certificates before installing new ones:

Arch Linux:

# Find and remove the certificate
sudo rm -f /etc/ca-certificates/trust-source/anchors/krakenhashes-ca.crt
sudo update-ca-trust

# Or use trust anchor to remove by name
sudo trust anchor --remove "KrakenHashes Root CA"

# Remove from Chrome/Chromium
certutil -d sql:$HOME/.pki/nssdb -D -n "KrakenHashes Root CA"

Debian/Ubuntu:

sudo rm /usr/local/share/ca-certificates/krakenhashes-ca.crt
sudo update-ca-certificates --fresh

Fedora/RHEL:

sudo rm /etc/pki/ca-trust/source/anchors/krakenhashes-ca.crt
sudo update-ca-trust

Getting Help¶

If you're still experiencing issues:

1. Check the backend logs for certificate generation errors:

   grep -i "certificate\|tls\|ssl" /path/to/backend.log
   

2. Ensure your environment variables are set correctly

3. Try regenerating certificates with a clean state
4. Report issues at: https://github.com/ZerkerEOD/krakenhashes/issues