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]>

Author: stevvooe

.github/workflows/test.yml

@@ -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

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,24 @@
 // 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"
+
+	// BLAKE3 is deprecated. Use the symbol "Blake3" instead.
+	BLAKE3 = Blake3
+)
+
 func init() {
-	digest.RegisterAlgorithm(digest.BLAKE3, &blake3hash{})
+	RegisterAlgorithm(Blake3, &blake3hash{})
 }
 
 type blake3hash struct{}

blake3/blake3_test.go

@@ -38,6 +38,9 @@ func TestParseDigest(t *testing.T) {
 			Algorithm: "sha384",
 			Encoded:   "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 		},
+		{
+			Input:     "blake3:af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262",
+			Algorithm: "blake3",
 		{
 			// empty
 			Input: "",

blake3/go.mod

@@ -1,3 +1,5 @@
 module github.com/opencontainers/go-digest
 
 go 1.18
+
+require github.com/zeebo/blake3 v0.2.0

digest_test.go

@@ -37,6 +37,15 @@ func TestDigestVerifier(t *testing.T) {
 	}
 }
 
+func TestDigestBlakeVector(t *testing.T) {
+	// From the BLAKE3 test vectors.
+	testvector := Blake3.FromBytes([]byte{0, 1, 2, 3, 4})
+	expected := "blake3:b40b44dfd97e7a84a996a91af8b85188c66c126940ba7aad2e7ae6b385402aa2"
+	if string(testvector) != expected {
+		t.Fatalf("Expected: %s; Got: %s", expected, testvector)
+	}
+}
+
 // TestVerifierUnsupportedDigest ensures that unsupported digest validation is
 // flowing through verifier creation.
 func TestVerifierUnsupportedDigest(t *testing.T) {