chacha8.go

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package chacha8rand implements a pseudorandom generator
     6  // based on ChaCha8. It is used by both runtime and math/rand/v2
     7  // and must have minimal dependencies.
     8  package chacha8rand
     9  
    10  import (
    11  	"internal/byteorder"
    12  	"internal/cpu"
    13  	"unsafe"
    14  )
    15  
    16  // Offsets into internal/cpu records for use in assembly.
    17  const (
    18  	offsetLOONG64HasLSX = unsafe.Offsetof(cpu.Loong64.HasLSX)
    19  	offsetRISCV64HasV   = unsafe.Offsetof(cpu.RISCV64.HasV)
    20  )
    21  
    22  const (
    23  	ctrInc = 4  // increment counter by 4 between block calls
    24  	ctrMax = 16 // reseed when counter reaches 16
    25  	chunk  = 32 // each chunk produced by block is 32 uint64s
    26  	reseed = 4  // reseed with 4 words
    27  )
    28  
    29  // block is the chacha8rand block function.
    30  func block(seed *[4]uint64, blocks *[32]uint64, counter uint32)
    31  
    32  // A State holds the state for a single random generator.
    33  // It must be used from one goroutine at a time.
    34  // If used by multiple goroutines at a time, the goroutines
    35  // may see the same random values, but the code will not
    36  // crash or cause out-of-bounds memory accesses.
    37  type State struct {
    38  	buf  [32]uint64
    39  	seed [4]uint64
    40  	i    uint32
    41  	n    uint32
    42  	c    uint32
    43  }
    44  
    45  // Next returns the next random value, along with a boolean
    46  // indicating whether one was available.
    47  // If one is not available, the caller should call Refill
    48  // and then repeat the call to Next.
    49  //
    50  // Next is //go:nosplit to allow its use in the runtime
    51  // with per-m data without holding the per-m lock.
    52  //
    53  //go:nosplit
    54  func (s *State) Next() (uint64, bool) {
    55  	i := s.i
    56  	if i >= s.n {
    57  		return 0, false
    58  	}
    59  	s.i = i + 1
    60  	return s.buf[i&31], true // i&31 eliminates bounds check
    61  }
    62  
    63  // Init seeds the State with the given seed value.
    64  func (s *State) Init(seed [32]byte) {
    65  	s.Init64([4]uint64{
    66  		byteorder.LEUint64(seed[0*8:]),
    67  		byteorder.LEUint64(seed[1*8:]),
    68  		byteorder.LEUint64(seed[2*8:]),
    69  		byteorder.LEUint64(seed[3*8:]),
    70  	})
    71  }
    72  
    73  // Init64 seeds the state with the given seed value.
    74  func (s *State) Init64(seed [4]uint64) {
    75  	s.seed = seed
    76  	block(&s.seed, &s.buf, 0)
    77  	s.c = 0
    78  	s.i = 0
    79  	s.n = chunk
    80  }
    81  
    82  // Refill refills the state with more random values.
    83  // After a call to Refill, an immediate call to Next will succeed
    84  // (unless multiple goroutines are incorrectly sharing a state).
    85  func (s *State) Refill() {
    86  	s.c += ctrInc
    87  	if s.c == ctrMax {
    88  		// Reseed with generated uint64s for forward secrecy.
    89  		// Normally this is done immediately after computing a block,
    90  		// but we do it immediately before computing the next block,
    91  		// to allow a much smaller serialized state (just the seed plus offset).
    92  		// This gives a delayed benefit for the forward secrecy
    93  		// (you can reconstruct the recent past given a memory dump),
    94  		// which we deem acceptable in exchange for the reduced size.
    95  		s.seed[0] = s.buf[len(s.buf)-reseed+0]
    96  		s.seed[1] = s.buf[len(s.buf)-reseed+1]
    97  		s.seed[2] = s.buf[len(s.buf)-reseed+2]
    98  		s.seed[3] = s.buf[len(s.buf)-reseed+3]
    99  		s.c = 0
   100  	}
   101  	block(&s.seed, &s.buf, s.c)
   102  	s.i = 0
   103  	s.n = uint32(len(s.buf))
   104  	if s.c == ctrMax-ctrInc {
   105  		s.n = uint32(len(s.buf)) - reseed
   106  	}
   107  }
   108  
   109  // Reseed reseeds the state with new random values.
   110  // After a call to Reseed, any previously returned random values
   111  // have been erased from the memory of the state and cannot be
   112  // recovered.
   113  func (s *State) Reseed() {
   114  	var seed [4]uint64
   115  	for i := range seed {
   116  		for {
   117  			x, ok := s.Next()
   118  			if ok {
   119  				seed[i] = x
   120  				break
   121  			}
   122  			s.Refill()
   123  		}
   124  	}
   125  	s.Init64(seed)
   126  }
   127  
   128  // Marshal marshals the state into a byte slice.
   129  // Marshal and Unmarshal are functions, not methods,
   130  // so that they will not be linked into the runtime
   131  // when it uses the State struct, since the runtime
   132  // does not need these.
   133  func Marshal(s *State) []byte {
   134  	data := make([]byte, 6*8)
   135  	copy(data, "chacha8:")
   136  	used := (s.c/ctrInc)*chunk + s.i
   137  	byteorder.BEPutUint64(data[1*8:], uint64(used))
   138  	for i, seed := range s.seed {
   139  		byteorder.LEPutUint64(data[(2+i)*8:], seed)
   140  	}
   141  	return data
   142  }
   143  
   144  type errUnmarshalChaCha8 struct{}
   145  
   146  func (*errUnmarshalChaCha8) Error() string {
   147  	return "invalid ChaCha8 encoding"
   148  }
   149  
   150  // Unmarshal unmarshals the state from a byte slice.
   151  func Unmarshal(s *State, data []byte) error {
   152  	if len(data) != 6*8 || string(data[:8]) != "chacha8:" {
   153  		return new(errUnmarshalChaCha8)
   154  	}
   155  	used := byteorder.BEUint64(data[1*8:])
   156  	if used > (ctrMax/ctrInc)*chunk-reseed {
   157  		return new(errUnmarshalChaCha8)
   158  	}
   159  	for i := range s.seed {
   160  		s.seed[i] = byteorder.LEUint64(data[(2+i)*8:])
   161  	}
   162  	s.c = ctrInc * (uint32(used) / chunk)
   163  	block(&s.seed, &s.buf, s.c)
   164  	s.i = uint32(used) % chunk
   165  	s.n = chunk
   166  	if s.c == ctrMax-ctrInc {
   167  		s.n = chunk - reseed
   168  	}
   169  	return nil
   170  }
   171
View as plain text