base: github.com/grailbio/base/digest Index | Files

package digest

import "github.com/grailbio/base/digest"

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

Package Files

digest.go digestreader.go digestwriter.go

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 Uses

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 Uses

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 Uses

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

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

func Parse Uses

func Parse(s string) (Digest, error)

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

func ParseHash Uses

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 Uses

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 Uses

func (d Digest) Bytes() []byte

Bytes returns the byte representation for this digest.

func (Digest) Expands Uses

func (d Digest) Expands(e Digest) bool

Expands tells whether digest d expands digest e.

func (*Digest) GobDecode Uses

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

GobDecode implements Gob decoding for digests.

func (Digest) GobEncode Uses

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

GobEncode implements Gob encoding for digests.

func (Digest) Hash Uses

func (d Digest) Hash() crypto.Hash

Hash returns the cryptographic hash used to produce this Digest.

func (Digest) Hex Uses

func (d Digest) Hex() string

Hex returns the padded hexadecimal representation of the Digest.

func (Digest) HexN Uses

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 Uses

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 Uses

func (d Digest) IsShort() bool

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

func (Digest) IsZero Uses

func (d Digest) IsZero() bool

IsZero returns whether the digest is the zero digest.

func (Digest) Less Uses

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 Uses

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

MarshalJSON marshals the Digest into JSON format.

func (*Digest) Mix Uses

func (d *Digest) Mix(e Digest)

Mix mixes digests d and e with XOR.

func (Digest) NPrefix Uses

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 Uses

func (d Digest) Name() string

Name returns the name of the digest's hash.

func (Digest) Short Uses

func (d Digest) Short() string

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

func (Digest) ShortString Uses

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 Uses

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 Uses

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 Uses

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

UnmarshalJSON unmarshals a digest from JSON data.

type Digester Uses

type Digester crypto.Hash

Digester computes digests based on a cryptographic hash function.

func (Digester) FromBytes Uses

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

FromBytes computes a Digest from a slice of bytes.

func (Digester) FromDigests Uses

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

FromDigests computes a Digest over other Digests.

func (Digester) FromString Uses

func (d Digester) FromString(s string) Digest

FromString computes a Digest from a string.

func (Digester) MarshalJSON Uses

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

MarshalJSON generates a JSON format byte slice from a Digester.

func (Digester) New Uses

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 Uses

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

NewReader creates a new WriterAt.

func (Digester) NewWriter Uses

func (d Digester) NewWriter() Writer

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

func (Digester) NewWriterAt Uses

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 Uses

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 Uses

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 Uses

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

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

type Reader Uses

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 Uses

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 Uses

func (d Writer) Digest() Digest

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

func (Writer) Write Uses

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

type WriterAt Uses

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 Uses

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 Uses

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

WriteAt implements the WriterAt interface.

Package digest imports 16 packages (graph) and is imported by 51 packages. Updated 2019-05-16. Refresh now. Tools for package owners.