# Install Psono Pwned Passwords

Psono Pwned Passwords lets clients check passwords against a locally hosted copy of the Have I Been Pwned password database. Password checks use your own API instead of the public Pwned Passwords service. The client hashes passwords locally and sends only the first five characters of the SHA-1 hash to the API.

# Preamble

This guide assumes that your Psono server and webclient are running and that you use current server and client versions supporting PWNED_PASSWORDS_API_URL. It uses:

  • https://psono.example.com for Psono.
  • https://pwned.example.com for the Pwned Passwords API.
  • Port 10600 for the API container, accessible only from the local Nginx reverse proxy.
  • /opt/docker/psono-pwned-passwords for the database on the Docker host.

Run the installation commands as root on a host with Docker, Nginx, and curl. The examples assume that Nginx and the container run on the same host. Create a DNS record for pwned.example.com and obtain a TLS certificate covering that hostname. The database is currently approximately 50 GB. SSD storage is recommended.

# Server configuration

  1. Configure the Pwned Passwords URL.

    Set the following in the Psono server's settings.yaml:

    PWNED_PASSWORDS_API_URL: 'https://pwned.example.com'
    

    Alternatively, set the server environment variable PSONO_PWNED_PASSWORDS_API_URL. This is the base URL of the service; do not append /range or a hash prefix. Restart your Psono server or Combo container after changing this setting.

  2. Configure Content-Security-Policy.

    Add https://pwned.example.com to the connect-src directive of the existing Content-Security-Policy header on your regular Psono reverse proxy. For the standard Nginx configuration, the header would look like this:

    add_header Content-Security-Policy "default-src 'none';  manifest-src 'self'; connect-src 'self' https://pwned.example.com https://static.psono.com https://api.pwnedpasswords.com https://storage.googleapis.com https://*.digitaloceanspaces.com https://*.blob.core.windows.net https://*.s3.amazonaws.com https://*.wasabisys.com; font-src 'self'; img-src 'self' https://favicon.psono.com data:; script-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; frame-ancestors 'none'; child-src 'self'";
    

    Modify your existing header rather than adding a second CSP header. Preserve other origins required by your installation, such as a fileserver or custom favicon service. If your deployment uses NGINX_HEADER_CONTENT_SECURITY_POLICY, add the same origin to that setting instead.

    Test and restart the regular reverse proxy after changing its configuration:

    nginx -t
    service nginx restart
    

# Installation

  1. Create the storage directory and download the database.

    For the initial installation:

    mkdir -p /opt/docker/psono-pwned-passwords
    
    curl --fail --location \
      --output /opt/docker/psono-pwned-passwords/passwords.sqlite \
      https://storage.googleapis.com/static.psono.com/psono/psono-pwned-passwords/passwords.sqlite
    

    Wait for the download to finish before starting the container. For an existing installation, follow Update the database instead.

  2. Run the API container.

    docker pull psono/psono-pwned-passwords:latest
    
    docker run --name psono-pwned-passwords \
      -v /opt/docker/psono-pwned-passwords:/data:ro \
      -d --restart=unless-stopped \
      -p 127.0.0.1:10600:80 \
      psono/psono-pwned-passwords:latest
    

    Check the service:

    curl --fail http://127.0.0.1:10600/healthcheck/
    docker logs psono-pwned-passwords
    

    The healthcheck should return JSON containing "status":"ok".

  3. Setup the reverse proxy.

    Follow the "Installation Pwned Passwords Reverse Proxy" section below to expose the API through HTTPS.

# Installation Pwned Passwords Reverse Proxy

  1. Install Nginx.

    apt-get install nginx
    
  2. Create the Nginx configuration.

    Create /etc/nginx/sites-available/pwned.example.com.conf with the following content:

    server {
        listen 80;
        server_name pwned.example.com;
        return 301 https://$host$request_uri;
    }
    
    server {
        listen 443 ssl http2;
        server_name pwned.example.com;
    
        ssl_protocols TLSv1.2 TLSv1.3;
    
        # Comment this in if you know what you are doing
        # add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
    
        add_header Referrer-Policy same-origin;
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";
    
        ssl_certificate /etc/ssl/fullchain.pem;
        ssl_certificate_key /etc/ssl/privkey.pem;
    
        # Requests contain password-hash prefixes; avoid recording them in access logs.
        access_log off;
    
        gzip on;
        gzip_vary on;
        gzip_types text/plain;
    
        location / {
            proxy_set_header        Host $host;
            proxy_set_header        X-Real-IP $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header        X-Forwarded-Proto $scheme;
    
            proxy_pass          http://127.0.0.1:10600;
            proxy_read_timeout  90;
            proxy_cache off;
        }
    }
    

    Use the certificate and private-key paths for pwned.example.com.

  3. Enable the Nginx configuration.

    ln -s /etc/nginx/sites-available/pwned.example.com.conf /etc/nginx/sites-enabled/
    
  4. Test the Nginx configuration.

    nginx -t
    
  5. Restart Nginx.

    service nginx restart
    

# Validation

Check the public healthcheck and range endpoint:

curl --fail https://pwned.example.com/healthcheck/
curl --fail https://pwned.example.com/range/5baa6

The range endpoint returns lines of HASH_SUFFIX:COUNT as plain text.

Sign out, reload the webclient, and sign in again so the client receives the configured URL. Generate a security report with breach detection enabled. In the browser's developer tools, confirm that range requests go to https://pwned.example.com/range/....

# Note: Installation behind Firewall

If you have put your installation behind a firewall, whitelist the following traffic:

  • Incoming TCP 443 from users' browsers to pwned.example.com for password checks.
  • Incoming TCP 80 to the API reverse proxy for the redirect to HTTPS.

Port 10600 is bound to the host's loopback interface in this guide and does not need to be exposed externally.

For database replacement and container updates, see Update Psono Pwned Passwords.