storage

Documentation

Overview

Package storage is the on-disk layout of a password store: name-to-path mapping, tree walking, and durable writes.

The layout is byte-identical to pass. A store is a plain directory tree, an entry is a file named after the entry plus a crypto extension, and nothing binpass-specific is ever written into it.

Index

• Variables
• type Entry
• type FS
  • func New(dir string) *FS
  • func (f *FS) DirPath(name string) (string, error)
  • func (f *FS) Entries(name string, exts []string) ([]Entry, error)
  • func (f *FS) Find(name string, exts []string) (string, error)
  • func (f *FS) IsDir(name string) bool
  • func (f *FS) MkdirAll(path string) error
  • func (f *FS) Name(path string) (string, error)
  • func (f *FS) Path(name, ext string) (string, error)
  • func (f *FS) Read(path string) ([]byte, error)
  • func (f *FS) Remove(path string) error
  • func (f *FS) Rename(from, to string) error
  • func (f *FS) Write(path string, data []byte) error
  • func (f *FS) WriteFrom(path string, produce func(io.Writer) error) error

Variables

var ErrOutsideStore = errors.New("storage: path escapes the store")

ErrOutsideStore reports a name that escapes the store root.

Types

type Entry

type Entry struct {
	// Name is the slash-separated store name, without extension.
	Name string
	// Path is the absolute file path.
	Path string
	// Ext is the crypto extension, including the dot.
	Ext string
}

Entry is one secret found in the store.

type FS

type FS struct {
	// Dir is the absolute store root.
	Dir string
	// Umask masks the permissions of created files and directories,
	// honouring PASSWORD_STORE_UMASK.
	Umask os.FileMode
}

FS is a store rooted at a directory.

func New

func New(dir string) *FS

New returns an FS rooted at dir with pass's default 077 umask.

func (*FS) DirPath

func (f *FS) DirPath(name string) (string, error)

DirPath returns the absolute path of a subfolder name.

func (*FS) Entries

func (f *FS) Entries(name string, exts []string) ([]Entry, error)

Entries walks the subtree rooted at name and returns its entries, sorted by name. Dotfiles and dot-directories are skipped, matching pass, which keeps .git, .gpg-id and .binpass out of listings.

func (*FS) Find

func (f *FS) Find(name string, exts []string) (string, error)

Find returns the path of the entry called name, whatever its crypto extension, preferring exts in the order given. It reports fs.ErrNotExist when no candidate exists.

func (*FS) IsDir

func (f *FS) IsDir(name string) bool

IsDir reports whether name is an existing subfolder of the store.

func (*FS) MkdirAll

func (f *FS) MkdirAll(path string) error

MkdirAll creates a store subdirectory with the store's permissions.

func (*FS) Name

func (f *FS) Name(path string) (string, error)

Name converts an absolute entry path back into a store name, stripping the crypto extension. The result always uses forward slashes.

func (*FS) Path

func (f *FS) Path(name, ext string) (string, error)

Path returns the absolute path of an entry name with the given extension. Names are slash-separated and relative to the store root.

func (*FS) Read

func (f *FS) Read(path string) ([]byte, error)

Read returns the raw ciphertext of a file.

func (*FS) Remove

func (f *FS) Remove(path string) error

Remove deletes an entry file and then prunes the directories it leaves empty, up to the store root, exactly as pass does.

func (*FS) Rename

func (f *FS) Rename(from, to string) error

Rename moves an entry, creating the destination directory and pruning any directories the move empties.

func (*FS) Write

func (f *FS) Write(path string, data []byte) error

Write stores data at path durably: a temporary file in the same directory is written and fsynced, then renamed over the target, then the directory itself is fsynced. A crash therefore leaves either the old entry or the new one, never a truncated secret.

func (*FS) WriteFrom

func (f *FS) WriteFrom(path string, produce func(io.Writer) error) error

WriteFrom is Write for producers that stream, so that a large binary entry never has to exist in memory twice.