HUB
Sign inSign up

viyh/whisper

By viyh

•Updated about 16 hours ago

Whisper provides a simple way to share secret information with someone else.

Image
Security
0

100K+

viyh/whisper repository overview

⁠Whisper⁠

Secure secret sharing via one-time or short-lived links.

Share passwords, credentials, keys, or other sensitive data without using insecure channels like email or chat. Secrets are encrypted client-side before transmission -- the server never sees plaintext.

⁠How It Works

  1. Enter secret text or select a file, along with a password.
  2. Choose an expiration: one-time use, 1 hour, 1 day, or 1 week.
  3. Click Create Secret to get a shareable link.
  4. Send the link and password separately (e.g., link via email, password via text).
  5. The recipient opens the link, enters the password, and retrieves the secret.

⁠Security Model

Whisper uses a layered security approach:

  • Client-side encryption: Secrets are encrypted with AES-256-GCM (Web Crypto API) before leaving the browser. The server never has access to plaintext data or passwords.
  • The link and the password are both needed: Each link ends in a random token after the #, which browsers never send to servers. The browser derives the encryption key from the password with Argon2id (WASM), salted with the token, and the server stores each secret under a hash of the token. The server, its storage and its logs can't decrypt a secret or tell which link it belongs to, and a copy of the storage is useless without the links, even with secret_key.
  • One-time secrets: Deleted atomically after retrieval -- concurrent requests cannot both succeed. Unread one-time secrets are deleted after 30 days.
  • Rate limiting: per IP, 10 attempts a minute to open secrets and 30 new secrets a minute (create_rate_limit), plus a per-secret lock after 10 wrong passwords (max_failed_attempts). Behind a load balancer, set trusted_proxy_count (see Running Behind a Proxy⁠).
  • Strict CSP: No inline scripts or styles, and nothing is loaded from other sites.

See Security Details⁠ for the full cryptographic design, and SECURITY.md⁠ for what it can't protect against.

⁠Quick Start

# Generate a config file with a random secret key
export SECRET_KEY=$(head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 48)
sed "s/CHANGE_ME_TO_A_RANDOM_STRING_OF_32_OR_MORE_CHARACTERS/$SECRET_KEY/" src/config.default.yaml > config.yaml

# Build from source (optional, can also pull viyh/whisper:0.5.1).
# The base images need a free Docker account: docker login dhi.io
# docker build -t viyh/whisper .

# Run
docker run -d --name whisper -p 8000:8000 \
    -v $(pwd)/config.yaml:/usr/src/app/config.yaml \
    viyh/whisper:0.5.1

Browse to http://localhost:8000⁠

For anything beyond local testing, Whisper must run behind a TLS-terminating proxy (a cloud load balancer, Cloud Run, Caddy, Traefik, ...). See Deploying⁠.

⁠Configuration

Copy src/config.default.yaml to config.yaml and customize. Mount it into the container at /usr/src/app/config.yaml.

⁠Required Settings
SettingDescription
secret_keyServer secret that keys the stored HMAC of each secret's auth token (see Cryptographic Flow⁠). Use a unique random string of 32+ characters; a shorter one starts with a warning. Change this from the default: Whisper won't start with the placeholder.
storage_classStorage backend class path (see Storage Backends⁠).
⁠Optional Settings
SettingDefaultDescription
storage_config{}Backend-specific settings (bucket name, path, etc.)
storage_clean_interval900Seconds between expired secret cleanup runs (at least 1).
max_data_size_kb100Maximum upload size in KB.
app_listen_ip0.0.0.0Listen address for the development server (python app.py) only.
app_port5000Port for the development server only. In the container, see WEB_PORT.
app_url_base/URL base path (e.g., /whisper/ for subpath hosting). A missing leading or trailing / is added.
argon2_time_cost5Argon2id time cost for the key derivation, which runs in the browser. Higher = slower to create and open secrets, and slower to guess passwords. Changing any Argon2id setting makes unexpired secrets unopenable.
argon2_memory_cost131072Argon2id memory cost in KB (131072 = 128 MB).
argon2_parallelism1Argon2id parallelism.
max_failed_attempts10Wrong passwords allowed per secret before it locks until it expires. A locked secret's encrypted data is deleted, so raising this later doesn't reopen it. 0 turns the lock off; the per-IP rate limit still applies.
create_rate_limit30Secrets each IP address can create per minute. 0 turns the limit off.
trusted_proxy_count0Number of X-Forwarded-For entries added by proxies in front of the container. See Running Behind a Proxy⁠.
⁠Environment Variables
VariableDefaultDescription
WEB_PORT8000Port the container listens on.
WEB_THREADS2Concurrent requests handled.
LOG_LEVELINFOSet to DEBUG for verbose logging.
CONFIG_FILEconfig.yamlConfig file path inside the container.
WHISPER_CONFIGThe config YAML itself. If set, used instead of CONFIG_FILE. For platforms that inject secrets as environment variables (e.g. ECS).
⁠Running Behind a Proxy

