fosster/rexcrypt
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions

feat/tools/rexcrack #14

Merged
sezieru merged 15 commits from feat/tools/rexcrack into main 2025-10-19 10:29:46 +00:00
Conversation 0 Commits 15 Files changed 7 +818 -38
sezieru commented 2025-10-19 10:25:35 +00:00
Owner
Copy link

feat: add rexcrack dictionary-attack demo (multithreaded) + tests & docs

This PR introduces rexcrack, a small, heavily-commented companion tool to RexCrypt for teaching how verification can be composed into a dictionary attack. It’s intentionally educational (not production hardening), and mirrors RexCrypt’s CLI/design philosophy.

Summary

  • New binary: bin/rexcrack

  • Purpose: multithreaded dictionary attack demo using crypt_r(3) (“stored hash as setting” verification).

  • Validation: anchored regex checks for supported crypt(5) formats; uses crypt_checksalt() when available. Legacy DES/bigcrypt accepted on purpose (teaching).

  • Concurrency: pool of pthread workers; one struct crypt_data per thread; shared fgets under mutex; overlong line drain so the next candidate isn’t polluted.

  • I/O discipline: winner printed on stdout; verbose logs (if enabled) go to stderr.

  • Exit codes:

    • 0 → match found
    • 2 → not found
    • errors → EX_* from <sysexits.h> (e.g., EX_NOINPUT bad file, EX_DATAERR invalid hash)

Also included:

  • Makefile: builds rexcrack; tests depend on both binaries.
  • Tests: TAP v14 cases for match/not-found/error, stdout/stderr discipline, overlong wordlist handling, invalid hash, and file errors.
  • Docs: README/TESTING updated with usage, semantics, and notes.

CLI

rexcrack -h <hash> -w <wordlist> [-t <threads>] [-v]
  • -h <hash>: stored hash (exact string produced by rexcrypt)
  • -w <wordlist>: newline-separated candidates (blank + overlong lines are fine)
  • -t <threads>: default = #CPUs, min 1, soft cap 64
  • -v: verbose tracing to stderr (stdout reserved for the winner)

Example:

H="$(./bin/rexcrypt -k hunter2)"
./bin/rexcrack -h "$H" -w tests/wordlist.txt -t 8

Testing

Run everything:

make distclean && make test

Expect all green; sample end of TAP output:

ok 15 - rexcrack - match returns 0
ok 16 - rexcrack - not found returns 2
ok 17 - rexcrack - bad file returns EX_NOINPUT
ok 18 - rexcrack - bad hash rejected with EX_DATAERR

The suite also covers:

  • stdout/stderr separation (winner on stdout; logs on stderr)
  • overlong first line → hunter2 still found (drain works)
  • thread-count edges (coerce/clamp)

Notes for reviewers

  • Regex table: Anchored POSIX-ERE. sha1crypt length is documented with a note (manpage discrepancy); current pattern matches real output on our systems. SunMD5 pattern follows docs; inconsistencies are commented for students.
  • Legacy formats: DES (13-char) and bigcrypt are intentionally accepted to demonstrate why these are legacy/weak—called out in README.
  • Return precedence: fatal library failure prefers EX_SOFTWARE over generic failure; normal outcomes remain 0/2.
  • Signals: SIGINT sets a stop flag for graceful early exit (teachable systems touchpoint).

Why this is useful (pedagogical goals)

  • Reinforces the “hash-as-setting” verify method from RexCrypt.
  • Demonstrates safe state per thread (crypt_r), shared I/O under a mutex, and handling of tricky inputs (overlong lines).
  • Shows a clean interface for scripting via exit codes and stdout/stderr discipline.
  • Provides students a safe, bounded offensive-security exercise with clear ethics guidance.

How to review

  • Build both tools: make

  • Smoke test:

    H="$(./bin/rexcrypt -k default)"
./bin/rexcrack -h "$H" -w tests/wordlist.txt -t 4

  • Skim README “rexcrack” section and TESTING updates for clarity/accuracy.

  • (Optional) Try a different algorithm:

    H="$(./bin/rexcrypt -a 7 -k s3cret)"
./bin/rexcrack -h "$H" -w tests/wordlist.txt

Commit highlights (latest first)

  • fix(rexcrack): adjust flag summary debug output and return precedence
  • docs(rexcrack,tests): add rexcrack usage, exit semantics, and TAP coverage
  • build(makefile): quiet compiler output
  • refactor(test): use new wordlist + add tests
  • test(rexcrack): TAP cases for match/no-match/error; accept EX_* as error
  • feat(rexcrack): multithreaded dictionary-attack demo (crypt_r + pthreads)
  • …(others: debug/cleanup/Makefile wiring)

Checklist

  • Builds on clang/gcc with -Wall -Wextra
  • make test passes (TAP v14)
  • README and TESTING updated
  • No behavior change to rexcrypt CLI

Ready for review.

