isaac

README

English | 中文

ISAAC

ISAAC is a cryptographically secure pseudorandom number generator (CSPRNG) and stream cipher designed by Robert J. Jenkins Jr. in 1996. This Go implementation provides both 32-bit and 64-bit versions of ISAAC, with a generic implementation that supports both types.

Features

• Pure Go implementation
• Generic implementation supporting both uint32 and uint64 types
• Cryptographically secure
• Fast and efficient
• Thread-safe
• No external dependencies
• Fixed-size array state for better performance

Installation

go get github.com/lbbniu/isaac

Usage

Basic Usage

package main

import (
    "fmt"
    
    "github.com/lbbniu/isaac"
)

func main() {
    // Create a new ISAAC instance with uint32
    rng := isaac.New[uint32]()
    
    // Generate random numbers
    for i := 0; i < 5; i++ {
        fmt.Println(rng.Rand())
    }
}

Using uint64

// Create a new ISAAC instance with uint64
rng := isaac.New[uint64]()

Seeding

// Create a new ISAAC instance
rng := isaac.New[uint32]()

// Seed with a fixed-size array
var seed [isaac.Words]uint32
rng.Seed(seed)

Refilling

// Create a new ISAAC instance
rng := isaac.New[uint32]()

// Get a batch of random numbers
var result [isaac.Words]uint32
rng.Refill(&result)

Implementation Details

The implementation includes:

• Generic implementation in isaac.go with fixed-size array state
• 32-bit specific implementation in isaac32.go
• 64-bit specific implementation in isaac64.go
• Comprehensive test coverage with test vectors from GNU Coreutils

Security

ISAAC is designed to be cryptographically secure. However, please note:

1. Always use a cryptographically secure seed
2. Do not reuse the same seed for different purposes
3. Consider using a more modern CSPRNG for new applications

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References

• ISAAC: a fast cryptographic random number generator
• ISAAC and RC4
• GNU Coreutils ISAAC Test
• GNU Coreutils ISAAC Implementation

Documentation

Overview

Package isaac implements the ISAAC CSPRNG

Index

• Constants
• type ISAAC
  • func New[T uint32 | uint64]() *ISAAC[T]
  • func (s *ISAAC[T]) Rand() T
  • func (s *ISAAC[T]) Refill(r *[Words]T)
  • func (s *ISAAC[T]) Seed(seed [Words]T, initValues ...T)
• type ISAAC32
  • func New32() *ISAAC32
  • func (s *ISAAC32) Rand() uint32
  • func (s *ISAAC32) Refill(r *[Words]uint32)
  • func (s *ISAAC32) Seed(seed [Words]uint32, initValues ...uint32)
• type ISAAC64
  • func New64() *ISAAC64
  • func (s *ISAAC64) Rand() uint64
  • func (s *ISAAC64) Refill(r *[Words]uint64)
  • func (s *ISAAC64) Seed(seed [Words]uint64, initValues ...uint64)
• type UINT32_C
• type UINT64_C

Constants

const (
	// Bits     = 64
	Words    = 1 << 8
	WordsLog = 8
)

Constants aligned with C version

Types

type ISAAC

type ISAAC[T uint32 | uint64] struct {
	// contains filtered or unexported fields
}

ISAAC struct using generic type

func New

func New[T uint32 | uint64]() *ISAAC[T]

New creates a new ISAAC instance

func (*ISAAC[T]) Rand

func (s *ISAAC[T]) Rand() T

Rand returns the next random number

func (*ISAAC[T]) Refill

func (s *ISAAC[T]) Refill(r *[Words]T)

Refill replenishes the random number array

func (*ISAAC[T]) Seed

func (s *ISAAC[T]) Seed(seed [Words]T, initValues ...T)

Seed initializes ISAAC

type ISAAC32

type ISAAC32 struct {
	// contains filtered or unexported fields
}

ISAAC32 struct for 32-bit implementation

func New32

func New32() *ISAAC32

New32 creates a new ISAAC32 instance

func (*ISAAC32) Rand

func (s *ISAAC32) Rand() uint32

Rand returns the next random number

func (*ISAAC32) Refill

func (s *ISAAC32) Refill(r *[Words]uint32)

Refill replenishes the random number array

func (*ISAAC32) Seed

func (s *ISAAC32) Seed(seed [Words]uint32, initValues ...uint32)

Seed initializes ISAAC32 Corresponds to the C isaac_seed function

type ISAAC64

type ISAAC64 struct {
	// contains filtered or unexported fields
}

ISAAC64 struct for 64-bit implementation

func New64

func New64() *ISAAC64

New64 creates a new ISAAC64 instance

func (*ISAAC64) Rand

func (s *ISAAC64) Rand() uint64

Rand returns the next random number

func (*ISAAC64) Refill

func (s *ISAAC64) Refill(r *[Words]uint64)

Refill replenishes the random number array

func (*ISAAC64) Seed

func (s *ISAAC64) Seed(seed [Words]uint64, initValues ...uint64)

Seed initializes ISAAC64 Corresponds to the C isaac_seed function

type UINT32_C

type UINT32_C = uint32

type UINT64_C

type UINT64_C = uint64