Whisper rate-limits and logs by client IP. Any load balancer or CDN in front of the container adds its own X-Forwarded-For entries, and Whisper needs to know how many to skip to find the real client. If this is too low, every visitor appears to come from the proxy and shares a single rate limit, so one client can block retrievals for everyone. If it is too high, clients can spoof their IP and dodge the limit.

Deploymenttrusted_proxy_count
Clients connect directly to the container0
One proxy that appends the client IP (e.g. AWS ALB, Caddy, Traefik, nginx)1
Google Cloud Run (*.run.app URL or domain mapping)1
Proxy that appends the client IP and its own IP (e.g. Google Cloud external Application Load Balancer)2

Proxy behavior varies, so verify after deploying: each request is logged as [<ip>] ..., and that IP should be your own public address, not a private or load balancer address. Also check that a request with a fake X-Forwarded-For: 1.2.3.4 header is still logged with your real IP; if not, the value is too high.

⁠Deploying

Whisper needs HTTPS in front of it: the browser crypto APIs require a secure context, and responses set HSTS. The container runs gunicorn directly and should not be exposed to the internet without a proxy, which also protects it from slow clients.

Use the GCS or S3 backend on Cloud Run or ECS; local and in-memory storage lose secrets when the container restarts or is replaced. Keep one instance (or task), since rate limits are kept in memory per instance.

⁠Storage Backends

⁠Local Disk (default)

Stores secrets as JSON files. Mount a volume for persistence.

storage_class: whisper.storage.local.local
storage_config:
    path: /tmp/whisper
docker run -d --name whisper -p 8000:8000 \
    -v $(pwd)/config.yaml:/usr/src/app/config.yaml \
    -v whisper-data:/tmp/whisper \
    whisper
⁠In-Memory

Simplest and most secure -- secrets are lost on restart.

storage_class: whisper.storage.memory.memory
storage_config: {}
⁠AWS S3

Uses S3 object tags (create_date, expire_date) so the cleanup process only reads tags, not full objects.

storage_class: whisper.storage.aws.s3
storage_config:
    bucket_name: my-whisper-bucket
    bucket_path: secrets

Credentials: IAM role (recommended), credential file mount (-v ~/.aws:/.aws:ro), or environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION).

Minimum IAM permissions:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "s3:ListBucket", "s3:GetBucketLocation",
            "s3:GetObject", "s3:PutObject", "s3:DeleteObject",
            "s3:GetObjectTagging", "s3:PutObjectTagging", "s3:DeleteObjectTagging"
        ],
        "Resource": [
            "arn:aws:s3:::my-whisper-bucket",
            "arn:aws:s3:::my-whisper-bucket/*"
        ]
    }]
}
⁠GCP Cloud Storage

Uses object metadata (create_date, expire_date) for efficient cleanup.

storage_class: whisper.storage.gcp.gcs
storage_config:
    gcp_project: my-project
    bucket_name: my-whisper-bucket
    bucket_path: secrets

Credentials: Application default credentials (recommended), or mount gcloud config (-v ~/.config/gcloud:/.config/gcloud:ro).

Required GCS permissions:

storage.objects.get, storage.objects.update, storage.objects.list,
storage.objects.create, storage.objects.delete,
storage.multipartUploads.create, storage.multipartUploads.abort,
storage.multipartUploads.listParts, storage.multipartUploads.list,
storage.buckets.get

Or use built-in roles on the bucket: roles/storage.objectUser + roles/storage.legacyBucketReader.

Disable the bucket's soft delete policy and object versioning so deleted secrets are really gone.

⁠Security Details

⁠Secret Structure
{
    "id": "ef61c74ad052f48f54d58eda0a5aeae3b90cd0d7ba7d25ce62b605ed6bfd59f1",
    "create_date": 1795075200,
    "expire_date": -1,
    "data": "Zwt3ihvb8Pe0oeBQHB8vjJZ4Y6yI+pn/36pZXoSuYFAA8S13B8XsnFL6YvqBaf4GaG0IRg==",
    "hash": "db8ad3a89de86ef3295c3cf50f4f915fa065e736fcc4d90849f1580268733099",
    "version": 3,
    "failed_attempts": 0
}
FieldDescription
idSHA-256 of the link token (64 hex characters). The token itself never reaches the server.
create_dateUNIX timestamp of creation.
expire_dateUNIX timestamp of expiration, or -1 for one-time use.
dataCiphertext from the browser: the 96-bit IV followed by the AES-256-GCM ciphertext, base64-encoded.
hashHMAC-SHA256 of the auth token, keyed with secret_key.
versionFormat version. Only 3 can be created or opened (see Older Links⁠).
failed_attemptsWrong passwords so far (see max_failed_attempts).
⁠Cryptographic Flow (v3)

