digest

digest — go-ruby-digest

A pure-Go (no cgo) reimplementation of Ruby's Digest standard library — the deterministic, interpreter-independent message-digest core of MRI 4.0.5's digest, digest/md5, digest/sha1, digest/sha2, digest/rmd160 and digest/bubblebabble. It computes Digest::MD5 / SHA1 / SHA256 / SHA384 / SHA512 / RMD160 and the Digest.bubblebabble encoding byte-for-byte identical to MRI, with no Ruby runtime and no cgo.

It is the digest backend for go-embedded-ruby, but is a standalone, reusable module — a sibling of go-ruby-regexp (the Onigmo engine), go-ruby-erb (the ERB compiler) and go-ruby-yaml (the Psych emitter/loader).

What it is — and isn't. A message digest is pure computation over bytes, so it lives here as pure Go over crypto/* and golang.org/x/crypto/ripemd160. Binding the algorithms into Ruby classes (Digest::SHA256, the #update / #hexdigest protocol, == against a hex string) is the host's job; this library hands back a small, idiomatic Go Digest interface plus one-shot helpers the host maps onto MRI's surface.

Features

Faithful port of MRI's Digest, validated against the ruby binary on every supported platform:

• Six algorithms — MD5, SHA1, SHA256, SHA384, SHA512, RMD160 (RIPEMD-160), each with its correct block and digest lengths.
• Incremental protocol — Update / Reset / Finish / HexFinish / Base64Finish mirror Digest::Instance#update / #<< / #reset / #digest / #hexdigest / #base64digest.
• Class one-shots — Sum / HexSum / Base64Sum are Digest::ALGO.digest / .hexdigest / .base64digest; SumFile / HexSumFile / Base64SumFile are Digest::ALGO.file(path).
• Bubble Babble — BubbleBabble is Digest.bubblebabble (the Antti Huima pronounceable encoding); SumBubbleBabble is Digest::ALGO.bubblebabble (bubble-babble of the algorithm's digest), matching MRI's digest/bubblebabble.
• Name factory — New("SHA256") is the Digest(name) factory, case- and dash-insensitive ("sha-256"), with RIPEMD160 aliased to RMD160.

CGO-free, 100% test coverage, gofmt + go vet clean, and green across the six 64-bit Go targets (amd64, arm64, riscv64, loong64, ppc64le, s390x).

Install

go get github.com/go-ruby-digest/digest

Usage

package main

import (
	"fmt"

	"github.com/go-ruby-digest/digest"
)

func main() {
	// One-shot: Digest::SHA256.hexdigest("abc")
	hx, _ := digest.HexSum("SHA256", []byte("abc"))
	fmt.Println(hx) // ba7816bf...20015ad

	// Incremental: Digest::SHA1.new; d.update("a"); d << "bc"; d.hexdigest
	d := digest.SHA1()
	d.Update([]byte("a"))
	d.Update([]byte("bc"))
	fmt.Println(d.HexFinish()) // a9993e36...7850c26c9cd0d89d

	// Digest.bubblebabble("Pineapple")
	fmt.Println(digest.BubbleBabble([]byte("Pineapple"))) // xigak-nyryk-humil-bosek-sonax
}

API

// Digest is the incremental Digest::Instance protocol.
type Digest interface {
	Update(data []byte)    // #update / #<<
	Reset()                // #reset
	Finish() []byte        // #digest
	HexFinish() string     // #hexdigest
	Base64Finish() string  // #base64digest
	BlockLength() int      // #block_length
	DigestLength() int     // #digest_length / #length / #size
}

// New is the Digest(name) factory; the direct constructors are the named classes.
func New(name string) (Digest, error)
func MD5() Digest
func SHA1() Digest
func SHA256() Digest
func SHA384() Digest
func SHA512() Digest
func RMD160() Digest

// Class one-shots: Digest::ALGO.digest / .hexdigest / .base64digest.
func Sum(name string, data []byte) ([]byte, error)
func HexSum(name string, data []byte) (string, error)
func Base64Sum(name string, data []byte) (string, error)

// File one-shots: Digest::ALGO.file(path).{digest,hexdigest,base64digest}.
func SumFile(name, path string) ([]byte, error)
func HexSumFile(name, path string) (string, error)
func Base64SumFile(name, path string) (string, error)

// Bubble Babble: Digest.bubblebabble and Digest::ALGO.bubblebabble.
func BubbleBabble(data []byte) string
func SumBubbleBabble(name string, data []byte) (string, error)

Algorithm table

Tests & coverage

The suite pairs deterministic, ruby-free tests (which alone hold coverage at 100%, so the qemu cross-arch and Windows lanes pass the gate) with a differential MRI oracle: a corpus is hashed here and by the system ruby (Digest::ALGO.hexdigest / .base64digest / .digest / .bubblebabble / .file, the incremental update/<< path, and SHA2.new(bitlen)), and the outputs must match byte-for-byte. The oracle scripts $stdout.binmode / $stdin.binmode so Windows text-mode never pollutes the bytes, gate on MRI >= 4.0, and skip themselves where ruby is absent; the .file test uses t.TempDir() + filepath.ToSlash so no OS path is embedded in Ruby source.

COVERPKG=$(go list ./... | paste -sd, -)
go test -race -coverpkg="$COVERPKG" -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1   # 100.0%

License

BSD-3-Clause — see LICENSE. Copyright the go-ruby-digest/digest authors.

WebAssembly

Being pure Go (CGO=0), this library also compiles to WebAssembly — both GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI). CI builds both targets on every push, alongside the six 64-bit native/qemu arches.

GOOS=js     GOARCH=wasm go build ./...   # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./...   # WASI (wasmtime, wasmer, wasmedge, …)