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



    View Source
    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


    View Source
    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 {
                                                                                	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; 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.