// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-//go:build gc && !purego && ignore
+//go:build !purego
package sha3
+import (
+ "crypto/internal/fips/subtle"
+ "internal/cpu"
+)
+
// This file contains code for using the 'compute intermediate
// message digest' (KIMD) and 'compute last message digest' (KLMD)
-// instructions to compute SHA-3 and SHAKE hashes on IBM Z.
+// instructions to compute SHA-3 and SHAKE hashes on IBM Z. See
+// [z/Architecture Principles of Operation, Fourteen Edition].
+//
+// [z/Architecture Principles of Operation, Fourteen Edition]: https://www.ibm.com/docs/en/module_1678991624569/pdf/SA22-7832-13.pdf
-import "internal/cpu"
+func keccakF1600(a *[200]byte) {
+ keccakF1600Generic(a)
+}
// codes represent 7-bit KIMD/KLMD function codes as defined in
// the Principles of Operation.
type code uint64
const (
- // function codes for KIMD/KLMD
+ // Function codes for KIMD/KLMD, from Figure 7-207.
sha3_224 code = 32
- sha3_256 = 33
- sha3_384 = 34
- sha3_512 = 35
- shake_128 = 36
- shake_256 = 37
+ sha3_256 code = 33
+ sha3_384 code = 34
+ sha3_512 code = 35
+ shake_128 code = 36
+ shake_256 code = 37
nopad = 0x100
)
// kimd is a wrapper for the 'compute intermediate message digest' instruction.
-// src must be a multiple of the rate for the given function code.
+// src is absorbed into the sponge state a.
+// len(src) must be a multiple of the rate for the given function code.
//
//go:noescape
-func kimd(function code, chain *[200]byte, src []byte)
+func kimd(function code, a *[200]byte, src []byte)
// klmd is a wrapper for the 'compute last message digest' instruction.
-// src padding is handled by the instruction.
+// src is padded and absorbed into the sponge state a.
+//
+// If the function is a SHAKE XOF, the sponge is then optionally squeezed into
+// dst by first applying the permutation and then copying the output until dst
+// runs out. If len(dst) is a multiple of rate (including zero), the final
+// permutation is not applied. If the nopad bit of function is set and len(src)
+// is zero, only squeezing is performed.
//
//go:noescape
-func klmd(function code, chain *[200]byte, dst, src []byte)
-
-type asmState struct {
- a [200]byte // 1600 bit state
- buf []byte // care must be taken to ensure cap(buf) is a multiple of rate
- rate int // equivalent to block size
- storage [3072]byte // underlying storage for buf
- outputLen int // output length for full security
- function code // KIMD/KLMD function code
- state spongeDirection // whether the sponge is absorbing or squeezing
-}
-
-func newAsmState(function code) *asmState {
- var s asmState
- s.function = function
- switch function {
- case sha3_224:
- s.rate = 144
- s.outputLen = 28
- case sha3_256:
- s.rate = 136
- s.outputLen = 32
- case sha3_384:
- s.rate = 104
- s.outputLen = 48
- case sha3_512:
- s.rate = 72
- s.outputLen = 64
- case shake_128:
- s.rate = 168
- s.outputLen = 32
- case shake_256:
- s.rate = 136
- s.outputLen = 64
- default:
- panic("sha3: unrecognized function code")
- }
-
- // limit s.buf size to a multiple of s.rate
- s.resetBuf()
- return &s
-}
-
-func (s *asmState) clone() *asmState {
- c := *s
- c.buf = c.storage[:len(s.buf):cap(s.buf)]
- return &c
-}
+func klmd(function code, a *[200]byte, dst, src []byte)
-// copyIntoBuf copies b into buf. It will panic if there is not enough space to
-// store all of b.
-func (s *asmState) copyIntoBuf(b []byte) {
- bufLen := len(s.buf)
- s.buf = s.buf[:len(s.buf)+len(b)]
- copy(s.buf[bufLen:], b)
-}
-
-// resetBuf points buf at storage, sets the length to 0 and sets cap to be a
-// multiple of the rate.
-func (s *asmState) resetBuf() {
- max := (cap(s.storage) / s.rate) * s.rate
- s.buf = s.storage[:0:max]
-}
-
-// Write (via the embedded io.Writer interface) adds more data to the running hash.
-// It never returns an error.
-func (s *asmState) Write(b []byte) (int, error) {
- if s.state != spongeAbsorbing {
+func (d *Digest) write(p []byte) (n int, err error) {
+ if d.state != spongeAbsorbing {
panic("sha3: Write after Read")
}
- length := len(b)
- for len(b) > 0 {
- if len(s.buf) == 0 && len(b) >= cap(s.buf) {
- // Hash the data directly and push any remaining bytes
- // into the buffer.
- remainder := len(b) % s.rate
- kimd(s.function, &s.a, b[:len(b)-remainder])
- if remainder != 0 {
- s.copyIntoBuf(b[len(b)-remainder:])
- }
- return length, nil
- }
+ if !cpu.S390X.HasSHA3 {
+ return d.writeGeneric(p)
+ }
- if len(s.buf) == cap(s.buf) {
- // flush the buffer
- kimd(s.function, &s.a, s.buf)
- s.buf = s.buf[:0]
- }
+ n = len(p)
- // copy as much as we can into the buffer
- n := len(b)
- if len(b) > cap(s.buf)-len(s.buf) {
- n = cap(s.buf) - len(s.buf)
- }
- s.copyIntoBuf(b[:n])
- b = b[n:]
+ // If there is buffered input in the state, keep XOR'ing.
+ if d.n > 0 {
+ x := subtle.XORBytes(d.a[d.n:d.rate], d.a[d.n:d.rate], p)
+ d.n += x
+ p = p[x:]
}
- return length, nil
-}
-// Read squeezes an arbitrary number of bytes from the sponge.
-func (s *asmState) Read(out []byte) (n int, err error) {
- // The 'compute last message digest' instruction only stores the digest
- // at the first operand (dst) for SHAKE functions.
- if s.function != shake_128 && s.function != shake_256 {
- panic("sha3: can only call Read for SHAKE functions")
+ // If the sponge is full, apply the permutation.
+ if d.n == d.rate {
+ // Absorbing a "rate"ful of zeroes effectively XORs the state with
+ // zeroes (a no-op) and then runs the permutation. The actual function
+ // doesn't matter, they all run the same permutation.
+ kimd(shake_128, &d.a, make([]byte, rateK256))
+ d.n = 0
}
- n = len(out)
-
- // need to pad if we were absorbing
- if s.state == spongeAbsorbing {
- s.state = spongeSqueezing
-
- // write hash directly into out if possible
- if len(out)%s.rate == 0 {
- klmd(s.function, &s.a, out, s.buf) // len(out) may be 0
- s.buf = s.buf[:0]
- return
- }
-
- // write hash into buffer
- max := cap(s.buf)
- if max > len(out) {
- max = (len(out)/s.rate)*s.rate + s.rate
- }
- klmd(s.function, &s.a, s.buf[:max], s.buf)
- s.buf = s.buf[:max]
+ // Absorb full blocks with KIMD.
+ if len(p) >= d.rate {
+ wholeBlocks := len(p) / d.rate * d.rate
+ kimd(d.function(), &d.a, p[:wholeBlocks])
+ p = p[wholeBlocks:]
}
- for len(out) > 0 {
- // flush the buffer
- if len(s.buf) != 0 {
- c := copy(out, s.buf)
- out = out[c:]
- s.buf = s.buf[c:]
- continue
- }
-
- // write hash directly into out if possible
- if len(out)%s.rate == 0 {
- klmd(s.function|nopad, &s.a, out, nil)
- return
- }
-
- // write hash into buffer
- s.resetBuf()
- if cap(s.buf) > len(out) {
- s.buf = s.buf[:(len(out)/s.rate)*s.rate+s.rate]
- }
- klmd(s.function|nopad, &s.a, s.buf, nil)
+ // If there is any trailing input, XOR it into the state.
+ if len(p) > 0 {
+ d.n += subtle.XORBytes(d.a[d.n:d.rate], d.a[d.n:d.rate], p)
}
+
return
}
-// Sum appends the current hash to b and returns the resulting slice.
-// It does not change the underlying hash state.
-func (s *asmState) Sum(b []byte) []byte {
- if s.state != spongeAbsorbing {
+func (d *Digest) sum(b []byte) []byte {
+ if d.state != spongeAbsorbing {
panic("sha3: Sum after Read")
}
+ if !cpu.S390X.HasSHA3 ||
+ d.dsbyte != dsbyteSHA3 && d.dsbyte != dsbyteShake {
+ return d.sumGeneric(b)
+ }
// Copy the state to preserve the original.
- a := s.a
+ a := d.a
- // Hash the buffer. Note that we don't clear it because we
- // aren't updating the state.
- switch s.function {
+ // We "absorb" a buffer of zeroes as long as the amount of input we already
+ // XOR'd into the sponge, to skip over it. The max cap is specified to avoid
+ // an allocation.
+ buf := make([]byte, d.n, rateK256)
+ function := d.function()
+ switch function {
case sha3_224, sha3_256, sha3_384, sha3_512:
- klmd(s.function, &a, nil, s.buf)
- return append(b, a[:s.outputLen]...)
+ klmd(function, &a, nil, buf)
+ return append(b, a[:d.outputLen]...)
case shake_128, shake_256:
- d := make([]byte, s.outputLen, 64)
- klmd(s.function, &a, d, s.buf)
- return append(b, d[:s.outputLen]...)
+ h := make([]byte, d.outputLen, 64)
+ klmd(function, &a, h, buf)
+ return append(b, h...)
default:
panic("sha3: unknown function")
}
}
-// Reset resets the Hash to its initial state.
-func (s *asmState) Reset() {
- for i := range s.a {
- s.a[i] = 0
+func (d *Digest) read(out []byte) (n int, err error) {
+ if !cpu.S390X.HasSHA3 || d.dsbyte != dsbyteShake {
+ return d.readGeneric(out)
}
- s.resetBuf()
- s.state = spongeAbsorbing
-}
-
-// Size returns the number of bytes Sum will return.
-func (s *asmState) Size() int {
- return s.outputLen
-}
-
-// BlockSize returns the hash's underlying block size.
-// The Write method must be able to accept any amount
-// of data, but it may operate more efficiently if all writes
-// are a multiple of the block size.
-func (s *asmState) BlockSize() int {
- return s.rate
-}
-
-// Clone returns a copy of the ShakeHash in its current state.
-func (s *asmState) Clone() ShakeHash {
- return s.clone()
-}
-// new224 returns an assembly implementation of SHA3-224 if available,
-// otherwise it returns a generic implementation.
-func new224() *Digest {
- if cpu.S390X.HasSHA3 {
- return newAsmState(sha3_224)
- }
- return new224Generic()
-}
+ n = len(out)
-// new256 returns an assembly implementation of SHA3-256 if available,
-// otherwise it returns a generic implementation.
-func new256() *Digest {
- if cpu.S390X.HasSHA3 {
- return newAsmState(sha3_256)
- }
- return new256Generic()
-}
+ if d.state == spongeAbsorbing {
+ d.state = spongeSqueezing
+
+ // We "absorb" a buffer of zeroes as long as the amount of input we
+ // already XOR'd into the sponge, to skip over it. The max cap is
+ // specified to avoid an allocation.
+ buf := make([]byte, d.n, rateK256)
+ klmd(d.function(), &d.a, out, buf)
+ } else {
+ // We have "buffered" output still to copy.
+ if d.n < d.rate {
+ x := copy(out, d.a[d.n:d.rate])
+ d.n += x
+ out = out[x:]
+ }
+ if len(out) == 0 {
+ return
+ }
-// new384 returns an assembly implementation of SHA3-384 if available,
-// otherwise it returns a generic implementation.
-func new384() *Digest {
- if cpu.S390X.HasSHA3 {
- return newAsmState(sha3_384)
+ klmd(d.function()|nopad, &d.a, out, nil)
}
- return new384Generic()
-}
-// new512 returns an assembly implementation of SHA3-512 if available,
-// otherwise it returns a generic implementation.
-func new512() *Digest {
- if cpu.S390X.HasSHA3 {
- return newAsmState(sha3_512)
+ if len(out)%d.rate == 0 {
+ // The final permutation was not performed,
+ // so there is no "buffered" output.
+ d.n = d.rate
+ } else {
+ d.n = len(out) % d.rate
}
- return new512Generic()
-}
-// newShake128 returns an assembly implementation of SHAKE-128 if available,
-// otherwise it returns a generic implementation.
-func newShake128() ShakeHash {
- if cpu.S390X.HasSHA3 {
- return newAsmState(shake_128)
- }
- return newShake128Generic()
+ return
}
-// newShake256 returns an assembly implementation of SHAKE-256 if available,
-// otherwise it returns a generic implementation.
-func newShake256() ShakeHash {
- if cpu.S390X.HasSHA3 {
- return newAsmState(shake_256)
+func (d *Digest) function() code {
+ switch d.rate {
+ case rateK256:
+ return shake_128
+ case rateK448:
+ return sha3_224
+ case rateK512:
+ if d.dsbyte == dsbyteSHA3 {
+ return sha3_256
+ } else {
+ return shake_256
+ }
+ case rateK768:
+ return sha3_384
+ case rateK1024:
+ return sha3_512
+ default:
+ panic("invalid rate")
}
- return newShake256Generic()
}