Skip to content
Tutorials Center
My learning

Topics

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.

Go
b := make([]byte, 16)
_, err := rand.Read(b) // fills b with random bytes

Try it

Go Random bytes, tokens and text

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.

Go Random integers in a range

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

Go
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.Read never 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.Int panics when max <= 0, so validate the bound first.
  • Text() and the Read change need Go 1.24; Reader has always existed.

Usage notes

  • Never use math/rand for secrets. Do not seed it with the time, and do not use math/rand/v2 for 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.RawURLEncoding or rand.Text().
  • Avoid modulo bias. int(b[0]) % 6 favors small numbers because 256 is not divisible by 6. Use rand.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.Read with 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.