Creating a secret:

  1. The browser picks a random 22-character link token (base58, about 129 bits).
  2. The secret ID is the SHA-256 of "whisper v3 id:" + token.
  3. Argon2id(password, salt = token, with the configured cost) gives 256 bits, which HKDF-SHA256 splits into an AES-256-GCM key and a 256-bit auth token.
  4. The browser encrypts the secret with AES-256-GCM, using a random 96-bit IV and the secret ID as additional data, which binds the ciphertext to its ID.
  5. It sends the ID, the auth token and the ciphertext. The server stores the ciphertext and HMAC-SHA256(secret_key, auth token) under the ID, and never overwrites an existing ID.
  6. The link is https://<host>/#<token>. Browsers don't send the part after # to servers.

Opening a secret:

  1. The browser takes the token from the link and derives the ID, auth token and key from it and the password, as above.
  2. It sends the ID and the auth token. The server compares HMACs in constant time, and counts wrong passwords toward max_failed_attempts.
  3. For one-time secrets: atomic claim-and-delete before returning data.
  4. The browser decrypts the secret and removes the token from the address bar and history.

The server never sees the plaintext, the password, or the link token. Someone with a copy of the storage and secret_key but not the link can't decrypt a secret or guess its password offline, since the token is the Argon2id salt.

Links made before 0.4.0 (https://<host>/<40 hex characters>) can't be opened by 0.4.0 or later; Whisper says so instead. Their stored secrets are deleted when they expire.

For pre-0.2.0 (v1) links, check out the release/0.1.0_to_0.2.0⁠ branch, which retains v1 decryption support.

⁠Rate Limiting

The default in-memory rate limiter (storage_uri="memory://") keeps state in the container's single gunicorn process. With multiple containers or instances, each one enforces limits independently. The counts also reset when the container restarts, which on Cloud Run includes every cold start after scaling to zero. For shared rate-limit state across workers, configure a Redis backend via flask-limiter⁠.

⁠Development

⁠Writing Storage Backends

Storage backends must subclass store and implement:

MethodDescription
start()Initialize the backend.
get_secret(secret_id)Return secret object or False.
set_secret(s)Save a new secret. Never overwrite: atomically return False without writing if one with that ID exists (IDs come from the browser).
delete_secret(secret_id)Delete a secret.
update_secret(s)Save changes to an existing secret; return False without writing if it no longer exists (never recreates a claimed secret).
claim_secret(secret_id)Atomically delete and return True if it existed (for one-time secrets).
increment_failed_attempts(s)Optional. Add one to the stored failed_attempts; return False if the secret no longer exists. The default does it through update_secret; override it to count atomically.
delete_expired()Iterate stored secrets and delete any where is_expired() returns True.

See src/whisper/storage/memory.py for a minimal example.

⁠Running for Development
docker build -t whisper:dev .
docker run -it --rm --name whisper -p 8000:8000 \
    -e LOG_LEVEL=DEBUG \
    -v $(pwd)/src/config.yaml:/usr/src/app/config.yaml \
    whisper:dev
⁠Building

The image builds on Docker Hardened Images⁠, which are free but need a Docker account: run docker login dhi.io first. The runtime image has no shell or package manager.

# Standard build
docker build -t whisper:0.5.1 .

# Cross-platform build
docker buildx build --platform=linux/amd64,linux/arm64 \
    -t whisper:0.5.1 .
⁠Tech Stack

Backend: Python 3.14, Flask 3.1, Gunicorn 27 (Docker Hardened Images, Debian 13)

Client-side crypto: Web Crypto API (AES-256-GCM, HKDF, SHA-256), argon2-browser (WASM, served from the image; see src/whisper/assets/vendor)

Frontend: vanilla JS and CSS, no framework and no CDN (copy uses the browser Clipboard API)

Storage: Local disk, in-memory, AWS S3, GCP Cloud Storage

⁠Contributing

Pull requests are welcome. See CONTRIBUTING.md⁠ for setup and guidelines. For security issues, see SECURITY.md⁠.

⁠Author

Joe Richards (GitHub: @viyh⁠)

⁠License

MIT License⁠

Tag summary

Content type

Image

Digest

sha256:f9df2187c…

Size

53.1 MB

Last updated

about 16 hours ago

docker pull viyh/whisper