https://github.com/sorairolake/randgen
Generate pseudo-random bytes
https://github.com/sorairolake/randgen
cli command-line command-line-tool generator random random-generation rust rust-lang terminal tool
Last synced: 12 months ago
JSON representation
Generate pseudo-random bytes
- Host: GitHub
- URL: https://github.com/sorairolake/randgen
- Owner: sorairolake
- License: apache-2.0
- Created: 2025-03-10T12:57:34.000Z (over 1 year ago)
- Default Branch: develop
- Last Pushed: 2025-06-22T12:32:26.000Z (about 1 year ago)
- Last Synced: 2025-06-22T13:33:26.036Z (about 1 year ago)
- Topics: cli, command-line, command-line-tool, generator, random, random-generation, rust, rust-lang, terminal, tool
- Language: Rust
- Homepage:
- Size: 291 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.adoc
- Contributing: CONTRIBUTING.adoc
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Authors: AUTHORS.adoc
Awesome Lists containing this project
README
# randgen
[![CI][ci-badge]][ci-url]
[![Version][version-badge]][version-url]
![MSRV][msrv-badge]
![License][license-badge]
**randgen** is a tool which generates random bytes using a pseudorandom number
generator (PRNG).
## Installation
### From source
```sh
cargo install randgen
```
### From binaries
The [release page] contains pre-built binaries for Linux, macOS and Windows.
### How to build
Please see [BUILD.adoc].
## Usage
### Basic usage
Generate 1 KiB of random bytes:
```sh
randgen 1KiB
```
### Output formats
The following output formats are available:
- `raw` (encode the generated bytes as raw bytes)
- `base64` (encode the generated bytes as [base64])
- `base64url` (encode the generated bytes as [URL-safe base64])
- `hex` (encode the generated bytes as hex string)
> [!TIP]
> The result is output on a single line, so there is no line wrapping.
The default output format is `raw`. To change this, use `-f` option.
```sh
randgen -f base64 256
```
This has the same result as:
```sh
randgen 256 | base64 -w 0
```
### Supported PRNGs and CSPRNGs
Supported PRNGs are:
- [ISAAC] RNGs (if enabled at compile time)
- [Mersenne Twister] RNGs (if enabled at compile time)
- [PCG] RNGs (if enabled at compile time)
- [SFC] RNGs (if enabled at compile time)
- [Xorshift] family
- SplitMix64 RNG
- Xorshift RNG (if enabled at compile time)
- xoroshiro RNGs
- xoshiro RNGs
Supported CSPRNGs are:
- [ChaCha]-based RNGs
- [HC-128]-based RNG (if enabled at compile time)
The default RNG is `chacha12`. To change this, use `-r` option.
```sh
randgen -r pcg64 "2 MB"
```
### Providing a random seed
`-s` option allows you to specify a 64-bit unsigned integer random seed to be
used when creating a new PRNG. If this option is not specified, the RNG seeded
via random data from system sources such as the [`getrandom`] system call on
Linux.
```sh
$ randgen -f hex -r sfc32 -s 8 32B
24f48cd0c3f6a1c6e8d7b4dcff9578864aced749e4eb1805dfba8b6e21d0cba0
```
This has the same result as:
```sh
$ randgen -r sfc32 -s 8 32B | xxd -c 0 -p
24f48cd0c3f6a1c6e8d7b4dcff9578864aced749e4eb1805dfba8b6e21d0cba0
```
### Print the progress bar
When `-p` option is specified, `randgen` will print information showing the
progress of the generation of random bytes.
```sh
randgen -p 4GiB > /dev/null
```
This is similar to the following example which uses [`pv(1)`]:
```sh
randgen 4GiB | pv -s 4G > /dev/null
```
### Generate shell completion
`--generate-completion` option generates shell completions to standard output.
The following shells are supported:
- `bash`
- `elvish`
- `fish`
- `nushell`
- `powershell`
- `zsh`
Example:
```sh
randgen --generate-completion bash > randgen.bash
```
### Integration with other programs
#### Encode the generated bytes
To encode the generated bytes into an output format not supported by `randgen`,
pipe the output of `randgen` to the input of another program.
For example, to encode the generated bytes as [base32]:
```sh
$ randgen -s 16 32B | base32
DYQZ33GRHUR5WIFRSBZVQ3ZPEFZASXB3SNTRUHR3NPITZBMDPZXQ====
```
#### Line wrapping
`randgen` does not wrap lines of the result.
To wrap lines of the result:
```sh
$ randgen -f base64url -s 256 128B | fold -w 76
0X82yjVU1_JLdDU07ywJ_7CAJBwRTEVS_i1-kRgR6HQsb9jFyQNuiFIBmrTucpwt-CZjZj90JYjE
6D2erJEn6f8ju9KBmLraVj55I9KQRxhh2BmJMrovQhEK9nU3Ysn-mOURovtVCE45dqKyWTHuWLV2
Hr1yramxGwVm88LXhA8=
```
This has the same result as:
```sh
$ randgen -s 256 128B | basenc --base64url
0X82yjVU1_JLdDU07ywJ_7CAJBwRTEVS_i1-kRgR6HQsb9jFyQNuiFIBmrTucpwt-CZjZj90JYjE
6D2erJEn6f8ju9KBmLraVj55I9KQRxhh2BmJMrovQhEK9nU3Ysn-mOURovtVCE45dqKyWTHuWLV2
Hr1yramxGwVm88LXhA8=
```
### Comparison with similar things
The following generates 64 KiB of random bytes and encodes it as base64:
```sh
randgen -f base64 64KiB
```
This section describes how to do the same thing with other things.
#### OpenSSL
[`openssl-rand(1ssl)`] can be used for this purpose.
```sh
openssl rand -base64 64K
```
#### GnuPG
[`gpg --gen-random`] can be used for this purpose.
```sh
gpg --gen-random 1 65536 | base64
```
#### Kernel random number source devices
[`random(4)`] (`/dev/random` and `/dev/urandom`) can be used for this purpose.
```sh
head -c 65536 /dev/random | base64
```
> [!CAUTION]
> Unlike `randgen`, these things wrap lines of the result.
## Command-line options
Please see the following:
- [`randgen(1)`]
## Source code
The upstream repository is available at
.
## Changelog
Please see [CHANGELOG.adoc].
## Contributing
Please see [CONTRIBUTING.adoc].
## License
Copyright (C) 2025 Shun Sakai (see [AUTHORS.adoc])
1. This program is distributed under the terms of either the _Apache License
2.0_ or the _MIT License_.
2. Some files are distributed under the terms of the _Creative Commons
Attribution 4.0 International Public License_.
This project is compliant with version 3.3 of the [_REUSE Specification_]. See
copyright notices of individual files for more details on copyright and
licensing information.
[ci-badge]: https://img.shields.io/github/actions/workflow/status/sorairolake/randgen/CI.yaml?branch=develop&style=for-the-badge&logo=github&label=CI
[ci-url]: https://github.com/sorairolake/randgen/actions?query=branch%3Adevelop+workflow%3ACI++
[version-badge]: https://img.shields.io/crates/v/randgen?style=for-the-badge&logo=rust
[version-url]: https://crates.io/crates/randgen
[msrv-badge]: https://img.shields.io/crates/msrv/randgen?style=for-the-badge&logo=rust
[license-badge]: https://img.shields.io/crates/l/randgen?style=for-the-badge
[release page]: https://github.com/sorairolake/randgen/releases
[BUILD.adoc]: BUILD.adoc
[base64]: https://datatracker.ietf.org/doc/html/rfc4648#section-4
[URL-safe base64]: https://datatracker.ietf.org/doc/html/rfc4648#section-5
[ISAAC]: https://www.burtleburtle.net/bob/rand/isaacafa.html
[Mersenne Twister]: https://www.math.sci.hiroshima-u.ac.jp/m-mat/MT/emt.html
[PCG]: https://www.pcg-random.org/
[SFC]: https://pracrand.sourceforge.net/RNG_engines.txt
[Xorshift]: https://prng.di.unimi.it/
[ChaCha]: https://cr.yp.to/chacha.html
[HC-128]: https://en.wikipedia.org/wiki/HC-128
[`getrandom`]: https://man7.org/linux/man-pages/man2/getrandom.2.html
[`pv(1)`]: https://www.ivarch.com/programs/quickref/pv.shtml
[base32]: https://datatracker.ietf.org/doc/html/rfc4648#section-6
[`openssl-rand(1ssl)`]: https://docs.openssl.org/3.4/man1/openssl-rand/
[`gpg --gen-random`]: https://gnupg.org/documentation/manuals/gnupg24/gpg.1.html
[`random(4)`]: https://man7.org/linux/man-pages/man4/random.4.html
[`randgen(1)`]: docs/man/man1/randgen.1.adoc
[CHANGELOG.adoc]: CHANGELOG.adoc
[CONTRIBUTING.adoc]: CONTRIBUTING.adoc
[AUTHORS.adoc]: AUTHORS.adoc
[_REUSE Specification_]: https://reuse.software/spec-3.3/