vfile

Documentation

Overview

Package vfile verifies files against a hash or signature.

vfile aims to be TOCTTOU-safe by reading files into memory before verifying.

Index

• Variables
• func CalculateHash(b *bytes.Reader, h hash.Hash) ([]byte, error)
• func CheckHashedContent(b *bytes.Reader, wantHash []byte, h hash.Hash) (*bytes.Reader, error)
• func GetKeyRing(keyPath string) (openpgp.KeyRing, error)
• func GetRSAKeysFromRing(ring openpgp.KeyRing) ([]*rsa.PublicKey, error)
• type ErrHashMismatch
  • func (e ErrHashMismatch) Error() string
• type ErrInvalidHash
  • func (e ErrInvalidHash) Error() string
  • func (e ErrInvalidHash) Unwrap() error
• type ErrUnsigned
  • func (e ErrUnsigned) Error() string
  • func (e ErrUnsigned) Unwrap() error
• type ErrWrongSigner
  • func (e ErrWrongSigner) Error() string
• type File
  • func OpenHashedFile256(path string, wantSHA256Hash []byte) (*File, error)
  • func OpenHashedFile512(path string, wantSHA512Hash []byte) (*File, error)
  • func OpenSignedFile(keyring openpgp.KeyRing, path, pathSig string) (*File, error)
  • func OpenSignedSigFile(keyring openpgp.KeyRing, path string) (*File, error)
  • func (f *File) Name() string

Variables

var ErrNoExpectedHash = errors.New("OpenHashedFile: no expected hash given")

ErrNoExpectedHash is given when the caller did not specify a hash.

var ErrNoKeyRing = errors.New("no keyring given")

ErrNoKeyRing is returned when a nil keyring was given.

Functions

func CalculateHash

func CalculateHash(b *bytes.Reader, h hash.Hash) ([]byte, error)

CalculateHash computes the hash of the input data b given a hash function.

func CheckHashedContent

func CheckHashedContent(b *bytes.Reader, wantHash []byte, h hash.Hash) (*bytes.Reader, error)

CheckHashedContent verifies a calculated hash against an expected hash array.

WARNING! Unlike many Go functions, this may return both the file and an error in case the expected hash does not match the contents.

If the contents match, the contents are returned with no error.

func GetKeyRing

func GetKeyRing(keyPath string) (openpgp.KeyRing, error)

GetKeyRing returns an OpenPGP KeyRing loaded from the specified path.

keyPath must be an already trusted path, e.g. keys are included in the initramfs.

func GetRSAKeysFromRing

func GetRSAKeysFromRing(ring openpgp.KeyRing) ([]*rsa.PublicKey, error)

GetRSAKeysFromRing iterates a PGP Keyring and extracts all rsa.PublicKey. An error is returned iff the keyring is not found or no RSA public keys were found on it.

Types

type ErrHashMismatch

type ErrHashMismatch struct {
	Want []byte
	Got  []byte
}

ErrHashMismatch is returned when the file's hash does not match the expected hash.

func (ErrHashMismatch) Error

func (e ErrHashMismatch) Error() string

type ErrInvalidHash

type ErrInvalidHash struct {
	// Path is the path to the file that was supposed to be verified.
	Path string

	// Err is some underlying error.
	Err error
}

ErrInvalidHash is returned when hash verification failed.

func (ErrInvalidHash) Error

func (e ErrInvalidHash) Error() string

func (ErrInvalidHash) Unwrap

func (e ErrInvalidHash) Unwrap() error

type ErrUnsigned

type ErrUnsigned struct {
	// Path is the file that failed signature verification.
	Path string

	// Err is a nested error, if there was one.
	Err error
}

ErrUnsigned is returned for a file that failed signature verification.

func (ErrUnsigned) Error

func (e ErrUnsigned) Error() string

func (ErrUnsigned) Unwrap

func (e ErrUnsigned) Unwrap() error

type ErrWrongSigner

type ErrWrongSigner struct {
	// KeyRing is the expected key ring.
	KeyRing openpgp.KeyRing
}

ErrWrongSigner represents a file signed by some key, but not the ones in the given key ring.

func (ErrWrongSigner) Error

func (e ErrWrongSigner) Error() string

type File

type File struct {
	*bytes.Reader

	FileName string
}

File encapsulates a bytes.Reader with the file contents and its name.

func OpenHashedFile256

func OpenHashedFile256(path string, wantSHA256Hash []byte) (*File, error)

OpenHashedFile256 opens path and verifies whether its contents match the given sha256 hash.

WARNING! Unlike many Go functions, this may return both the file and an error in case the expected hash does not match the contents.

If the contents match, the contents are returned with no error.

func OpenHashedFile512

func OpenHashedFile512(path string, wantSHA512Hash []byte) (*File, error)

OpenHashedFile512 opens path and verifies whether its contents match the given sha512 hash.

WARNING! Unlike many Go functions, this may return both the file and an error in case the expected hash does not match the contents.

If the contents match, the contents are returned with no error.

func OpenSignedFile

func OpenSignedFile(keyring openpgp.KeyRing, path, pathSig string) (*File, error)

OpenSignedFile opens a file that is expected to be signed.

WARNING! Unlike many Go functions, this may return both the file and an error.

It expects path.sig to be available.

If the signature does not exist or does not match the keyring, both the file and a signature error will be returned.

func OpenSignedSigFile

func OpenSignedSigFile(keyring openpgp.KeyRing, path string) (*File, error)

OpenSignedSigFile calls OpenSignedFile expecting the signature to be in path.sig.

E.g. if path is /foo/bar, the signature is expected to be in /foo/bar.sig.

func (*File) Name

func (f *File) Name() string

Name returns the file name.