crypto/subtle: add XORBytes

Export cipher.xorBytes as subtle.XORBytes, for proposal #53021,
to provide fast XOR to cryptography libraries outside crypto/cipher.

Along with the move, implement the alignment check TODO
in xor_generic.go, so that systems with neither unaligned
accesses nor custom assembly can still XOR a word at a time
in word-based algorithms like GCM. This removes the need
for the separate cipher.xorWords.

Fixes #53021.

Change-Id: I58f80a922f1cff671b5ebc6168eb046e702b5a4c
Reviewed-on: https://go-review.googlesource.com/c/go/+/421435
TryBot-Result: Gopher Robot <[email protected]>
Auto-Submit: Russ Cox <[email protected]>
Run-TryBot: Russ Cox <[email protected]>
Reviewed-by: Alan Donovan <[email protected]>
Reviewed-by: Filippo Valsorda <[email protected]>

Author: rsc

api/next/53021.txt

@@ -0,0 +1 @@
+pkg crypto/subtle, func XORBytes([]uint8, []uint8, []uint8) int #53021

src/crypto/cipher/cbc.go

@@ -11,7 +11,10 @@
 
 package cipher
 
-import "crypto/internal/alias"
+import (
+	"crypto/internal/alias"
+	"crypto/subtle"
+)
 
 type cbc struct {
 	b         Block
@@ -80,7 +83,7 @@ func (x *cbcEncrypter) CryptBlocks(dst, src []byte) {
 
 	for len(src) > 0 {
 		// Write the xor to dst, then encrypt in place.
-		xorBytes(dst[:x.blockSize], src[:x.blockSize], iv)
+		subtle.XORBytes(dst[:x.blockSize], src[:x.blockSize], iv)
 		x.b.Encrypt(dst[:x.blockSize], dst[:x.blockSize])
 
 		// Move to the next block with this block as the next iv.
@@ -162,7 +165,7 @@ func (x *cbcDecrypter) CryptBlocks(dst, src []byte) {
 	// Loop over all but the first block.
 	for start > 0 {
 		x.b.Decrypt(dst[start:end], src[start:end])
-		xorBytes(dst[start:end], dst[start:end], src[prev:start])
+		subtle.XORBytes(dst[start:end], dst[start:end], src[prev:start])
 
 		end = start
 		start = prev
@@ -171,7 +174,7 @@ func (x *cbcDecrypter) CryptBlocks(dst, src []byte) {
 
 	// The first block is special because it uses the saved iv.
 	x.b.Decrypt(dst[start:end], src[start:end])
-	xorBytes(dst[start:end], dst[start:end], x.iv)
+	subtle.XORBytes(dst[start:end], dst[start:end], x.iv)
 
 	// Set the new iv to the first block we copied earlier.
 	x.iv, x.tmp = x.tmp, x.iv

src/crypto/cipher/cfb.go

@@ -6,7 +6,10 @@
 
 package cipher
 
-import "crypto/internal/alias"
+import (
+	"crypto/internal/alias"
+	"crypto/subtle"
+)
 
 type cfb struct {
 	b       Block
@@ -37,7 +40,7 @@ func (x *cfb) XORKeyStream(dst, src []byte) {
 			// able to match CTR/OFB performance.
 			copy(x.next[x.outUsed:], src)
 		}
-		n := xorBytes(dst, src, x.out[x.outUsed:])
+		n := subtle.XORBytes(dst, src, x.out[x.outUsed:])
 		if !x.decrypt {
 			copy(x.next[x.outUsed:], dst)
 		}

src/crypto/cipher/ctr.go

@@ -12,7 +12,10 @@
 
 package cipher
 
-import "crypto/internal/alias"
+import (
+	"crypto/internal/alias"
+	"crypto/subtle"
+)
 
 type ctr struct {
 	b       Block
@@ -83,7 +86,7 @@ func (x *ctr) XORKeyStream(dst, src []byte) {
 		if x.outUsed >= len(x.out)-x.b.BlockSize() {
 			x.refill()
 		}
-		n := xorBytes(dst, src, x.out[x.outUsed:])
+		n := subtle.XORBytes(dst, src, x.out[x.outUsed:])
 		dst = dst[n:]
 		src = src[n:]
 		x.outUsed += n

src/crypto/cipher/export_test.go

@@ -5,6 +5,5 @@
 package cipher
 
 // Export internal functions for testing.
-var XorBytes = xorBytes
 var NewCBCGenericEncrypter = newCBCGenericEncrypter
 var NewCBCGenericDecrypter = newCBCGenericDecrypter

src/crypto/cipher/gcm.go

@@ -373,15 +373,15 @@ func (g *gcm) counterCrypt(out, in []byte, counter *[gcmBlockSize]byte) {
 		g.cipher.Encrypt(mask[:], counter[:])
 		gcmInc32(counter)
 
-		xorWords(out, in, mask[:])
+		subtle.XORBytes(out, in, mask[:])
 		out = out[gcmBlockSize:]
 		in = in[gcmBlockSize:]
 	}
 
 	if len(in) > 0 {
 		g.cipher.Encrypt(mask[:], counter[:])
 		gcmInc32(counter)
-		xorBytes(out, in, mask[:])
+		subtle.XORBytes(out, in, mask[:])
 	}
 }
 
@@ -423,5 +423,5 @@ func (g *gcm) auth(out, ciphertext, additionalData []byte, tagMask *[gcmTagSize]
 	binary.BigEndian.PutUint64(out, y.low)
 	binary.BigEndian.PutUint64(out[8:], y.high)
 
-	xorWords(out, out, tagMask[:])
+	subtle.XORBytes(out, out, tagMask[:])
 }

src/crypto/cipher/ofb.go

@@ -6,7 +6,10 @@
 
 package cipher
 
-import "crypto/internal/alias"
+import (
+	"crypto/internal/alias"
+	"crypto/subtle"
+)
 
 type ofb struct {
 	b       Block
@@ -66,7 +69,7 @@ func (x *ofb) XORKeyStream(dst, src []byte) {
 		if x.outUsed >= len(x.out)-x.b.BlockSize() {
 			x.refill()
 		}
-		n := xorBytes(dst, src, x.out[x.outUsed:])
+		n := subtle.XORBytes(dst, src, x.out[x.outUsed:])
 		dst = dst[n:]
 		src = src[n:]
 		x.outUsed += n