Back to godoc.org

Package digest

v0.0.10
Latest Go to latest

The highest tagged major version is .

Published: Oct 8, 2020 | License: Apache-2.0 | Module: github.com/grailbio/base

Overview

Package digest provides a generalized representation for digests computed with cryptographic hash functions. It provides an efficient in-memory representation as well as serialization.

Index

Constants

const (
	MD4         digestHash = 1 + iota // crypto.MD4
	MD5                               // crypto.MD5
	SHA1                              // crypto.SHA1
	SHA224                            // crypto.SHA224
	SHA256                            // crypto.SHA256
	SHA384                            // crypto.SHA384
	SHA512                            // crypto.SHA512
	MD5SHA1                           // crypto.MD5SHA1
	RIPEMD160                         // crypto.RIPEMD160
	SHA3_224                          // crypto.SHA3_224
	SHA3_256                          // crypto.SHA3_256
	SHA3_384                          // crypto.SHA3_384
	SHA3_512                          // crypto.SHA3_512
	SHA512_224                        // crypto.SHA512_224
	SHA512_256                        // crypto.SHA512_256
	BLAKE2s_256                       // crypto.BLAKE2s_256
	BLAKE2b_256                       // crypto.BLAKE2b_256
	BLAKE2b_384                       // crypto.BLAKE2b_384
	BLAKE2b_512                       // crypto.BLAKE2b_512

)

Variables

var (
	// An attempt was made to parse an invalid digest
	ErrInvalidDigest = errors.New("invalid digest")
	// A Digest's hash function was not imported.
	ErrHashUnavailable = errors.New("the requested hash function is not available")
	// The Digest's hash did not match the hash of the Digester.
	ErrWrongHash = errors.New("wrong hash")
	// An EOF was encountered while attempting to read a Digest.
	ErrShortRead = errors.New("short read")
)

func WriteDigest

func WriteDigest(w io.Writer, d Digest) (n int, err error)

WriteDigest is a convenience function to write a (binary) Digest to an io.Writer. Its format is two bytes representing the hash function, followed by the hash value itself.

Writing a zero digest is disallowed; WriteDigest panics in this case.

type Digest

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

Digest represents a digest computed with a cryptographic hash function. It uses a fixed-size representation and is directly comparable.

func New

func New(h crypto.Hash, b []byte) Digest

New returns a new literal digest with the provided hash and value.

func Parse

func Parse(s string) (Digest, error)

Parse parses a string representation of Digest, as defined by Digest.String().

func ParseHash

func ParseHash(h crypto.Hash, hx string) (Digest, error)

ParseHash parses hex string hx produced by the the hash h into a Digest.

func ReadDigest

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

ReadDigest is a convenience function to read a (binary) Digest from an io.Reader, as written by WriteDigest.

func (Digest) Bytes

func (d Digest) Bytes() []byte

Bytes returns the byte representation for this digest.

func (Digest) Expands

func (d Digest) Expands(e Digest) bool

Expands tells whether digest d expands digest e.

func (*Digest) GobDecode

func (d *Digest) GobDecode(p []byte) error

GobDecode implements Gob decoding for digests.

func (Digest) GobEncode

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

GobEncode implements Gob encoding for digests.

func (Digest) Hash

func (d Digest) Hash() crypto.Hash

Hash returns the cryptographic hash used to produce this Digest.

func (Digest) Hex

func (d Digest) Hex() string

Hex returns the padded hexadecimal representation of the Digest.

func (Digest) HexN

func (d Digest) HexN(n int) string

HexN returns the padded hexadecimal representation of the digest's first n bytes. N must be smaller or equal to the digest's size, or else it panics.

func (Digest) IsAbbrev

func (d Digest) IsAbbrev() bool

IsAbbrev tells whether d is an "abbreviated" digest, comprising no more than half of the digest bytes.

func (Digest) IsShort

func (d Digest) IsShort() bool

IsShort tells whether d is a "short" digest, comprising only the initial 4 bytes.

func (Digest) IsZero

func (d Digest) IsZero() bool

IsZero returns whether the digest is the zero digest.

func (Digest) Less

func (d Digest) Less(e Digest) bool

Less defines an order of digests of the same hash. panics if two Less digests with different hashes are compared.

func (Digest) MarshalJSON

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

MarshalJSON marshals the Digest into JSON format.

func (*Digest) Mix

func (d *Digest) Mix(e Digest)

Mix mixes digests d and e with XOR.