# feat: add `rexcrack` dictionary-attack demo (multithreaded) + tests & docs This PR introduces **`rexcrack`**, a small, heavily-commented companion tool to RexCrypt for teaching how verification can be composed into a dictionary attack. It’s intentionally educational (not production hardening), and mirrors RexCrypt’s CLI/design philosophy. ## Summary * **New binary:** `bin/rexcrack` * **Purpose:** multithreaded dictionary attack demo using `crypt_r(3)` (“stored hash as setting” verification). * **Validation:** anchored regex checks for supported `crypt(5)` formats; uses `crypt_checksalt()` when available. Legacy DES/bigcrypt accepted on purpose (teaching). * **Concurrency:** pool of pthread workers; one `struct crypt_data` per thread; shared `fgets` under mutex; overlong line **drain** so the next candidate isn’t polluted. * **I/O discipline:** winner printed on **stdout**; verbose logs (if enabled) go to **stderr**. * **Exit codes:** * `0` → match found * `2` → not found * **errors** → `EX_*` from `<sysexits.h>` (e.g., `EX_NOINPUT` bad file, `EX_DATAERR` invalid hash) Also included: * **Makefile:** builds `rexcrack`; tests depend on both binaries. * **Tests:** TAP v14 cases for match/not-found/error, stdout/stderr discipline, overlong wordlist handling, invalid hash, and file errors. * **Docs:** README/TESTING updated with usage, semantics, and notes. --- ## CLI ``` rexcrack -h <hash> -w <wordlist> [-t <threads>] [-v] ``` * `-h <hash>`: stored hash (exact string produced by `rexcrypt`) * `-w <wordlist>`: newline-separated candidates (blank + overlong lines are fine) * `-t <threads>`: default = #CPUs, min 1, soft cap 64 * `-v`: verbose tracing to **stderr** (stdout reserved for the winner) > Example: > > ``` > H="$(./bin/rexcrypt -k hunter2)" > ./bin/rexcrack -h "$H" -w tests/wordlist.txt -t 8 > ``` --- ## Testing Run everything: ``` make distclean && make test ``` Expect all green; sample end of TAP output: ``` ok 15 - rexcrack - match returns 0 ok 16 - rexcrack - not found returns 2 ok 17 - rexcrack - bad file returns EX_NOINPUT ok 18 - rexcrack - bad hash rejected with EX_DATAERR ``` The suite also covers: * stdout/stderr separation (winner on stdout; logs on stderr) * overlong first line → `hunter2` still found (drain works) * thread-count edges (coerce/clamp) --- ## Notes for reviewers * **Regex table:** Anchored POSIX-ERE. `sha1crypt` length is documented with a note (manpage discrepancy); current pattern matches real output on our systems. SunMD5 pattern follows docs; inconsistencies are commented for students. * **Legacy formats:** DES (13-char) and bigcrypt are intentionally accepted to *demonstrate* why these are legacy/weak—called out in README. * **Return precedence:** fatal library failure prefers `EX_SOFTWARE` over generic failure; normal outcomes remain 0/2. * **Signals:** SIGINT sets a stop flag for graceful early exit (teachable systems touchpoint). --- ## Why this is useful (pedagogical goals) * Reinforces the “hash-as-setting” verify method from RexCrypt. * Demonstrates safe state per thread (`crypt_r`), shared I/O under a mutex, and handling of tricky inputs (overlong lines). * Shows a clean interface for scripting via exit codes and stdout/stderr discipline. * Provides students a safe, bounded offensive-security exercise with clear ethics guidance. --- ## How to review * Build both tools: `make` * Smoke test: ``` H="$(./bin/rexcrypt -k default)" ./bin/rexcrack -h "$H" -w tests/wordlist.txt -t 4 ``` * Skim README “rexcrack” section and TESTING updates for clarity/accuracy. * (Optional) Try a different algorithm: ``` H="$(./bin/rexcrypt -a 7 -k s3cret)" ./bin/rexcrack -h "$H" -w tests/wordlist.txt ``` --- ## Commit highlights (latest first) * `fix(rexcrack): adjust flag summary debug output and return precedence` * `docs(rexcrack,tests): add rexcrack usage, exit semantics, and TAP coverage` * `build(makefile): quiet compiler output` * `refactor(test): use new wordlist + add tests` * `test(rexcrack): TAP cases for match/no-match/error; accept EX_* as error` * `feat(rexcrack): multithreaded dictionary-attack demo (crypt_r + pthreads)` * …(others: debug/cleanup/Makefile wiring) --- ## Checklist * [x] Builds on clang/gcc with `-Wall -Wextra` * [x] `make test` passes (TAP v14) * [x] README and TESTING updated * [x] No behavior change to `rexcrypt` CLI **Ready for review.**
sezieru self-assigned this 2025-10-19 10:25:35 +00:00 
- CLI: -h <hash>, -w <wordlist>, -t <threads>, -v (verbose)
- Worker pool: one crypt_data per thread; shared fgets under mutex with overlong-line drain
- Validation: regex-based validate_hash() (anchored patterns); lib fast-path via crypt_checksalt when available
- Signals: SIGINT sets stop flag for graceful shutdown
- Exit codes: 0=match, 2=not found, other=error (script-friendly)
- I/O: 1MB buffered read to reduce lock hold time
- alter test_case struct(type) to allow tracking the name of the binary being tested
- TAP runner now uses & displays that information
- renamed test_case variable
- README:
  - Add rexcrack companion tool section (usage, -v behavior, exit codes 0/2/EX_*)
  - Note both binaries in build outputs and manual compile tips
  - Mention overlong/blank line handling and legacy DES/bigcrypt (educational)
- TESTING:
  - Document rexcrack exit-code conventions and stdout/stderr discipline
  - Add examples referencing wordlist fixture and invalid-hash text checks
  - Include tests for match, not-found, bad file, bad hash
  - Update Test Definition Structure section to include relevant edits
  - Update tests to match new test_case structure
- debug format string prints -h/-w/-t/-v; use %lu for threads
- exit precedence: EX_SOFTWARE on fatal lib error before generic failure
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
sezieru
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: fosster/rexcrypt#14
No description provided.
Delete branch "feat/tools/rexcrack"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?