filesystem

Documentation

Overview

Package filesystem deals with the structure of the files on disk used to store the metadata for fscrypt. Specifically, this package includes:

• mountpoint management (mountpoint.go)
• querying existing mounted filesystems
• getting filesystems from a UUID
• finding the filesystem for a specific path
• metadata organization (filesystem.go)
• setting up a mounted filesystem for use with fscrypt
• adding/querying/deleting metadata
• making links to other filesystems' metadata
• following links to get data from other filesystems

Index

• Variables
• func UpdateMountInfo() error
• type Mount
  • func AllFilesystems() ([]*Mount, error)
  • func FindMount(path string) (*Mount, error)
  • func GetMount(mountpoint string) (*Mount, error)
  • func (m *Mount) AddLinkedProtector(descriptor string, dest *Mount) error
  • func (m *Mount) AddPolicy(data *metadata.PolicyData) error
  • func (m *Mount) AddProtector(data *metadata.ProtectorData) error
  • func (m *Mount) BaseDir() string
  • func (m *Mount) CheckSetup() error
  • func (m *Mount) CheckSupport() error
  • func (m *Mount) GetPolicy(descriptor string) (*metadata.PolicyData, error)
  • func (m *Mount) GetProtector(descriptor string) (*Mount, *metadata.ProtectorData, error)
  • func (m *Mount) GetRegularProtector(descriptor string) (*metadata.ProtectorData, error)
  • func (m *Mount) ListPolicies() ([]string, error)
  • func (m *Mount) ListProtectors() ([]string, error)
  • func (m *Mount) PolicyDir() string
  • func (m *Mount) ProtectorDir() string
  • func (m *Mount) RemoveAllMetadata() error
  • func (m *Mount) RemovePolicy(descriptor string) error
  • func (m *Mount) RemoveProtector(descriptor string) error
  • func (m *Mount) Setup() error
  • func (m *Mount) String() string
• type PathSorter
  • func (p PathSorter) Len() int
  • func (p PathSorter) Less(i, j int) bool
  • func (p PathSorter) Swap(i, j int)

Variables

var (
	ErrNotAMountpoint  = errors.New("not a mountpoint")
	ErrAlreadySetup    = errors.New("already setup for use with fscrypt")
	ErrNotSetup        = errors.New("not setup for use with fscrypt")
	ErrNoMetadata      = errors.New("could not find metadata")
	ErrLinkedProtector = errors.New("not a regular protector")
	ErrInvalidMetadata = errors.New("provided metadata is invalid")
	ErrFollowLink      = errors.New("cannot follow filesystem link")
	ErrLinkExpired     = errors.New("no longer exists on linked filesystem")
	ErrMakeLink        = util.SystemError("cannot create filesystem link")
	ErrGlobalMountInfo = util.SystemError("creating global mountpoint list failed")
	ErrCorruptMetadata = util.SystemError("on-disk metadata is corrupt")
)

Filesystem error values

Functions

func UpdateMountInfo

func UpdateMountInfo() error

UpdateMountInfo updates the filesystem mountpoint maps with the current state of the filesystem mountpoints. Returns error if the initialization fails.

Types

type Mount

type Mount struct {
	Path       string
	Filesystem string
	Options    []string
	Device     string
}

Mount contains information for a specific mounted filesystem.

Path       - Absolute path where the directory is mounted
Filesystem - Name of the mounted filesystem
Options    - List of options used when mounting the filesystem
Device     - Device for filesystem (empty string if we cannot find one)

In order to use a Mount to store fscrypt metadata, some directories must be setup first. Specifically, the directories created look like: <mountpoint> └── .fscrypt

├── policies
└── protectors

These "policies" and "protectors" directories will contain files that are the corresponding metadata structures for policies and protectors. The public interface includes functions for setting up these directories and Adding, Getting, and Removing these files.

There is also the ability to reference another filesystem's metadata. This is used when a Policy on filesystem A is protected with Protector on filesystem B. In this scenario, we store a "link file" in the protectors directory whose contents look like "UUID=3a6d9a76-47f0-4f13-81bf-3332fbe984fb". These contents can be anything parsable by libblkid (i.e. anything that could be in the Device column of /etc/fstab).

func AllFilesystems

func AllFilesystems() ([]*Mount, error)

AllFilesystems lists all the Mounts on the current system ordered by path. Use CheckSetup() to see if they are used with fscrypt.

func FindMount

func FindMount(path string) (*Mount, error)

