|
| 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 no dependencies. |
| 8 | +package chacha8rand |
| 9 | + |
| 10 | +import "unsafe" |
| 11 | + |
| 12 | +const ( |
| 13 | + ctrInc = 4 // increment counter by 4 between block calls |
| 14 | + ctrMax = 16 // reseed when counter reaches 16 |
| 15 | + chunk = 32 // each chunk produced by block is 32 uint64s |
| 16 | + reseed = 4 // reseed with 4 words |
| 17 | +) |
| 18 | + |
| 19 | +// block is the chacha8rand block function. |
| 20 | +func block(seed *[4]uint64, blocks *[32]uint64, counter uint32) |
| 21 | + |
| 22 | +// A State holds the state for a single random generator. |
| 23 | +// It must be used from one goroutine at a time. |
| 24 | +// If used by multiple goroutines at a time, the goroutines |
| 25 | +// may see the same random values, but the code will not |
| 26 | +// crash or cause out-of-bounds memory accesses. |
| 27 | +type State struct { |
| 28 | + buf [32]uint64 |
| 29 | + seed [4]uint64 |
| 30 | + i uint32 |
| 31 | + n uint32 |
| 32 | + c uint32 |
| 33 | +} |
| 34 | + |
| 35 | +// Next returns the next random value, along with a boolean |
| 36 | +// indicating whether one was available. |
| 37 | +// If one is not available, the caller should call Refill |
| 38 | +// and then repeat the call to Next. |
| 39 | +// |
| 40 | +// Next is //go:nosplit to allow its use in the runtime |
| 41 | +// with per-m data without holding the per-m lock. |
| 42 | +//go:nosplit |
| 43 | +func (s *State) Next() (uint64, bool) { |
| 44 | + i := s.i |
| 45 | + if i >= s.n { |
| 46 | + return 0, false |
| 47 | + } |
| 48 | + s.i = i + 1 |
| 49 | + return s.buf[i&31], true // i&31 eliminates bounds check |
| 50 | +} |
| 51 | + |
| 52 | +// Init seeds the State with the given seed value. |
| 53 | +func (s *State) Init(seed [32]byte) { |
| 54 | + s.Init64(*(*[4]uint64)(unsafe.Pointer(&seed))) |
| 55 | +} |
| 56 | + |
| 57 | +// Init64 seeds the state with the given seed value. |
| 58 | +func (s *State) Init64(seed [4]uint64) { |
| 59 | + s.seed = seed |
| 60 | + block(&s.seed, &s.buf, 0) |
| 61 | + s.c = 0 |
| 62 | + s.i = 0 |
| 63 | + s.n = chunk |
| 64 | +} |
| 65 | + |
| 66 | +// Refill refills the state with more random values. |
| 67 | +// After a call to Refill, an immediate call to Next will succeed |
| 68 | +// (unless multiple goroutines are incorrectly sharing a state). |
| 69 | +func (s *State) Refill() { |
| 70 | + s.c += ctrInc |
| 71 | + if s.c == ctrMax { |
| 72 | + // Reseed with generated uint64s for forward secrecy. |
| 73 | + // Normally this is done immediately after computing a block, |
| 74 | + // but we do it immediately before computing the next block, |
| 75 | + // to allow a much smaller serialized state (just the seed plus offset). |
| 76 | + // This gives a delayed benefit for the forward secrecy |
| 77 | + // (you can reconstruct the recent past given a memory dump), |
| 78 | + // which we deem acceptable in exchange for the reduced size. |
| 79 | + s.seed[0] = s.buf[len(s.buf)-reseed+0] |
| 80 | + s.seed[1] = s.buf[len(s.buf)-reseed+1] |
| 81 | + s.seed[2] = s.buf[len(s.buf)-reseed+2] |
| 82 | + s.seed[3] = s.buf[len(s.buf)-reseed+3] |
| 83 | + s.c = 0 |
| 84 | + } |
| 85 | + block(&s.seed, &s.buf, s.c) |
| 86 | + s.i = 0 |
| 87 | + s.n = uint32(len(s.buf)) |
| 88 | + if s.c == ctrMax-ctrInc { |
| 89 | + s.n = uint32(len(s.buf)) - reseed |
| 90 | + } |
| 91 | +} |
| 92 | + |
| 93 | +// Marshal marshals the state into a byte slice. |
| 94 | +// Marshal and Unmarshal are functions, not methods, |
| 95 | +// so that they will not be linked into the runtime |
| 96 | +// when it uses the State struct, since the runtime |
| 97 | +// does not need these. |
| 98 | +func Marshal(s *State) []byte { |
| 99 | + data := make([]byte, 6*8) |
| 100 | + copy(data, "chacha8:") |
| 101 | + used := (s.c/ctrInc)*chunk + s.i |
| 102 | + bePutUint64(data[1*8:], uint64(used)) |
| 103 | + for i, seed := range s.seed { |
| 104 | + lePutUint64(data[(2+i)*8:], seed) |
| 105 | + } |
| 106 | + return data |
| 107 | +} |
| 108 | + |
| 109 | +type errUnmarshalChaCha8 struct{} |
| 110 | + |
| 111 | +func (*errUnmarshalChaCha8) Error() string { |
| 112 | + return "invalid ChaCha8 encoding" |
| 113 | +} |
| 114 | + |
| 115 | +// Unmarshal unmarshals the state from a byte slice. |
| 116 | +func Unmarshal(s *State, data []byte) error { |
| 117 | + if len(data) != 6*8 || string(data[:8]) != "chacha8:" { |
| 118 | + return new(errUnmarshalChaCha8) |
| 119 | + } |
| 120 | + used := beUint64(data[1*8:]) |
| 121 | + if used > (ctrMax/ctrInc)*chunk-reseed { |
| 122 | + return new(errUnmarshalChaCha8) |
| 123 | + } |
| 124 | + for i := range s.seed { |
| 125 | + s.seed[i] = leUint64(data[(2+i)*8:]) |
| 126 | + } |
| 127 | + s.c = ctrInc * (uint32(used) / chunk) |
| 128 | + block(&s.seed, &s.buf, s.c) |
| 129 | + s.i = uint32(used) % chunk |
| 130 | + s.n = chunk |
| 131 | + if s.c == ctrMax-ctrInc { |
| 132 | + s.n = chunk - reseed |
| 133 | + } |
| 134 | + return nil |
| 135 | +} |
| 136 | + |
| 137 | +// binary.bigEndian.Uint64, copied to avoid dependency |
| 138 | +func beUint64(b []byte) uint64 { |
| 139 | + _ = b[7] // bounds check hint to compiler; see golang.org/issue/14808 |
| 140 | + return uint64(b[7]) | uint64(b[6])<<8 | uint64(b[5])<<16 | uint64(b[4])<<24 | |
| 141 | + uint64(b[3])<<32 | uint64(b[2])<<40 | uint64(b[1])<<48 | uint64(b[0])<<56 |
| 142 | +} |
| 143 | + |
| 144 | +// binary.bigEndian.PutUint64, copied to avoid dependency |
| 145 | +func bePutUint64(b []byte, v uint64) { |
| 146 | + _ = b[7] // early bounds check to guarantee safety of writes below |
| 147 | + b[0] = byte(v >> 56) |
| 148 | + b[1] = byte(v >> 48) |
| 149 | + b[2] = byte(v >> 40) |
| 150 | + b[3] = byte(v >> 32) |
| 151 | + b[4] = byte(v >> 24) |
| 152 | + b[5] = byte(v >> 16) |
| 153 | + b[6] = byte(v >> 8) |
| 154 | + b[7] = byte(v) |
| 155 | +} |
| 156 | + |
| 157 | +// binary.littleEndian.Uint64, copied to avoid dependency |
| 158 | +func leUint64(b []byte) uint64 { |
| 159 | + _ = b[7] // bounds check hint to compiler; see golang.org/issue/14808 |
| 160 | + return uint64(b[0]) | uint64(b[1])<<8 | uint64(b[2])<<16 | uint64(b[3])<<24 | |
| 161 | + uint64(b[4])<<32 | uint64(b[5])<<40 | uint64(b[6])<<48 | uint64(b[7])<<56 |
| 162 | +} |
| 163 | + |
| 164 | +// binary.littleEndian.PutUint64, copied to avoid dependency |
| 165 | +func lePutUint64(b []byte, v uint64) { |
| 166 | + _ = b[7] // early bounds check to guarantee safety of writes below |
| 167 | + b[0] = byte(v) |
| 168 | + b[1] = byte(v >> 8) |
| 169 | + b[2] = byte(v >> 16) |
| 170 | + b[3] = byte(v >> 24) |
| 171 | + b[4] = byte(v >> 32) |
| 172 | + b[5] = byte(v >> 40) |
| 173 | + b[6] = byte(v >> 48) |
| 174 | + b[7] = byte(v >> 56) |
| 175 | +} |
0 commit comments