README
¶
rndstr
A simple, secure random string generator for Go.
Installation
go get github.com/KarpelesLab/rndstr
Requires Go 1.24 or later.
Usage
Secure Random Strings (Recommended)
Use SimpleReader with crypto/rand.Reader for security-sensitive applications:
import (
"crypto/rand"
"github.com/KarpelesLab/rndstr"
)
// Generate a 32-character alphanumeric token
token, err := rndstr.SimpleReader(32, rndstr.Alnum, rand.Reader)
// Generate a human-readable code (no ambiguous characters)
code, err := rndstr.SimpleReader(8, rndstr.Code, rand.Reader)
// Generate a random password
password, err := rndstr.SimpleReader(16, rndstr.Password, rand.Reader)
Quick Non-Secure Strings
For non-security-sensitive use cases (e.g., test data):
// Uses math/rand - NOT cryptographically secure
s := rndstr.Simple(16, rndstr.Alnum)
Character Sets
| Constant | Length | Description |
|---|---|---|
Alpha |
52 | Lowercase and uppercase ASCII letters (a-z, A-Z) |
Alnum |
62 | Letters plus digits (a-z, A-Z, 0-9) |
Code |
31 | Uppercase letters and digits, excluding ambiguous characters (I, O, Q, 0, 1) for human readability |
Password |
87 | Alphanumeric plus special characters |
Custom Character Sets
You can use any string as a character set:
// Hexadecimal
hex, err := rndstr.SimpleReader(16, "0123456789abcdef", rand.Reader)
// Binary
bin, err := rndstr.SimpleReader(32, "01", rand.Reader)
Security
SimpleReaderuses unbiased random selection via rejection sampling, making it suitable for cryptographic purposes when used withcrypto/rand.ReaderSimpleusesmath/randand is not cryptographically secureSimpleFastReaderuses modulo reduction which introduces bias - deprecated in favor ofSimpleReader
License
See LICENSE file.
Documentation
¶
Overview ¶
Package rndstr provides functions for generating random strings.
The package offers multiple generation strategies with different security/performance tradeoffs:
SimpleReader: Secure, unbiased generation using any io.Reader source. Recommended for security-sensitive applications with crypto/rand.Reader.
Simple: Fast but uses math/rand (not cryptographically secure). Deprecated for security-sensitive use.
SimpleFastReader: Fast but biased. Deprecated in favor of SimpleReader.
Example usage:
// Secure random string s, err := rndstr.SimpleReader(32, rndstr.Alnum, rand.Reader) // Human-readable code (excludes ambiguous chars) code, err := rndstr.SimpleReader(8, rndstr.Code, rand.Reader)
Index ¶
Constants ¶
const ( // Alpha contains lowercase and uppercase ASCII letters. Alpha = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" // Alnum contains lowercase and uppercase ASCII letters plus digits. Alnum = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" // Code contains uppercase letters and digits, excluding ambiguous // characters (I, O, Q, 0, 1) for improved human readability. Code = "ABCDEFGHJKLMNPRSTUVWXYZ23456789" // Password contains alphanumeric characters plus common special characters. Password = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&~#([-|_^@)]{}$*,?;.:/!<>" )
Character sets for random string generation.
Variables ¶
var ErrInvalidRange = errors.New("rndstr: range must be greater than zero")
ErrInvalidRange is returned when an invalid range parameter is provided.
Functions ¶
func Simple
deprecated
func SimpleFastReader
deprecated
SimpleFastReader generates a random string using modulo reduction.
Deprecated: This function has biased output when the character set length does not evenly divide 256. For example, with Alnum (62 chars), some characters are ~1.6% more likely than others. Use SimpleReader instead for unbiased output.
Example: rndstr.SimpleFastReader(10, rndstr.Alnum, rand.Reader)
func SimpleReader ¶
SimpleReader generates a random string using the provided random source.
This function uses unbiased random selection and is suitable for security-sensitive applications when used with crypto/rand.Reader. It consumes at least 4 bytes of random input per generated character.
Example: rndstr.SimpleReader(10, rndstr.Alnum, rand.Reader)
Types ¶
This section is empty.
Source Files