verity

Documentation

Overview

This package implements the minimum of functionality needed to generate and map dm-verity images. It's provided in order to avoid a perceived higher long term cost of packaging, linking against and maintaining the original C veritysetup tool.

dm-verity is a Linux device mapper target that allows integrity verification of a read-only block device. The block device whose integrity should be checked (the 'data device') must be first processed by a tool like veritysetup to generate a hash device and root hash. The original data device, hash device and root hash are then set up as a device mapper target, and any read performed from the data device through the verity target will be verified for integrity by Linux using the hash device and root hash.

Internally, the hash device is a Merkle tree of all the bytes in the data device, layed out as layers of 'hash blocks'. Starting with data bytes, layers are built recursively, with each layer's output hash blocks becoming the next layer's data input, ending with the single root hash.

For more information about the internals, see the Linux and cryptsetup upstream code:

https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity

Index

• func NewEncoder(out io.Writer, dataBlockSize, hashBlockSize uint32, writeSb bool) (*encoder, error)
• type MappingTable
  • func (t *MappingTable) Length() uint64
  • func (t *MappingTable) String() string
  • func (t *MappingTable) TargetParameters() []string
  • func (t *MappingTable) VerityParameterList() []string
• Bugs

Functions

func NewEncoder

func NewEncoder(out io.Writer, dataBlockSize, hashBlockSize uint32, writeSb bool) (*encoder, error)

NewEncoder returns a fully initialized encoder, or an error. The encoder will write to the given io.Writer object. A verity superblock will be written, preceding the hash tree, if writeSb is true.

Types

type MappingTable

type MappingTable struct {

	// DataDevicePath is the filesystem path of the data device used as part
	// of the Verity Device Mapper target.
	DataDevicePath string
	// HashDevicePath is the filesystem path of the hash device used as part
	// of the Verity Device Mapper target.
	HashDevicePath string
	// HashStart marks the starting block of the Verity hash tree.
	HashStart int64
	// contains filtered or unexported fields
}

MappingTable aggregates data needed to generate a complete Verity mapping table.

func (*MappingTable) Length

func (t *MappingTable) Length() uint64

Length returns the data device length, represented as a number of 512-byte sectors.

func (*MappingTable) String

func (t *MappingTable) String() string

String returns a string-formatted mapping table for use with Device Mapper. BUG(mz): unescaped whitespace can appear in block device paths

func (*MappingTable) TargetParameters

func (t *MappingTable) TargetParameters() []string

TargetParameters returns the mapping table as a list of Device Mapper target parameters, ordered as they would appear in a parameter string (see: String).

func (*MappingTable) VerityParameterList

func (t *MappingTable) VerityParameterList() []string

VerityParameterList returns a list of Verity target parameters, ordered as they would appear in a parameter string.

Notes

Bugs

• Current implementation requires a 1/128th of the data image size to be allocatable on the heap.

• unescaped whitespace can appear in block device paths