Blake3 (#1)

* digest: promote blake3 to first-class digest

The dual module approach for blake3 was slightly awkward. Since it
provides similar usability with a massive bump in performance, it's
extremely likely to land as a registered algorithm in the image-spec.

This PR removes the secondary module, which made it difficult to test as
a unit. This may break users who are using HEAD versions of the package.
For a new release, this will be backwards compatible. The other drawback
is that the zeebo/blake3 will now be a dependency but this can be
replaced transparently by the standard libary in the future.

In addition to promoting blake3, this makes a few style adjustments to
be in line with Go's style guidelines.

Signed-off-by: Stephen Day <[email protected]>

* fix: update stevvooe's blake3 PR

opencontainers#66
opencontainers/image-spec#1240
Signed-off-by: Ramkumar Chinchani <[email protected]>

* fix: add a length test for blake3

Signed-off-by: Ramkumar Chinchani <[email protected]>

* fix: add a Makefile

make
make build
make test

Signed-off-by: Ramkumar Chinchani <[email protected]>

* fix: merge conflicts

Signed-off-by: Ramkumar Chinchani <[email protected]>

* fix: blake3 pulls in golang 1.22.x dep

2025-04-25T19:33:20.2495501Z go: downloading github.com/zeebo/blake3 v0.2.4
2025-04-25T19:33:20.3154128Z go: downloading github.com/klauspost/cpuid/v2 v2.2.10
2025-04-25T19:33:20.3959610Z github.com/klauspost/cpuid/v2: cannot compile Go 1.22 code
2025-04-25T19:33:21.1059807Z FAIL github.com/opencontainers/go-digest [build failed]
2025-04-25T19:33:21.1060449Z FAIL github.com/opencontainers/go-digest/digestset [build failed]
2025-04-25T19:33:21.1219422Z ##[error]Process completed with exit code 1.
Signed-off-by: Ramkumar Chinchani <[email protected]>

---------

Signed-off-by: Stephen Day <[email protected]>
Signed-off-by: Ramkumar Chinchani <[email protected]>
Co-authored-by: Stephen Day <[email protected]>

Author: rchincha

.github/workflows/test.yml

@@ -4,7 +4,7 @@ jobs:
   test:
     strategy:
       matrix:
-        go-version: [1.18.x, 1.19.x, 1.20.x, 1.21.x, 1.22.x]
+        go-version: [1.22.x, 1.23.x, 1.24.x]
         platform: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
@@ -16,6 +16,3 @@ jobs:
         uses: actions/checkout@v4
       - name: Test
         run: go test -v ./...
-      - name: Test Blake3
-        run: go test -v ./...
-        working-directory: blake3

Makefile

@@ -0,0 +1,9 @@
+.PHONY: all build test
+
+all: build test
+
+build:
+	go build -v ./...
+
+test:
+	go test -v -cover -race ./...

algorithm.go

@@ -103,14 +103,16 @@ const (
 
 var algorithmRegexp = regexp.MustCompile(`^[a-z0-9]+([+._-][a-z0-9]+)*$`)
 
-// CryptoHash is the interface that any hash algorithm must implement
+// CryptoHash is the interface that any digest algorithm must implement
 type CryptoHash interface {
-	// Available reports whether the given hash function is usable in the current binary.
+	// Available reports whether the given hash function is usable in the
+	// current binary.
 	Available() bool
-	// Size returns the length, in bytes, of a digest resulting from the given hash function.
+	// Size returns the length, in bytes, of a digest resulting from the given
+	// hash function.
 	Size() int
-	// New returns a new hash.Hash calculating the given hash function. If the hash function is not
-	// available, it may panic.
+	// New returns a new hash.Hash calculating the given hash function. If the
+	// hash function is not available, it may panic.
 	New() hash.Hash
 }
 
@@ -129,14 +131,16 @@ var (
 	algorithmsLock sync.RWMutex
 )
 
-// RegisterAlgorithm may be called to dynamically register an algorithm. The implementation is a CryptoHash, and
-// the regex is meant to match the hash portion of the algorithm. If a duplicate algorithm is already registered,
-// the return value is false, otherwise if registration was successful the return value is true.
+// RegisterAlgorithm may be called to dynamically register an algorithm. The
+// implementation is a CryptoHash, and the regex is meant to match the hash
+// portion of the algorithm. If a duplicate algorithm is already registered, the
+// return value is false, otherwise if registration was successful the return
+// value is true.
 //
 // The algorithm encoding format must be based on hex.
 //
-// The algorithm name must be conformant to the BNF specification in the OCI image-spec, otherwise the function
-// will panic.
+// The algorithm name must be conformant to the BNF specification in the OCI
+// image-spec, otherwise the function will panic.
 func RegisterAlgorithm(algorithm Algorithm, implementation CryptoHash) bool {
 	algorithmsLock.Lock()
 	defer algorithmsLock.Unlock()
@@ -150,8 +154,10 @@ func RegisterAlgorithm(algorithm Algorithm, implementation CryptoHash) bool {
 	}
 
 	algorithms[algorithm] = implementation
-	// We can do this since the Digest function below only implements a hex digest. If we open this in the future
-	// we need to allow for alternative digest algorithms to be implemented and for the user to pass their own
+
+	// We can do this since the Digest function below only implements a hex
+	// digest. If we open this in the future we need to allow for alternative
+	// digest algorithms to be implemented and for the user to pass their own
 	// custom regexp.
 	anchoredEncodedRegexps[algorithm] = hexDigestRegex(implementation)
 	return true

blake3/blake3.go renamed to blake3.go

@@ -11,18 +11,21 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-
-package blake3
+package digest
 
 import (
 	"hash"
 
-	"github.com/opencontainers/go-digest"
 	"github.com/zeebo/blake3"
 )
 
+const (
+	// Blake3 is the blake3 algorithm with the default 256-bit output size
+	Blake3 Algorithm = "blake3"
+)
+
 func init() {
-	digest.RegisterAlgorithm(digest.BLAKE3, &blake3hash{})
+	RegisterAlgorithm(Blake3, &blake3hash{})
 }
 
 type blake3hash struct{}

blake3/blake3_test.go

@@ -38,6 +38,11 @@ func TestParseDigest(t *testing.T) {
 			Algorithm: "sha384",
 			Encoded:   "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 		},
+		{
+			Input:     "blake3:af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+			Algorithm: "blake3",
+			Encoded:   "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+		},
 		{
 			// empty
 			Input: "",
@@ -83,6 +88,11 @@ func TestParseDigest(t *testing.T) {
 			Input: "sha512:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
 			Err:   digest.ErrDigestInvalidLength,
 		},
+		{
+			// too short (from different algorithm)
+			Input: "blake3:abcdef0123456789abcdef0123456789abcdef01234",
+			Err:   digest.ErrDigestInvalidLength,
+		},
 		{
 			Input: "foo:d41d8cd98f00b204e9800998ecf8427e",
 			Err:   digest.ErrDigestUnsupported,

blake3/go.mod

@@ -1,3 +1,10 @@
 module github.com/opencontainers/go-digest
 
-go 1.18
+go 1.22
+
+require github.com/zeebo/blake3 v0.2.4
+
+require (
+	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
+	golang.org/x/sys v0.32.0 // indirect
+)

blake3/go.sum

@@ -0,0 +1,10 @@
+github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
+github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/zeebo/assert v1.1.0 h1:hU1L1vLTHsnO8x8c9KAR5GmM5QscxHg5RNU5z5qbUWY=
+github.com/zeebo/assert v1.1.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+github.com/zeebo/blake3 v0.2.4 h1:KYQPkhpRtcqh0ssGYcKLG1JYvddkEA8QwCM/yBqhaZI=
+github.com/zeebo/blake3 v0.2.4/go.mod h1:7eeQ6d2iXWRGF6npfaxl2CU+xy2Fjo2gxeyZGCRUjcE=
+github.com/zeebo/pcg v1.0.1 h1:lyqfGeWiv4ahac6ttHs+I5hwtH/+1mrhlCtVNQM2kHo=
+github.com/zeebo/pcg v1.0.1/go.mod h1:09F0S9iiKrwn9rlI5yjLkmrug154/YRW6KnnXVDM/l4=
+golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20=
+golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=