Go Reference ยท Encoding and Data Formats
The Go crypto/rand package
Reference for Go's crypto/rand package: Read, Text, Int and Prime, why it differs from math/rand, error handling, and building tokens and IDs safely.
crypto/rand gives you random data that is safe to use for secrets: session tokens, API keys, password reset links, salts and nonces. The bytes come from the operating system's cryptographically secure generator, so nobody can predict the next value from earlier ones.
This is a different tool from math/rand. The math/rand generators are fast and good for simulations and games, but they are predictable and must never produce secrets. If an attacker could benefit from guessing the value, use crypto/rand.
b := make([]byte, 16) _, err := rand.Read(b) // fills b with random bytes
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
var Reader io.Reader func Read(b []byte) (n int, err error) func Text() string func Int(rand io.Reader, max *big.Int) (n *big.Int, err error) func Prime(rand io.Reader, bits int) (*big.Int, error)
| Name | Description |
|---|---|
b |
The slice to fill completely with random bytes. |
max |
Exclusive upper bound for Int. Must be greater than zero. |
bits |
Bit length of the prime for Prime; must be at least 2. |
Reader |
The global source. Pass it where an io.Reader of randomness is needed. |
Returns: Read fills the whole slice. Text returns a string of 26 characters from the base32 alphabet (A-Z and 2-7). Int returns a uniform value in [0, max).
Errors and edge cases:
- Since Go 1.24,
rand.Readnever returns an error: if the operating system fails, the program crashes irrecoverably. In older versions it could return an error, so keep the check if you support them. rand.Intpanics whenmax <= 0, so validate the bound first.Text()and theReadchange need Go 1.24;Readerhas always existed.
Usage notes
- Never use
math/randfor secrets. Do not seed it with the time, and do not usemath/rand/v2for tokens either. Both are for statistics, not security. - Token length: 16 random bytes (128 bits) is a strong minimum for session and reset tokens; 32 bytes is common for API keys.
- Encode before showing. Raw random bytes are not printable. Use
hex,base64.RawURLEncodingorrand.Text(). - Avoid modulo bias.
int(b[0]) % 6favors small numbers because 256 is not divisible by 6. Userand.Int. - Speed: each call may involve a system call, so for bulk non-secret data prefer
math/rand/v2. - UUIDs: the standard library has no UUID package. Version 4 UUIDs are 16 bytes from
rand.Readwith a few bits fixed, or use a well-known third-party module. - Keys and nonces: AEAD ciphers such as AES-GCM need a unique nonce for each message. Draw it from
rand.Read.