merkletree

Documentation

Overview

Package merkletree implements Merkle tree generating and verification.

Index

• func DigestSize(hashAlgorithm int) int
• func Generate(params *GenerateParams) ([]byte, error)
• func Verify(params *VerifyParams) (int64, error)
• type GenerateParams
• type Layout
  • func InitLayout(dataSize int64, hashAlgorithms int, dataAndTreeInSameFile bool) (Layout, error)
• type VerifyParams
• type VerityDescriptor
  • func (d *VerityDescriptor) String() string

Functions

func DigestSize

func DigestSize(hashAlgorithm int) int

DigestSize returns the size (in bytes) of a digest.

func Generate

func Generate(params *GenerateParams) ([]byte, error)

Generate constructs a Merkle tree for the contents of params.File. The output is written to params.TreeWriter.

Generate returns a hash of a VerityDescriptor, which contains the file metadata and the hash from file content.

func Verify

func Verify(params *VerifyParams) (int64, error)

Verify verifies the content read from data with offset. The content is verified against tree. If content spans across multiple blocks, each block is verified. Verification fails if the hash of the data does not match the tree at any level, or if the final root hash does not match expected. Once the data is verified, it will be written using params.Out.

Verify checks for both target file content and metadata. If readSize is 0, only metadata is checked.

Types

type GenerateParams

type GenerateParams struct {
	// File is a reader of the file to be hashed.
	File io.ReaderAt
	// Size is the size of the file.
	Size int64
	// Name is the name of the target file.
	Name string
	// Mode is the mode of the target file.
	Mode uint32
	// UID is the user ID of the target file.
	UID uint32
	// GID is the group ID of the target file.
	GID uint32
	// Children is a map of children names for a directory. It should be
	// empty for a regular file.
	Children map[string]struct{}
	// SymlinkTarget is the target path of a symlink file, or "" if the file is not a symlink.
	SymlinkTarget string
	// HashAlgorithms is the algorithms used to hash data.
	HashAlgorithms int
	// TreeReader is a reader for the Merkle tree.
	TreeReader io.ReaderAt
	// TreeWriter is a writer for the Merkle tree.
	TreeWriter io.Writer
	// DataAndTreeInSameFile is true if data and Merkle tree are in the same
	// file, or false if Merkle tree is a separate file from data.
	DataAndTreeInSameFile bool
}

GenerateParams contains the parameters used to generate a Merkle tree for a given file.

type Layout

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

Layout defines the scale of a Merkle tree.

func InitLayout

func InitLayout(dataSize int64, hashAlgorithms int, dataAndTreeInSameFile bool) (Layout, error)

InitLayout initializes and returns a new Layout object describing the structure of a tree. dataSize specifies the size of input data in bytes.

type VerifyParams

type VerifyParams struct {
	// Out will be filled with verified data.
	Out io.Writer
	// File is a handler on the file to be verified.
	File io.ReaderAt
	// tree is a handler on the Merkle tree used to verify file.
	Tree io.ReaderAt
	// Size is the size of the file.
	Size int64
	// Name is the name of the target file.
	Name string
	// Mode is the mode of the target file.
	Mode uint32
	// UID is the user ID of the target file.
	UID uint32
	// GID is the group ID of the target file.
	GID uint32
	// Children is a map of children names for a directory. It should be
	// empty for a regular file.
	Children map[string]struct{}
	// SymlinkTarget is the target path of a symlink file, or "" if the file is not a symlink.
	SymlinkTarget string
	// HashAlgorithms is the algorithms used to hash data.
	HashAlgorithms int
	// ReadOffset is the offset of the data range to be verified.
	ReadOffset int64
	// ReadSize is the size of the data range to be verified.
	ReadSize int64
	// Expected is a trusted hash for the file. It is compared with the
	// calculated root hash to verify the content.
	Expected []byte
	// DataAndTreeInSameFile is true if data and Merkle tree are in the same
	// file, or false if Merkle tree is a separate file from data.
	DataAndTreeInSameFile bool
}

VerifyParams contains the params used to verify a portion of a file against a Merkle tree.

type VerityDescriptor

type VerityDescriptor struct {
	Name          string
	FileSize      int64
	Mode          uint32
	UID           uint32
	GID           uint32
	Children      map[string]struct{}
	SymlinkTarget string
	RootHash      []byte
}

VerityDescriptor is a struct that is serialized and hashed to get a file's root hash, which contains the root hash of the raw content and the file's meatadata.

func (*VerityDescriptor) String

func (d *VerityDescriptor) String() string