Ciranda

A deterministic password generator

---

Project maintained by w4m3r Hosted on GitHub Pages — Theme by mattgraham

Design Overview

Ciranda is a deterministic password generator. Given the same inputs, it produces the same password.

The design is intentionally split into two stages:

1. enhance the human-entered seed into fixed-size key material
2. construct an exact-length password from that key material

This separation keeps the password-hardening concern distinct from the output format concern. Argon2id handles the cost of guessing the seed. The password construction stage handles length, character sets, and deterministic placement.

Inputs

The CLI prompts for:

• seed: the master secret, entered hidden and confirmed
• context: a service, account, or domain label
• length: the desired password length, from 4 to 128
• character sets: uppercase, lowercase, digits, and/or special characters
• Argon2 profile: the named derivation-cost profile

The library exposes the same model through:

• enhance
• PasswordSettings
• CharacterSets
• CharacterSet
• Argon2Profile
• Argon2Settings

Pipeline

The current derivation pipeline is:

1. hash context with BLAKE3 to produce a 16-byte salt
2. enhance seed with Argon2id using that salt
3. derive a fixed 64-byte key
4. split that key into two 32-byte BLAKE3 stream keys
5. build character buckets from the selected character sets
6. shuffle the buckets with a deterministic Fisher-Yates shuffle
7. pick one character from each bucket with a deterministic byte stream
8. copy the resulting password to the clipboard

The output depends on all of these values:

• seed
• context
• password length
• selected character sets
• Argon2 memory cost
• Argon2 time cost
• Argon2 parallelism cost

Changing any of them can change the generated password.

Determinism

Ciranda does not store generated passwords. Determinism lets a user regenerate a password from the same stable inputs instead of saving the password somewhere else.

That makes input discipline important. The seed and context must be typed consistently, and profile changes should be treated as derivation-policy changes because they also change the output.

Cost Profiles

Argon2 exposes low-level parameters, but normal CLI usage should not require users to tune them one by one. Ciranda therefore provides named profiles:

• Development: fast, low-cost settings for tests and local iteration
• Standard: the normal interactive profile
• Hardened: a high-memory profile for capable machines

The profile controls how expensive seed guessing is. It is not the recommended rotation mechanism. Rotate by changing the seed for global rotation, or by changing or versioning the context for service-specific rotation.

Password Construction

The final stage constructs a password instead of encoding random bytes directly. That gives Ciranda explicit output guarantees:

• the password length is exact
• only selected character groups are used
• every selected group appears at least once
• equivalent settings produce equivalent output

This is why the output stage uses buckets, deterministic shuffling, and unbiased index selection instead of a direct byte-to-text encoding.