Skip to content

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.

Downloading the CA Certificate

The CA certificate can be downloaded from: - HTTP endpoint: http://your-server:1337/ca.crt - Via the web interface: When you see the certificate warning, there's usually an option to download the CA certificate

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")
  • KH_ADDITIONAL_IP_ADDRESSES: Comma-separated additional IP addresses (e.g., "192.168.1.100,10.0.0.50")
  • KH_CERT_KEY_SIZE: RSA key size (2048 or 4096, default: 4096)
  • KH_CERT_VALIDITY_DAYS: Server certificate validity in days (default: 365)
  • KH_CA_VALIDITY_DAYS: 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

If you need to regenerate certificates (e.g., to add new SANs):

  1. Stop the KrakenHashes backend
  2. Delete the existing certificates: 
    rm -rf ~/.krakenhashes/certs/*
# Or your configured certs directory
  3. Start the backend - new certificates will be generated automatically
  4. Reinstall the new CA certificate on client systems

Certificate Modes

KrakenHashes supports three TLS modes:

  1. self-signed (default): Automatically generates and manages certificates
  2. provided: Use your own certificates (set paths via environment variables)
  3. certbot: Integration with Let's Encrypt for public domains

To change modes, set the KH_TLS_MODE environment variable.

Certbot Mode (Let's Encrypt)

This mode allows you to use Let's Encrypt certificates via Certbot with Cloudflare DNS-01 challenge. This is 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 /usr/local/bin/certbot-renew.sh

Monitor Renewal: 

docker exec krakenhashes 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 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 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 certbot certificates --config-dir /etc/krakenhashes/certs

# Certificate expiry
docker exec krakenhashes 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

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