Documentation
¶
Overview ¶
Package random provides cryptographically secure random string generation in hex, base32, and base64 encodings.
Index ¶
- Variables
- func Element[T any](s []T) T
- func GenerateBase32EncodedString(ctx context.Context, length int) (string, error)
- func GenerateBase64EncodedString(ctx context.Context, length int) (string, error)
- func GenerateHexEncodedString(ctx context.Context, length int) (string, error)
- func GenerateRawBytes(ctx context.Context, length int) ([]byte, error)
- func MustGenerateHexEncodedString(ctx context.Context, length int) string
- func MustGenerateRawBytes(ctx context.Context, length int) []byte
- func RegisterGenerator(i do.Injector)
- type Generator
- type Option
- type StandardGenerator
- func (g *StandardGenerator) GenerateBase32EncodedString(ctx context.Context, length int) (string, error)
- func (g *StandardGenerator) GenerateBase64EncodedString(ctx context.Context, length int) (string, error)
- func (g *StandardGenerator) GenerateHexEncodedString(ctx context.Context, length int) (string, error)
- func (g *StandardGenerator) GenerateRawBytes(ctx context.Context, length int) ([]byte, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoRandomness = platformerrors.New("generator has no source of randomness")
ErrNoRandomness is returned by a Generator that has no source of randomness to draw from, and is what random/noop answers with for every call.
It exists because the alternative is an empty value and a nil error, which is indistinguishable at the call site from a successful draw. What this interface produces becomes two-factor secrets, salts, session and API tokens, and one-time codes, so a generator that yields the same empty value to every caller — and to every attacker comparing two of them — has to say so in the only channel a caller is obliged to check.
Functions ¶
func Element ¶
func Element[T any](s []T) T
Element fetches a random element from a slice. It returns the zero value of T for an empty slice rather than panicking.
The choice comes from crypto/rand, not math/rand: this package is documented as cryptographically secure, and a caller reaching for it to pick a token, a shard, or a decoy from a slice has every reason to read that promise as covering this function too. crypto/rand.Int cannot fail on any platform Go supports, so the error it returns is discarded rather than widening this signature for a case that does not occur.
func GenerateBase32EncodedString ¶
GenerateBase32EncodedString generates a one-off value with an anonymous Generator.
func GenerateBase64EncodedString ¶
GenerateBase64EncodedString generates a one-off value with an anonymous Generator.
func GenerateHexEncodedString ¶
GenerateHexEncodedString generates a one-off value with an anonymous Generator.
Example ¶
package main
import (
"context"
"fmt"
"github.com/primandproper/platform-go/v10/random"
)
func main() {
s, err := random.GenerateHexEncodedString(context.Background(), 16)
if err != nil {
panic(err)
}
// Output is non-deterministic, but always 32 hex characters (16 bytes * 2)
fmt.Println(len(s))
}
Output: 32
func GenerateRawBytes ¶
GenerateRawBytes generates a one-off value with an anonymous Generator.
Example ¶
package main
import (
"context"
"fmt"
"github.com/primandproper/platform-go/v10/random"
)
func main() {
b, err := random.GenerateRawBytes(context.Background(), 8)
if err != nil {
panic(err)
}
fmt.Println(len(b))
}
Output: 8
func MustGenerateHexEncodedString ¶
MustGenerateHexEncodedString generates a one-off value with an anonymous Generator.
func MustGenerateRawBytes ¶
MustGenerateRawBytes generates a one-off value with an anonymous Generator, but does not return an error.
func RegisterGenerator ¶
RegisterGenerator registers a Generator with the injector.
Types ¶
type Generator ¶
type Generator interface {
GenerateHexEncodedString(ctx context.Context, length int) (string, error)
GenerateBase32EncodedString(context.Context, int) (string, error)
GenerateBase64EncodedString(context.Context, int) (string, error)
GenerateRawBytes(context.Context, int) ([]byte, error)
}
Generator should generate random strings securely.
type Option ¶
type Option func(*options)
Option configures the Generator this package constructs. The zero configuration works: an absent logger logs nowhere and an absent tracer provider traces nowhere.
func WithTracerProvider ¶
WithTracerProvider attaches a tracer provider, enabling spans on every operation.
type StandardGenerator ¶
type StandardGenerator struct {
// contains filtered or unexported fields
}
StandardGenerator is the one Generator implementation, over crypto/rand. It is exported, and returned by NewGenerator, so a caller can depend on the generator it built rather than on the Generator seam.
func NewGenerator ¶
func NewGenerator(opts ...Option) *StandardGenerator
NewGenerator builds a new Generator.
func (*StandardGenerator) GenerateBase32EncodedString ¶
func (g *StandardGenerator) GenerateBase32EncodedString(ctx context.Context, length int) (string, error)
GenerateBase32EncodedString generates a base32-encoded string of a securely random byte array of a given length.
func (*StandardGenerator) GenerateBase64EncodedString ¶
func (g *StandardGenerator) GenerateBase64EncodedString(ctx context.Context, length int) (string, error)
GenerateBase64EncodedString generates a base64-encoded string of a securely random byte array of a given length.
func (*StandardGenerator) GenerateHexEncodedString ¶
func (g *StandardGenerator) GenerateHexEncodedString(ctx context.Context, length int) (string, error)
GenerateHexEncodedString generates a hex-encoded string of a securely random byte array of a given length.
func (*StandardGenerator) GenerateRawBytes ¶
GenerateRawBytes generates a securely random byte array.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package randommock provides moq-generated mock implementations of the random package's interfaces.
|
Package randommock provides moq-generated mock implementations of the random package's interfaces. |
|
Package noop is the random.Generator that has nothing to draw from: every method returns random.ErrNoRandomness and no value.
|
Package noop is the random.Generator that has nothing to draw from: every method returns random.ErrNoRandomness and no value. |