# 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.comfor Psono.https://pwned.example.comfor the Pwned Passwords API.- Port
10600for the API container, accessible only from the local Nginx reverse proxy. /opt/docker/psono-pwned-passwordsfor 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
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/rangeor a hash prefix. Restart your Psono server or Combo container after changing this setting.Configure
Content-Security-Policy.Add
https://pwned.example.comto theconnect-srcdirective of the existingContent-Security-Policyheader 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
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.sqliteWait for the download to finish before starting the container. For an existing installation, follow Update the database instead.
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:latestCheck the service:
curl --fail http://127.0.0.1:10600/healthcheck/ docker logs psono-pwned-passwordsThe healthcheck should return JSON containing
"status":"ok".Setup the reverse proxy.
Follow the "Installation Pwned Passwords Reverse Proxy" section below to expose the API through HTTPS.
# Installation Pwned Passwords Reverse Proxy
Install Nginx.
apt-get install nginxCreate the Nginx configuration.
Create
/etc/nginx/sites-available/pwned.example.com.confwith 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.Enable the Nginx configuration.
ln -s /etc/nginx/sites-available/pwned.example.com.conf /etc/nginx/sites-enabled/Test the Nginx configuration.
nginx -tRestart 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.comfor 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.