func (Digest) NPrefix

func (d Digest) NPrefix() int

NPrefix returns the number of nonzero leading bytes in the digest, after which the remaining bytes are zero.

func (Digest) Name

func (d Digest) Name() string

Name returns the name of the digest's hash.

func (Digest) Short

func (d Digest) Short() string

Short returns a short (prefix) version of the Digest's hexadecimal representation.

func (Digest) ShortString

func (d Digest) ShortString(n int) string

ShortString returns a short representation of the digest, comprising the digest name and its first n bytes.

func (Digest) String

func (d Digest) String() string

String returns the full string representation of the digest: the digest name, followed by ":", followed by its hexadecimal value.

func (*Digest) Truncate

func (d *Digest) Truncate(n int)

Truncate truncates digest d to n bytes. Truncate panics if n is greater than the digest's hash size.

func (*Digest) UnmarshalJSON

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

UnmarshalJSON unmarshals a digest from JSON data.

type Digester

type Digester crypto.Hash

Digester computes digests based on a cryptographic hash function.

func (Digester) FromBytes

func (d Digester) FromBytes(p []byte) Digest

FromBytes computes a Digest from a slice of bytes.

func (Digester) FromDigests

func (d Digester) FromDigests(digests ...Digest) Digest

FromDigests computes a Digest over other Digests.

func (Digester) FromString

func (d Digester) FromString(s string) Digest

FromString computes a Digest from a string.

func (Digester) MarshalJSON

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

MarshalJSON generates a JSON format byte slice from a Digester.

func (Digester) New

func (d Digester) New(b []byte) Digest

New returns a new digest with the provided literal contents. New panics if the digest size does not match the hash function's length.

func (Digester) NewReader

func (d Digester) NewReader(source io.Reader) Reader

NewReader creates a new WriterAt.

func (Digester) NewWriter

func (d Digester) NewWriter() Writer

NewWriter returns a Writer that can be used to compute Digests of long inputs.

func (Digester) NewWriterAt

func (d Digester) NewWriterAt(ctx context.Context, target io.WriterAt) *WriterAt

NewWriterAt creates a new WriterAt. The provided context is used to fail pending writes upon cancellation.

func (Digester) Parse

func (d Digester) Parse(s string) (Digest, error)

Parse parses a string into a Digest with the cryptographic hash of Digester. The input string is in the form of Digest.String, except that the hash name may be omitted--it is then instead assumed to be the hash function associated with the Digester.

func (Digester) Rand

func (d Digester) Rand(r *mathrand.Rand) Digest

Rand returns a random digest generated by the random provided generator. If no generator is provided (r is nil), Rand uses the system's cryptographically secure random number generator.

func (*Digester) UnmarshalJSON

func (d *Digester) UnmarshalJSON(b []byte) error

UnmarshalJSON converts from a JSON format byte slice to a Digester.

type Reader

type Reader interface {
	io.Reader
	Digest() (Digest, error)
}

Reader can be used to calculate the digest of a file as it is being read. It uses back pressure to stall reads when a block is missing. This can cause deadlock if the application doesn't retry immediately.

The s3manager uploader differentiates between two kinds of readers to improve upload performance: Simple Readers and "ReaderSeekers" for performance. This implementation creates either a simpleReaderAt or a readerAtSeeker depending on the underlying ReaderAt.

Expects the reads to be complete and non-overlapping.

type Writer

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

Writer provides an io.Writer to which digested bytes are written and from which a Digest is produced.

func (Writer) Digest

func (d Writer) Digest() Digest

Digest produces the current Digest of the Writer. It does not reset its internal state.

func (Writer) Write

func (d Writer) Write(p []byte) (n int, err error)

type WriterAt

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

WriterAt can be used to calculate the digest of a file as it is being written. It uses back pressure to stall writes when a block is missing. WriterAt must be written to sequentially (otherwise a deadlock is possible); but it accepts re-writes of past regions so that the user can retry failures.

In particular, this matches the semantics for the S3 download manager from github.com/aws/aws-sdk-go; thus WriterAt can be used to speed up simultaneous download and integrity checking for objects stored in S3.

func (*WriterAt) Digest

func (w *WriterAt) Digest() (Digest, error)

Digest returns the digest for the data that has been written. Digest waits for writes to flush, and returns underlying context errors.

func (*WriterAt) WriteAt

func (w *WriterAt) WriteAt(p []byte, off int64) (int, error)

WriteAt implements the WriterAt interface.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier