random

README

go-random

A fast, clear, and cryptographically-secure random data generator for Golang

go-random is a fast, clear, and cryptographically-secure random data generator for Golang. It was developed out of the frustration on finding simple ways to write random string and data generator in Golang without having to write complex functions every time.

Why? Security should be baked-in within frameworks for developers. Security should be the easy option.

go-random uses the standard Golang APIs to generate randomness (crypto/rand), with an abstracted API that is clear to use.

Features

• Clear and simple API
• Extremely fast
• Cryptographically-secure (based on crypto/rand) Golang APIs
• Concurrency-safe: You can run millions of go-routines and not have a token collision as the randomness seed is different for each call.

Use-cases for go-random?

You can use go-random for secure-by-default password and token generation for your application.

Installation

go get -u github.com/mazen160/go-random

Usage

Generating Random String

A secure string (token) with the length of 32 characters.

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	data, err := random.String(32)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(data)
}

Output:

> G83zSBEbKeCiV3ij0WcuqR0lIZRJMMc2

Generating Random Bytes

Random bytes with the length of 32 bytes.

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	data, err := random.Bytes(32)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(data)
}

Output:

> [57 63 142 3 148 39 175 87 69 12 178 46 138 42 11 175 93 13 142 0 97 231 132 200 151 143 241 82 235 167 34 33]

Generating Random Integer

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	data, err := random.GetInt(1024)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(data)
}

Output:

> 981

Finding a random integer between 50 to 2000.

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	data, err := random.IntRange(50, 2500)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(data)
}

Output:

> 1527

Selecting a random set of characters from a given character set (charset)

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	charset := "abcde01235"
	length := 20
	data, err := random.Random(length, charset, true)
	if err != nil {
		fmt.Println(err)
	}

	fmt.Println(data)
}

Output:

> 0ee130e152dce0bb5123

Select a random string from a slice of strings

package main

import (
	"fmt"

	"github.com/mazen160/go-random"
)

func main() {
	s := []string{"a", "b", "c", "d", "e", "f"}
	data, err := random.Choice(s)
	if err != nil {
		fmt.Println(err)
	}

	fmt.Println(data)
}

Output:

> d

Use Pre-defined Charsets

go-random has a pre-defined charset:

• Digits Digits: [0-9]
• ASCIILettersLowercase: Asci Lowercase Letters: [a-z]
• ASCIILettersUppercase: Ascii Uppercase Letters: [A-Z]
• Letters: Ascii Letters: [a-zA-Z]
• ASCIICharacters: Ascii Charaters: [a-zA-Z0-9]
• Hexdigits: Hex Digits: [0-9a-fA-F]
• Octdigits: Octal Digits: [0-7]
• Punctuation: Punctuation and special characters.
• Printables: All printables.

To use, you can access it as: random.Letters.

Contribution

Contributions are more than welcome. Please share your ideas by Github issues and pull requests.

Wishlist

• Gopher Logo 🙏
• Reviews and thoughts on changes and improvements?

License

The project is licensed under MIT license.

Author

Mazin Ahmed

• Website: https://mazinahmed.net
• Email: mazin [at] mazinahmed [dot] net
• Twitter: https://twitter.com/mazen160
• Linkedin: http://linkedin.com/in/infosecmazinahmed

Documentation

Index

• Variables
• func Bytes(n int) ([]byte, error)
• func Choice(j []string) (string, error)
• func ChoiceInsecure(j []string) string
• func GetInt(max int) (int, error)
• func GetIntInsecure(i int) int
• func IntRange(min int, max int) (int, error)
• func Random(n int, charset string, isSecure bool) (string, error)
• func String(n int) (string, error)
• func StringInsecure(n int) (string, error)
• func StringRange(min int, max int) (string, error)

Variables

var (
	Digits                string = "0123456789"                                                         // Digits: [0-9]
	ASCIILettersLowercase string = "abcdefghijklmnopqrstuvwxyz"                                         // Asci Lowerrcase Letters: [a-z]
	ASCIILettersUppercase string = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"                                         // Ascii Uppercase Letters: [A-Z]
	Letters               string = ASCIILettersLowercase + ASCIILettersUppercase                        // Ascii Letters: [a-zA-Z]
	ASCIICharacters       string = ASCIILettersLowercase + ASCIILettersUppercase + Digits               // Ascii Charaters: [a-zA-Z0-9]
	Hexdigits             string = "0123456789abcdefABCDEF"                                             // Hex Digits: [0-9a-fA-F]
	Octdigits             string = "01234567"                                                           // Octal Digits: [0-7]
	Punctuation           string = "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"                                 // Punctuation and special characters
	Printables            string = Digits + ASCIILettersLowercase + ASCIILettersUppercase + Punctuation // Printables
)

Functions

func Bytes

func Bytes(n int) ([]byte, error)

Bytes generates a cryptographically secure set of bytes.

func Choice

func Choice(j []string) (string, error)

Choice makes a random choice from a slice of string.

func ChoiceInsecure

func ChoiceInsecure(j []string) string

Choice makes a random choice from a slice of string. Use only when the random choice does not require to be secure.

func GetInt

func GetInt(max int) (int, error)

GetInt generates a cryptographically-secure random Int. Provided max can't be <= 0.

func GetIntInsecure

func GetIntInsecure(i int) int

GetIntInsecure generate a random integer using a seed of current system time.

func IntRange

func IntRange(min int, max int) (int, error)

IntRange returns a random integer between a given range.

func Random

func Random(n int, charset string, isSecure bool) (string, error)

Random is responsible for generating Random data from a given character set.

func String

func String(n int) (string, error)

String generates a cryptographically secure string.

func StringInsecure

func StringInsecure(n int) (string, error)

String generates a cryptographically insecure string. Use only when generating random data that does not require to be secure.

func StringRange

func StringRange(min int, max int) (string, error)

StringRange generates a secure random string within the given range.