digest

Documentation

Overview

Package digest provides a type-safe SHA256 digest implementation.

The Digest type enforces the canonical format "sha256:<64 lowercase hex chars>" at construction time and provides constant-time comparison to prevent timing side-channel attacks.

Usage

d, err := digest.Parse("sha256:abc123...")
if err != nil {
    // handle invalid format
}

// Compute from bytes
d := digest.FromBytes(data)

// Constant-time comparison
if d.Equal(other) { ... }

Security Properties

• Format validation at parse time (rejects malformed digests)
• Constant-time comparison (prevents timing attacks)
• Immutable after construction (prevents TOCTOU)
• JSON marshaling preserves format exactly

Index

• func Validate(s string) error
• type Digest
  • func FromBytes(data []byte) Digest
  • func FromReader(r io.Reader) (Digest, error)
  • func MustParse(s string) Digest
  • func Parse(s string) (Digest, error)
  • func (d Digest) Equal(other Digest) bool
  • func (d Digest) Hex() string
  • func (d Digest) IsZero() bool
  • func (d Digest) MarshalJSON() ([]byte, error)
  • func (d Digest) String() string
  • func (d *Digest) UnmarshalJSON(data []byte) error
• type Hasher
  • func NewHasher() *Hasher
  • func (h *Hasher) Digest() Digest
  • func (h *Hasher) Write(p []byte) (n int, err error)

Functions

func Validate

func Validate(s string) error

Validate checks if a string is a valid digest format without allocating a Digest. This is useful for validation-only scenarios.

Types

type Digest

type Digest struct {
	// contains filtered or unexported fields
}

Digest represents a SHA256 digest in canonical format. The zero value is invalid; use Parse, FromBytes, or FromReader to create.

func FromBytes

func FromBytes(data []byte) Digest

FromBytes computes the SHA256 digest of the given data.

func FromReader

func FromReader(r io.Reader) (Digest, error)

FromReader computes the SHA256 digest by reading from r.

func MustParse

func MustParse(s string) Digest

MustParse parses a digest string, panicking if invalid. Use only for compile-time constants and tests.

func Parse

func Parse(s string) (Digest, error)

Parse parses a digest string in canonical format. Returns an error if the format is invalid.

func (Digest) Equal

func (d Digest) Equal(other Digest) bool

Equal reports whether d and other represent the same digest. Uses constant-time comparison to prevent timing side-channel attacks. Returns false if either digest is zero.

func (Digest) Hex

func (d Digest) Hex() string

Hex returns just the hex portion of the digest (without "sha256:" prefix). Returns empty string for zero-value Digest.

func (Digest) IsZero

func (d Digest) IsZero() bool

IsZero reports whether d is the zero value (invalid/unset).

func (Digest) MarshalJSON

func (d Digest) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Digest) String

func (d Digest) String() string

String returns the canonical string representation. Returns empty string for zero-value Digest.

func (*Digest) UnmarshalJSON

func (d *Digest) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Validates the digest format during unmarshaling.

type Hasher

type Hasher struct {
	// contains filtered or unexported fields
}

Hasher accumulates data for digest computation. Use NewHasher to create, Write to add data, and Digest to get the result. Hasher implements io.Writer for use with io.Copy, io.TeeReader, etc.

func NewHasher

func NewHasher() *Hasher

NewHasher creates a new Hasher for incremental digest computation.

func (*Hasher) Digest

func (h *Hasher) Digest() Digest

Digest returns the computed digest. The Hasher can continue to be used after calling Digest.

func (*Hasher) Write

func (h *Hasher) Write(p []byte) (n int, err error)

Write implements io.Writer, adding data to the hash computation.