filesystem

package
v0.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2024 License: Apache-2.0 Imports: 18 Imported by: 7

Documentation

Overview

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

  1. mountpoint management (mountpoint.go) - querying existing mounted filesystems - getting filesystems from a UUID - finding the filesystem for a specific path
  2. 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

Constants

This section is empty.

Variables

View Source 
var SortDescriptorsByLastMtime = false

SortDescriptorsByLastMtime indicates whether descriptors are sorted by last modification time when being listed. This can be set to true to get consistent output for testing.

Functions

func EscapeString added in v0.3.3 

func EscapeString(str string) string

EscapeString is the reverse of unescapeString. Use this to avoid injecting spaces or newlines into output that uses these characters as separators.

func HaveReadAccessTo added in v0.2.7 

func HaveReadAccessTo(path string) bool

HaveReadAccessTo returns true if the process has read access to a file or directory, without actually opening it.

func OpenFileOverridingUmask added in v0.2.6 

func OpenFileOverridingUmask(name string, flag int, perm os.FileMode) (*os.File, error)

OpenFileOverridingUmask calls os.OpenFile but with the umask overridden so that no permission bits are masked out if the file is created.

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 DeviceNumber added in v0.2.6 

type DeviceNumber uint64

DeviceNumber represents a combined major:minor device number.

func (DeviceNumber) String added in v0.2.6 

func (num DeviceNumber) String() string

type ErrAlreadySetup 

type ErrAlreadySetup struct {
	Mount *Mount
}

ErrAlreadySetup indicates that a filesystem is already setup for fscrypt.

func (*ErrAlreadySetup) Error added in v0.2.8 

func (err *ErrAlreadySetup) Error() string

type ErrCorruptMetadata 

type ErrCorruptMetadata struct {
	Path            string
	UnderlyingError error
}

ErrCorruptMetadata indicates that an fscrypt metadata file is corrupt.

func (*ErrCorruptMetadata) Error added in v0.2.8 

func (err *ErrCorruptMetadata) Error() string

type ErrEncryptionNotEnabled added in v0.2.8 

type ErrEncryptionNotEnabled struct {
	Mount *Mount
}

ErrEncryptionNotEnabled indicates that encryption is not enabled on the given filesystem.

func (*ErrEncryptionNotEnabled) Error added in v0.2.8 

func (err *ErrEncryptionNotEnabled) Error() string

type ErrEncryptionNotSupported added in v0.2.8 

type ErrEncryptionNotSupported struct {
	Mount *Mount
}

ErrEncryptionNotSupported indicates that encryption is not supported on the given filesystem.

func (*ErrEncryptionNotSupported) Error added in v0.2.8 

func (err *ErrEncryptionNotSupported) Error() string
type ErrFollowLink struct {
	Link            string
	UnderlyingError error
}

ErrFollowLink indicates that a protector link can't be followed.

func (*ErrFollowLink) Error added in v0.2.8 

func (err *ErrFollowLink) Error() string

type ErrInsecurePermissions added in v0.3.3 

type ErrInsecurePermissions struct {
	Path string
}

ErrInsecurePermissions indicates that a filesystem is not considered to be setup for fscrypt because a metadata directory has insecure permissions.

func (*ErrInsecurePermissions) Error added in v0.3.3 

func (err *ErrInsecurePermissions) Error() string
type ErrMakeLink struct {
	Target          *Mount
	UnderlyingError error
}

ErrMakeLink indicates that a protector link can't be created.

func (*ErrMakeLink) Error added in v0.2.8 

func (err *ErrMakeLink) Error() string

type ErrMountOwnedByAnotherUser added in v0.3.3 

type ErrMountOwnedByAnotherUser struct {
	Mount *Mount
}

ErrMountOwnedByAnotherUser indicates that the mountpoint root directory is owned by a user that isn't trusted in the current context, so we don't consider fscrypt to be properly setup on the filesystem.

func (*ErrMountOwnedByAnotherUser) Error added in v0.3.3 

func (err *ErrMountOwnedByAnotherUser) Error() string

type ErrNoCreatePermission added in v0.3.3 

type ErrNoCreatePermission struct {
	Mount *Mount
}

ErrNoCreatePermission indicates that the current user lacks permission to create fscrypt metadata on the given filesystem.

func (*ErrNoCreatePermission) Error added in v0.3.3 

func (err *ErrNoCreatePermission) Error() string

type ErrNotAMountpoint 

type ErrNotAMountpoint struct {
	Path string
}

ErrNotAMountpoint indicates that a path is not a mountpoint.

func (*ErrNotAMountpoint) Error added in v0.2.8 

func (err *ErrNotAMountpoint) Error() string

type ErrNotSetup 

type ErrNotSetup struct {
	Mount *Mount
}

ErrNotSetup indicates that a filesystem is not setup for fscrypt.

func (*ErrNotSetup) Error added in v0.2.8 

func (err *ErrNotSetup) Error() string

type ErrPolicyNotFound added in v0.2.8 

type ErrPolicyNotFound struct {
	Descriptor string
	Mount      *Mount
}

ErrPolicyNotFound indicates that the policy metadata was not found.

func (*ErrPolicyNotFound) Error added in v0.2.8 

func (err *ErrPolicyNotFound) Error() string

type ErrProtectorNotFound added in v0.2.8 

type ErrProtectorNotFound struct {
	Descriptor string
	Mount      *Mount
}

ErrProtectorNotFound indicates that the protector metadata was not found.

func (*ErrProtectorNotFound) Error added in v0.2.8 

func (err *ErrProtectorNotFound) Error() string

type ErrSetupByAnotherUser added in v0.3.3 

