Expand description
Collision-free, random-looking codes from a counter.
Dealcode maps a non-negative integer counter n (from a database sequence
or any other source that never repeats) to a short, fixed-alphabet,
random-looking string called a code, and back. The mapping is a keyed
bijection (FF1 format-preserving encryption per NIST SP 800-38G), so two
different counters can never produce the same code, and a code decodes
back to its counter for anyone holding the key.
This crate implements format version 1 of the dealcode spec exactly; codes are byte-for-byte interoperable with every other conforming implementation.
§Quickstart
use dealcode::Dealcode;
let codec = Dealcode::new("0a1b...64-hex-chars-from-your-secret-manager")?;
let code = codec.encode(1)?; // "421163" — 6 hex chars
assert_eq!(code.len(), 6);
assert_eq!(codec.decode(&code)?, 1); // never collides with any other counterCodes start at min_length characters and grow by one character only when
the current length is exhausted; the growth schedule, alphabet handling,
and tweak derivation are all fixed by the spec.
§Configuration
use dealcode::Dealcode;
let coupons = Dealcode::builder("your-secret-key")
.alphabet("crockford") // human-friendly codes, e.g. "7Q4WKZ"
.min_length(6)
.max_length(10)
.domain("coupons") // same key, unrelated codes per domain
.build()?;
let orders = Dealcode::builder("your-secret-key")
.alphabet("dec") // digits only
.min_length(8)
.domain("orders")
.build()?;
let n = coupons.decode(&coupons.encode(42)?)?;
assert_eq!(n, 42);Immutability rule: for a given code namespace, the entire
configuration — key, alphabet, min_length, max_length, domain — must
never change once codes have been issued.
§Keys
Any non-empty key material is accepted (Key): raw bytes of exactly
16/24/32 bytes are used directly as the AES key; any other bytes, and
all strings (a hex-looking string is not auto-decoded), are expanded to
an AES-256 key via SHA-256("dealcode/v1/kdf" ‖ material). Prefer at
least 128 bits of randomness, e.g. openssl rand -hex 32.
Modules§
- alphabets
- Alphabet presets and normalization rules (SPEC.md §3).
Structs§
- Builder
- Configures and builds a
Dealcodecodec. - Cycling
Builder - Configures and builds a
CyclingDealcodecodec. - Cycling
Dealcode - A fixed-length cycling codec (dealcode mode v1c, SPEC.md §11): codes are
always exactly
lengthcharacters, and the counter space is spent in cycles ofcapacity= radix^lengthcodes each. - Dealcode
- A dealcode codec: a bijective
counter <-> codemapping (SPEC.md). - Key
- Key material for a
Dealcodecodec (SPEC.md §2.1).
Enums§
- Error
- All the ways dealcode can refuse to work, in three distinguishable kinds (SPEC.md §8).