FindMount returns the corresponding Mount object for some path in a filesystem. Note that in the case of a bind mounts there may be two Mount objects for the same underlying filesystem. An error is returned if the path is invalid or we cannot load the required mount data. If a filesystem has been updated since the last call to one of the mount functions, run UpdateMountInfo to see changes.

func GetMount

func GetMount(mountpoint string) (*Mount, error)

GetMount returns the Mount object with a matching mountpoint. An error is returned if the path is invalid or we cannot load the required mount data. If a filesystem has been updated since the last call to one of the mount functions, run UpdateMountInfo to see changes.

func (*Mount) AddLinkedProtector

func (m *Mount) AddLinkedProtector(descriptor string, dest *Mount) error

AddLinkedProtector adds a link in this filesystem to the protector metadata in the dest filesystem.

func (*Mount) AddPolicy

func (m *Mount) AddPolicy(data *metadata.PolicyData) error

AddPolicy adds the policy metadata to the filesystem storage.

func (*Mount) AddProtector

func (m *Mount) AddProtector(data *metadata.ProtectorData) error

AddProtector adds the protector metadata to this filesystem's storage. This will overwrite the value of an existing protector with this descriptor. This will fail with ErrLinkedProtector if a linked protector with this descriptor already exists on the filesystem.

func (*Mount) BaseDir

func (m *Mount) BaseDir() string

BaseDir returns the path of the base fscrypt directory on this filesystem.

func (*Mount) CheckSetup

func (m *Mount) CheckSetup() error

CheckSetup returns an error if all the fscrypt metadata directories do not exist. Will log any unexpected errors or incorrect permissions.

func (*Mount) CheckSupport

func (m *Mount) CheckSupport() error

CheckSupport returns an error if this filesystem does not support filesystem encryption.

func (*Mount) GetPolicy

func (m *Mount) GetPolicy(descriptor string) (*metadata.PolicyData, error)

GetPolicy looks up the policy metadata by descriptor.

func (*Mount) GetProtector

func (m *Mount) GetProtector(descriptor string) (*Mount, *metadata.ProtectorData, error)

GetProtector returns the Mount of the filesystem containing the information and that protector's data. If the descriptor is a regular (not linked) protector, the mount will return itself.

func (*Mount) GetRegularProtector

func (m *Mount) GetRegularProtector(descriptor string) (*metadata.ProtectorData, error)

GetRegularProtector looks up the protector metadata by descriptor. This will fail with ErrNoMetadata if the descriptor is a linked protector.

func (*Mount) ListPolicies

func (m *Mount) ListPolicies() ([]string, error)

ListPolicies lists the descriptors of all policies on this filesystem.

func (*Mount) ListProtectors

func (m *Mount) ListProtectors() ([]string, error)

ListProtectors lists the descriptors of all protectors on this filesystem. This does not include linked protectors.

func (*Mount) PolicyDir

func (m *Mount) PolicyDir() string

PolicyDir returns the directory containing the policy metadata.

func (*Mount) ProtectorDir

func (m *Mount) ProtectorDir() string

ProtectorDir returns the directory containing the protector metadata.

func (*Mount) RemoveAllMetadata

func (m *Mount) RemoveAllMetadata() error

RemoveAllMetadata removes all the policy and protector metadata from the filesystem. This operation is atomic, it either succeeds or no files in the baseDir are removed. WARNING: Will cause data loss if the metadata is used to encrypt directories (this could include directories on other filesystems).

func (*Mount) RemovePolicy

func (m *Mount) RemovePolicy(descriptor string) error

RemovePolicy deletes the policy metadata from the filesystem storage.

func (*Mount) RemoveProtector

func (m *Mount) RemoveProtector(descriptor string) error

RemoveProtector deletes the protector metadata (or an link to another filesystem's metadata) from the filesystem storage.

func (*Mount) Setup

func (m *Mount) Setup() error

Setup sets up the filesystem for use with fscrypt, note that this merely creates the appropriate files on the filesystem. It does not actually modify the filesystem's feature flags. This operation is atomic, it either succeeds or no files in the baseDir are created.

func (*Mount) String

func (m *Mount) String() string

type PathSorter

type PathSorter []*Mount

PathSorter allows mounts to be sorted by Path.

func (PathSorter) Len

func (p PathSorter) Len() int

func (PathSorter) Less

func (p PathSorter) Less(i, j int) bool

func (PathSorter) Swap

func (p PathSorter) Swap(i, j int)