type ErrSetupByAnotherUser struct {
	Mount *Mount
}

ErrSetupByAnotherUser indicates that one or more of the fscrypt metadata directories is owned by a user that isn't trusted in the current context, so we don't consider fscrypt to be properly setup on the filesystem.

func (*ErrSetupByAnotherUser) Error added in v0.3.3 

func (err *ErrSetupByAnotherUser) Error() string

type ErrSetupNotSupported added in v0.3.2 

type ErrSetupNotSupported struct {
	Mount *Mount
}

ErrSetupNotSupported indicates that the given filesystem type is not supported for fscrypt setup.

func (*ErrSetupNotSupported) Error added in v0.3.2 

func (err *ErrSetupNotSupported) Error() string

type Mount 

type Mount struct {
	Path           string
	FilesystemType string
	Device         string
	DeviceNumber   DeviceNumber
	Subtree        string
	ReadOnly       bool
}

Mount contains information for a specific mounted filesystem. 

Path           - Absolute path where the directory is mounted
FilesystemType - Type of the mounted filesystem, e.g. "ext4"
Device         - Device for filesystem (empty string if we cannot find one)
DeviceNumber   - Device number of the filesystem.  This is set even if
		 Device isn't, since all filesystems have a device
		 number assigned by the kernel, even pseudo-filesystems.
Subtree        - The mounted subtree of the filesystem.  This is usually
		 "/", meaning that the entire filesystem is mounted, but
		 it can differ for bind mounts.
ReadOnly       - True if this is a read-only mount

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.

We also allow ".fscrypt" to be a symlink which was previously created. This allows login protectors to be created when the root filesystem is read-only, provided that "/.fscrypt" is a symlink pointing to a writable location.

func AllFilesystems 

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

AllFilesystems lists all mounted filesystems ordered by path to their "main" Mount. Use CheckSetup() to see if they are set up for use with fscrypt.

func FindMount 

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

FindMount returns the main Mount object for the filesystem which contains the file at the specified path. An error is returned if the path is invalid or if we cannot load the required mount data. If a mount 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 is like FindMount, except GetMount also returns an error if the path doesn't name the same file as the filesystem's "main" Mount. For example, if a filesystem is fully mounted at "/mnt" and if "/mnt/a" exists, then FindMount("/mnt/a") will succeed whereas GetMount("/mnt/a") will fail. This is true even if "/mnt/a" is a bind mount of part of the same filesystem.

func (*Mount) AddLinkedProtector 

func (m *Mount) AddLinkedProtector(descriptor string, dest *Mount, trustedUser *user.User,
	ownerIfCreating *user.User) (bool, error)

AddLinkedProtector adds a link in this filesystem to the protector metadata in the dest filesystem, if one doesn't already exist. On success, the return value is a nil error and a bool that is true iff the link is newly created.

func (*Mount) AddPolicy 

func (m *Mount) AddPolicy(data *metadata.PolicyData, owner *user.User) error

AddPolicy adds the policy metadata to the filesystem storage.

func (*Mount) AddProtector 

func (m *Mount) AddProtector(data *metadata.ProtectorData, owner *user.User) 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 to the base fscrypt directory for this filesystem.

func (*Mount) CheckSetup 

func (m *Mount) CheckSetup(trustedUser *user.User) error

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

func (*Mount) CheckSupport added in v0.2.0 

func (m *Mount) CheckSupport() error

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

func (*Mount) EncryptionSupportError added in v0.2.8 

func (m *Mount) EncryptionSupportError(err error) error

EncryptionSupportError adds filesystem-specific context to the ErrEncryptionNotEnabled and ErrEncryptionNotSupported errors from the metadata package.

func (*Mount) GetPolicy 

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

GetPolicy looks up the policy metadata by descriptor.

func (*Mount) GetProtector 

func (m *Mount) GetProtector(descriptor string, trustedUser *user.User) (*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, trustedUser *user.User) (*metadata.ProtectorData, error)

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

func (*Mount) GetSetupMode added in v0.3.3 

func (m *Mount) GetSetupMode() (SetupMode, *user.User, error)

GetSetupMode returns the current mode for fscrypt metadata creation on this filesystem.

func (*Mount) ListPolicies 

func (m *Mount) ListPolicies(trustedUser *user.User) ([]string, error)

ListPolicies lists the descriptors of all policies on this filesystem. If trustedUser is non-nil, then the policies are restricted to those owned by the given user or by root.

func (*Mount) ListProtectors 

func (m *Mount) ListProtectors(trustedUser *user.User) ([]string, error)

ListProtectors lists the descriptors of all protectors on this filesystem. This does not include linked protectors. If trustedUser is non-nil, then the protectors are restricted to those owned by the given user or by root.

func (*Mount) PolicyDir 

func (m *Mount) PolicyDir() string

PolicyDir returns the directory containing the policy metadata.

func (*Mount) PolicyPath added in v0.2.8 

func (m *Mount) PolicyPath(descriptor string) string

PolicyPath returns the full path to a regular policy file with the specified descriptor.

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 a link to another filesystem's metadata) from the filesystem storage.

func (*Mount) Setup 

func (m *Mount) Setup(mode SetupMode) 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)

type SetupMode added in v0.3.3 

type SetupMode int

SetupMode is a mode for creating the fscrypt metadata directories. 

const (
	// SingleUserWritable specifies to make the fscrypt metadata directories
	// writable by a single user (usually root) only.
	SingleUserWritable SetupMode = iota
	// WorldWritable specifies to make the fscrypt metadata directories
	// world-writable (with the sticky bit set).
	WorldWritable
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.