A deterministic ASCII character generator written in Rust.
gacs is a CLI tool that generates reproducible ASCII strings (such as passwords or secret tokens) from a seed string, an optional file-based salt, and customizable character sets. It uses SHA-512 to deterministically derive the output from these inputs.
- Deterministic Generation: For a given seed, salt, character set, rule, and output length, the same inputs always produce the same character sequence.
- File-Based Salt: Incorporates the exact contents of any local file (images, documents, audio, etc.) into the input. Large files are streamed efficiently with minimal memory overhead. The salt file contributes to the output only if its contents are unknown to an attacker.
- Flexible Pre-defined Character Sets: Offers 4 built-in base sets optimized for different use cases:
- Standard BASE64 set.
- URL-Safe characters.
- Password-Safe characters (excludes visually ambiguous characters like
O,0,l,1and introduces symbols). - Shell-Safe characters (includes only alphanumeric characters,
., and_to avoid shell-specific quotation issues).
- Custom Character Modification Rules: Allows you to customize the base set by removing specific characters and appending new ones to meet specific string policies.
For a quick setup without a Rust environment, download the pre-compiled binaries for your platform from the GitHub Releases page.
We provide small, optimized binaries for the following targets:
| OS | Architecture / Environment | Archive File |
|---|---|---|
| Linux (GNU) | x86_64 | gacs-x86_64-unknown-linux-gnu.tar.gz |
| AArch64 | gacs-aarch64-unknown-linux-gnu.tar.gz |
|
| Linux (musl) | x86_64 | gacs-x86_64-unknown-linux-musl.tar.gz |
| AArch64 | gacs-aarch64-unknown-linux-musl.tar.gz |
|
| macOS | Apple Silicon (AArch64) | gacs-aarch64-apple-darwin.tar.gz |
| Intel (x86_64) | gacs-x86_64-apple-darwin.tar.gz |
|
| Windows | x86_64 (MSVC) | gacs-x86_64-pc-windows-msvc.zip |
| AArch64 (MSVC) | gacs-aarch64-pc-windows-msvc.zip |
Extract the archive and move the gacs (or gacs.exe) binary to a directory in your system's PATH.
Tip
Which Linux binary should I choose?
- GNU (
-gnu): Dynamically linked againstglibc. This is the standard choice for most mainstream Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). - musl (
-musl): Statically linked againstmusl libc, reducing runtime library dependencies. It is useful for minimal Linux environments such as Alpine Linux, OpenWrt, or distroless Docker containers.
If you prefer to compile gacs manually, you will need a Rust development environment installed (cargo). Clone the repository and build the binary:
git clone https://github.com/comosense/gacs.git
cd gacs
# Build with release optimizations
cargo build --release
# The compiled binary will be located at:
./target/release/gacs --help
Provide a seed string to generate a deterministic 32-character string using the default Password-Safe (ps) character set.
$ gacs my_secret_seed
@GP5m7ijz@R@yXoasokyE86PjTqWeYMc
The same seed and parameters always produce the same output.
Tip
If the seed argument is omitted, a random seed will be automatically generated. The generated seed can be displayed with --verbose if reproducibility is needed.
Use the -v (--verbose) flag to display the generated output alongside the parameters and the finalized character table used.
$ gacs my_secret_seed -v
@GP5m7ijz@R@yXoasokyE86PjTqWeYMc
[SEED] my_secret_seed
[LENGTH] 32
[CHARSET] ABCDEFGH!JKLMN@PQRSTUVWXYZabcdefghijk#mnopqrstuvwxyz$%23456789-_
Modify the output length with -l (--length) and switch the character set via -c (--charset).
64(BASE64):ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/us(URL-Safe):ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_ps(Password-Safe):ABCDEFGH!JKLMN@PQRSTUVWXYZabcdefghijk#mnopqrstuvwxyz$%23456789-_ss(Shell-Safe):ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._
# Generate a 16-character URL-Safe string
$ gacs my_secret_seed -l 16 -c us
OGP5m7ijzOROyXoa
Modify the character set by removing specific characters and appending new ones using the -r (--rule) flag. Format: 'characters_to_remove:characters_to_add'.
# Remove 'Z', 'z', and '9' from the charset, and append '^', '&', and '*'
$ gacs my_secret_seed -r 'Zz9:^&*'
@GP7n-jk%@R@$Xpbtp#$E_8PkTrWfYMd
Use the -s (--salt) option to incorporate the exact contents of a local file into the generation input. The output will only match when the seed, salt contents, and other generation parameters are identical.
# Incorporate a local image file as additional input
$ gacs my_secret_seed -s path/to/secret_image.jpgThe salt file is not a password-hardening mechanism by itself. If an attacker knows or can reproduce both the seed and the salt file contents, they can reproduce the output.
The file contents are streamed and are not loaded into memory in their entirety.
Generate multiple strings at once using the -n (--count) flag. Each string is generated from a separate randomly generated seed.
A manual [SEED] argument cannot be used together with -n (--count).
To view or save the generated seeds for future reproduction, combine this option with the -v (--verbose) flag.
# Generate 3 strings simultaneously with their auto-generated seeds
$ gacs -n 3 -v
sF@#%Rbq5CM%Y9CxL%6Xpo3$okq$RnJT
[SEED(Auto)] q1akBXyCPWB8vneEn3UKkCA9vqN7AI8MYIRH0gPfDangyi3DqoUh8.CJlggUDSv3XBCiYffVle9w_Grx
r4$m#HGvP-_ysF35xH2s7EC5Jq#xaiNb
[SEED(Auto)] Xi9uC74BV0dQ2ys0J3iCyDSxUASZGRdW8sYeR7zDkHYPHM8KuosaSOtyMXKgN69PbfHjtTzS7knT8SWL
jT_V@beU-KU5%Li#G_hRWDPVLvK2$FAq
[SEED(Auto)] o2.faPVAuJsR1Zxuz73TaLdXNcXCtFkw7LAjU9IixkshYNcclvWcSYHAekBUXJbh8gwCa.hpyowIMI1J
[LENGTH] 32
[CHARSET] ABCDEFGH!JKLMN@PQRSTUVWXYZabcdefghijk#mnopqrstuvwxyz$%23456789-_
When you omit the manual [SEED] argument, gacs automatically generates a random seed. By default, the seed is generated at the maximum supported length.
You can customize the length of auto-generated seeds using the -L (--seed-length) option.
# Generate a string using a shorter 16-character auto-generated seed
$ gacs -L 16 -v
WPkMAdVNBhJ2$fG24ZWZUVN#Ss-qR$gZ
[SEED(Auto)] rcJsnGlKN6KvBU1W
[LENGTH] 32
[CHARSET] ABCDEFGH!JKLMN@PQRSTUVWXYZabcdefghijk#mnopqrstuvwxyz$%23456789-_
Note
The -L (--seed-length) option specifically configures the length of the seed, not the final output string. It conflicts with a manual [SEED] argument and can only be used when seeds are being auto-generated.
Arguments:
[SEED] Base string to generate the characters from (generated automatically if omitted)
Options:
-s, --salt <FILE> Optional file to use as an additional cryptographic salt
-l, --length <LENGTH> Length of the generated string [default: 32]
-c, --charset <CHARSET> Character set to use (64, us, ps, ss) [default: ps]
-r, --rule <RULE> Modify the charset by removing and appending characters (Format: 'remove:add')
-n, --count <COUNT> Number of strings to generate
When this is set, seeds are auto-generated; conflicts with [SEED]
-L, --seed-length <LENGTH> Length of the auto-generated seed; conflicts with [SEED]
If omitted, the maximum possible length is applied
-v, --verbose Print detailed configuration along with the generated string(s)
-h, --help Print help
-V, --version Print version
The security of a generated secret ultimately depends on the unpredictability of its inputs.
When a seed is provided manually, use a sufficiently long and unpredictable seed. Do not use easily guessable values such as usernames, dates, dictionary words, or reused passwords.
When no seed is provided, a random seed will be automatically generated.
gacs uses SHA-512 to deterministically derive output from the seed and optional salt. Changing the input generally results in a substantially different digest and output.
However, deterministic generation does not increase the entropy of a weak seed. An attacker who can guess the seed and salt can reproduce the output.
The salt file is additional input, not a password-hardening mechanism. A salt file only adds secrecy when its contents are unknown to an attacker.
The output depends on the exact file contents, not the file name, path, modification time, or other file metadata.
--verbose prints the seed used for generation. Do not use --verbose when the seed must remain secret, especially when command output may be recorded in logs or shell history.
The current SHA-512 based generation algorithm supports output lengths up to 86 characters. Shorter outputs have correspondingly fewer possible values and should be chosen according to the security requirements of the intended use.
For a given gacs version, the same seed, salt contents, character set, character modification rule, and output length produce the same output.
Future versions may change the generation algorithm or built-in character sets. Applications that depend on long-term reproducibility should pin the gacs version.
Warning
gacs is a deterministic generator when given an explicit seed. For high-value secrets, use the default random-seed mode or another trusted cryptographic random generator unless reproducibility is specifically required. Do not use predictable or reused seeds for security-sensitive values.
This project is licensed under the MIT License - see the LICENSE file for details.