actions

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: 16 Imported by: 3

Documentation

Overview

Package actions is the high-level interface to the fscrypt packages. The functions here roughly correspond with commands for the tool in cmd/fscrypt. All of the actions include a significant amount of logging, so that good output can be provided for cmd/fscrypt's verbose mode. The top-level actions currently include:

  • Creating a new config file
  • Creating a context on which to perform actions
  • Creating, unlocking, and modifying Protectors
  • Creating, unlocking, and modifying Policies

Index

Constants

This section is empty.

Variables

View Source 
var ConfigFileLocation = "/etc/fscrypt.conf"

ConfigFileLocation is the location of fscrypt's global settings. This can be overridden by the user of this package.

View Source 
var ErrLocked = errors.New("key needs to be unlocked first")

ErrLocked indicates that the key hasn't been unwrapped yet.

View Source 
var LoginProtectorMountpoint = "/"

LoginProtectorMountpoint is the mountpoint where login protectors are stored. This can be overridden by the user of this package.

Functions

func CreateConfigFile 

func CreateConfigFile(target time.Duration, policyVersion int64) error

CreateConfigFile creates a new config file at the appropriate location with the appropriate hashing costs and encryption parameters. The hashing will be configured to take as long as the specified time target. In addition, the version of encryption policy to use may be overridden from the default of v1.

func PurgeAllPolicies 

func PurgeAllPolicies(ctx *Context) error

PurgeAllPolicies removes all policy keys on the filesystem from the kernel keyring. In order for this to fully take effect, the filesystem may also need to be unmounted or caches dropped.

func WriteRecoveryInstructions added in v0.2.6 

func WriteRecoveryInstructions(recoveryPassphrase *crypto.Key, recoveryProtector *Protector,
	policy *Policy, path string) error

WriteRecoveryInstructions writes a recovery passphrase and instructions to a file. This file should initially be located in the encrypted directory protected by the passphrase itself. It's up to the user to store the passphrase in a different location if they actually need it.

Types

type Context 

type Context struct {
	// Config is the struct loaded from the global config file. It can be
	// modified after being loaded to customise parameters.
	Config *metadata.Config
	// Mount is the filesystem relative to which all Protectors and Policies
	// are added, edited, removed, and applied, and to which policies using
	// the filesystem keyring are provisioned.
	Mount *filesystem.Mount
	// TargetUser is the user for whom protectors are created, and to whose
	// keyring policies using the user keyring are provisioned.  It's also
	// the user for whom the keys are claimed in the filesystem keyring when
	// v2 policies are provisioned.
	TargetUser *user.User
	// TrustedUser is the user for whom policies and protectors are allowed
	// to be read.  Specifically, if TrustedUser is set, then only
	// policies and protectors owned by TrustedUser or by root will be
	// allowed to be read.  If it's nil, then all policies and protectors
	// the process has filesystem-level read access to will be allowed.
	TrustedUser *user.User
}

Context contains the necessary global state to perform most of fscrypt's actions.

func NewContextFromMountpoint 

func NewContextFromMountpoint(mountpoint string, targetUser *user.User) (*Context, error)

NewContextFromMountpoint makes a context for the filesystem at the specified mountpoint and whose Config is loaded from the global config file. On success, the Context contains a valid Config and Mount. The target user defaults to the current effective user if none is specified.

func NewContextFromPath 

func NewContextFromPath(path string, targetUser *user.User) (*Context, error)

NewContextFromPath makes a context for the filesystem containing the specified path and whose Config is loaded from the global config file. On success, the Context contains a valid Config and Mount. The target user defaults to the current effective user if none is specified.

func (*Context) ProtectorOptions 

func (ctx *Context) ProtectorOptions() ([]*ProtectorOption, error)

ProtectorOptions creates a slice of all the options for all of the Protectors on the Context's mountpoint.

type ErrAccessDeniedPossiblyV2 added in v0.2.7 

type ErrAccessDeniedPossiblyV2 struct {
	DirPath string
}

ErrAccessDeniedPossiblyV2 indicates that a directory's encryption policy couldn't be retrieved due to "permission denied", but it looks like it's due to the directory using a v2 policy but the kernel not supporting it.

func (*ErrAccessDeniedPossiblyV2) Error added in v0.2.8 

func (err *ErrAccessDeniedPossiblyV2) Error() string

type ErrAlreadyProtected 

type ErrAlreadyProtected struct {
	Policy    *Policy
	Protector *Protector
}

ErrAlreadyProtected indicates that a policy is already protected by the given protector.

func (*ErrAlreadyProtected) Error added in v0.2.8 

func (err *ErrAlreadyProtected) Error() string

type ErrBadConfig 

type ErrBadConfig struct {
	Config          *metadata.Config
	UnderlyingError error
}

ErrBadConfig is an internal error that indicates that the config struct is invalid.

func (*ErrBadConfig) Error added in v0.2.8 

func (err *ErrBadConfig) Error() string

type ErrBadConfigFile 

type ErrBadConfigFile struct {
	Path            string
	UnderlyingError error
}

ErrBadConfigFile indicates that the config file is invalid.

func (*ErrBadConfigFile) Error added in v0.2.8 

func (err *ErrBadConfigFile) Error() string

type ErrConfigFileExists 

type ErrConfigFileExists struct {
	Path string
}

ErrConfigFileExists indicates that the config file already exists.

func (*ErrConfigFileExists) Error added in v0.2.8 

func (err *ErrConfigFileExists) Error() string

type ErrDifferentFilesystem 

type ErrDifferentFilesystem struct {
	PolicyMount *filesystem.Mount
	PathMount   *filesystem.Mount
}

ErrDifferentFilesystem indicates that a policy can't be applied to a directory on a different filesystem.

func (*ErrDifferentFilesystem) Error added in v0.2.8 

func (err *ErrDifferentFilesystem) Error() string

type ErrLoginProtectorExists added in v0.2.8 

type ErrLoginProtectorExists struct {
	User *user.User
}

ErrLoginProtectorExists indicates that a user already has a login protector.

func (*ErrLoginProtectorExists) Error added in v0.2.8 

func (err *ErrLoginProtectorExists) Error() string

type ErrLoginProtectorName added in v0.2.8 

type ErrLoginProtectorName struct {
	Name string
	User *user.User
}

ErrLoginProtectorName indicates that a name was given for a login protector.

func (*ErrLoginProtectorName) Error added in v0.2.8 

func (err *ErrLoginProtectorName) Error() string

type ErrMissingPolicyMetadata 

type ErrMissingPolicyMetadata struct {
	Mount      *filesystem.Mount
	DirPath    string
	Descriptor string
}

ErrMissingPolicyMetadata indicates that a directory is encrypted but its policy metadata cannot be found.

func (*ErrMissingPolicyMetadata) Error added in v0.2.8 

func (err *ErrMissingPolicyMetadata) Error() string

type ErrMissingProtectorName 

type ErrMissingProtectorName struct {
	Source metadata.SourceType
}

ErrMissingProtectorName indicates that a protector name is needed.

func (*ErrMissingProtectorName) Error added in v0.2.8 

func (err *ErrMissingProtectorName) Error() string

type ErrNoConfigFile 

type ErrNoConfigFile struct {
	Path string
}

ErrNoConfigFile indicates that the config file doesn't exist.

func (*ErrNoConfigFile) Error added in v0.2.8 

func (err *ErrNoConfigFile) Error() string

type ErrNotProtected 

type ErrNotProtected struct {
	PolicyDescriptor    string
	ProtectorDescriptor string
}

ErrNotProtected indicates that the given policy is not protected by the given protector.

func (*ErrNotProtected) Error added in v0.2.8 

func (err *ErrNotProtected) Error() string

type ErrOnlyProtector 

type ErrOnlyProtector struct {
	Policy *Policy
}

ErrOnlyProtector indicates that the last protector can't be removed from a policy.

func (*ErrOnlyProtector) Error added in v0.2.8 

func (err *ErrOnlyProtector) Error() string

type ErrPolicyMetadataMismatch 

type ErrPolicyMetadataMismatch struct {
	DirPath   string
	Mount     *filesystem.Mount
	PathData  *metadata.PolicyData
	MountData *metadata.PolicyData
}

ErrPolicyMetadataMismatch indicates that the policy metadata for an encrypted directory is inconsistent with that directory.

func (*ErrPolicyMetadataMismatch) Error added in v0.2.8 

func (err *ErrPolicyMetadataMismatch) Error() string

type ErrProtectorNameExists added in v0.2.8 

type ErrProtectorNameExists struct {
	Name string
}

ErrProtectorNameExists indicates that a protector name already exists.

func (*ErrProtectorNameExists) Error added in v0.2.8 

func (err *ErrProtectorNameExists) Error() string

type KeyFunc 

type KeyFunc func(info ProtectorInfo, retry bool) (*crypto.Key, error)

KeyFunc is passed to a function that will require some type of key. The info parameter is provided so the callback knows which key to provide. The retry parameter indicates that a previous key provided by this callback was incorrect (this allows for user feedback like "incorrect passphrase").

For passphrase sources, the returned key should be a passphrase. For raw sources, the returned key should be a 256-bit cryptographic key. Consumers of the callback will wipe the returned key. An error returned by the callback will be propagated back to the caller.

type OptionFunc 

type OptionFunc func(policyDescriptor string, options []*ProtectorOption) (int, error)

OptionFunc is passed to a function that needs to unlock a Policy. The callback is used to specify which protector should be used to unlock a Policy. The descriptor indicates which Policy we are using, while the options correspond to the valid Protectors protecting the Policy.

The OptionFunc should either return a valid index into options, which corresponds to the desired protector, or an error (which will be propagated back to the caller).

type Policy 

type Policy struct {
	Context *Context
	// contains filtered or unexported fields
}

Policy represents an unlocked policy, so it contains the PolicyData as well as the actual protector key. These unlocked Polices can then be applied to a directory, or have their key material inserted into the keyring (which will allow encrypted files to be accessed). As with the key struct, a Policy should be wiped after use.

func CreatePolicy 

func CreatePolicy(ctx *Context, protector *Protector) (*Policy, error)

CreatePolicy creates a Policy protected by given Protector and stores the appropriate data on the filesystem. On error, no data is changed on the filesystem.

func GetPolicy 

func GetPolicy(ctx *Context, descriptor string) (*Policy, error)

GetPolicy retrieves a locked policy with a specific descriptor. The Policy is still locked in this case, so it must be unlocked before using certain methods.

func GetPolicyFromPath 

func GetPolicyFromPath(ctx *Context, path string) (*Policy, error)

GetPolicyFromPath returns the locked policy descriptor for a file on the filesystem. The Policy is still locked in this case, so it must be unlocked before using certain methods. An error is returned if the metadata is inconsistent or the path is not encrypted.

func (*Policy) AddProtector 

func (policy *Policy) AddProtector(protector *Protector) error

AddProtector updates the data that is wrapping the Policy Key so that the provided Protector is now protecting the specified Policy. If an error is returned, no data has been changed. If the policy and protector are on different filesystems, a link will be created between them. The policy and protector must both be unlocked.

func (*Policy) Apply 

func (policy *Policy) Apply(path string) error

Apply sets the Policy on a specified directory. Currently we impose the additional constraint that policies and the directories they are applied to must reside on the same filesystem.

func (*Policy) CanBeAppliedWithoutProvisioning added in v0.2.6 

func (policy *Policy) CanBeAppliedWithoutProvisioning() bool

CanBeAppliedWithoutProvisioning returns true if this process can apply this policy to a directory without first calling Provision.

func (*Policy) Deprovision 

func (policy *Policy) Deprovision(allUsers bool) error

Deprovision removes the Policy key from the kernel keyring. This prevents reading and writing to the directory --- unless the target keyring is a user keyring, in which case caches must be dropped too. If the Policy key was already removed, returns keyring.ErrKeyNotPresent.

func (*Policy) Descriptor 

func (policy *Policy) Descriptor() string

Descriptor returns the key descriptor for this policy.

func (*Policy) Destroy 

func (policy *Policy) Destroy() error

Destroy removes a policy from the filesystem. It also removes any new protector links that were created for the policy. This does *not* wipe the policy's internal key from memory; use Lock() to do that.

func (*Policy) GetProvisioningStatus added in v0.2.6 

func (policy *Policy) GetProvisioningStatus() keyring.KeyStatus

GetProvisioningStatus returns the status of this policy's key in the keyring.

func (*Policy) IsProvisionedByTargetUser added in v0.2.6 

func (policy *Policy) IsProvisionedByTargetUser() bool

IsProvisionedByTargetUser returns true if the policy's key is present in the target kernel keyring, but not if that keyring is a filesystem keyring and the key only been added by users other than Context.TargetUser.

func (*Policy) Lock 

func (policy *Policy) Lock() error

Lock wipes a Policy's internal Key. It should always be called after using a Policy. This is often done with a defer statement. There is no effect if called multiple times.

func (*Policy) NeedsRootToProvision added in v0.2.6 

func (policy *Policy) NeedsRootToProvision() bool

NeedsRootToProvision returns true if Provision and Deprovision will require root for this policy in the current configuration.

func (*Policy) NeedsUserKeyring added in v0.2.6 

func (policy *Policy) NeedsUserKeyring() bool

NeedsUserKeyring returns true if Provision and Deprovision for this policy will use a user keyring (deprecated), not a filesystem keyring.

func (*Policy) Options added in v0.2.5 

func (policy *Policy) Options() *metadata.EncryptionOptions

Options returns the encryption options of this policy.

func (*Policy) ProtectorDescriptors 

func (policy *Policy) ProtectorDescriptors() []string

ProtectorDescriptors creates a slice of the Protector descriptors for the protectors protecting this policy.

func (*Policy) ProtectorOptions 

func (policy *Policy) ProtectorOptions() []*ProtectorOption

ProtectorOptions creates a slice of ProtectorOptions for the protectors protecting this policy.

func (*Policy) Provision 

func (policy *Policy) Provision() error

Provision inserts the Policy key into the kernel keyring. This allows reading and writing of files encrypted with this directory. Requires unlocked Policy.

func (*Policy) RemoveProtector 

func (policy *Policy) RemoveProtector(protectorDescriptor string) error

RemoveProtector updates the data that is wrapping the Policy Key so that the protector with the given descriptor is no longer protecting the specified Policy. If an error is returned, no data has been changed. Note that the protector itself won't be removed, nor will a link to the protector be removed (in the case where the protector and policy are on different filesystems). The policy can be locked or unlocked.

func (*Policy) Revert 

func (policy *Policy) Revert() error

Revert destroys a policy if it was created, but does nothing if it was just queried from the filesystem.

func (*Policy) String 

func (policy *Policy) String() string

func (*Policy) Unlock 

func (policy *Policy) Unlock(optionFn OptionFunc, keyFn KeyFunc) error

Unlock unwraps the Policy's internal key. As a Protector is needed to unlock the Policy, callbacks to select the Policy and get the key are needed. This method will retry the keyFn as necessary to get the correct key for the selected protector. Does nothing if policy is already unlocked.

func (*Policy) UnlockWithProtector added in v0.2.0 

func (policy *Policy) UnlockWithProtector(protector *Protector) error

UnlockWithProtector uses an unlocked Protector to unlock a policy. An error is returned if the Protector is not yet unlocked or does not protect the policy. Does nothing if policy is already unlocked.

func (*Policy) UsesProtector added in v0.2.0 

func (policy *Policy) UsesProtector(protector *Protector) bool

UsesProtector returns if the policy is protected with the protector

func (*Policy) Version added in v0.2.6 

func (policy *Policy) Version() int64

Version returns the version of this policy.

type Protector 

type Protector struct {
	Context *Context
	// contains filtered or unexported fields
}

Protector represents an unlocked protector, so it contains the ProtectorData as well as the actual protector key. These unlocked Protectors are necessary to unlock policies and create new polices. As with the key struct, a Protector should be wiped after use.

func AddRecoveryPassphrase added in v0.2.6 

func AddRecoveryPassphrase(policy *Policy, dirname string) (*crypto.Key, *Protector, error)

AddRecoveryPassphrase randomly generates a recovery passphrase and adds it as a custom_passphrase protector for the given Policy.

func CreateProtector 

func CreateProtector(ctx *Context, name string, keyFn KeyFunc, owner *user.User) (*Protector, error)

CreateProtector creates an unlocked protector with a given name (name only needed for custom and raw protector types). The keyFn provided to create the Protector key will only be called once. If an error is returned, no data has been changed on the filesystem.

func GetProtector 

func GetProtector(ctx *Context, descriptor string) (*Protector, error)

GetProtector retrieves a Protector with a specific descriptor. The Protector is still locked in this case, so it must be unlocked before using certain methods.

func GetProtectorFromOption 

func GetProtectorFromOption(ctx *Context, option *ProtectorOption) (*Protector, error)

GetProtectorFromOption retrieves a protector based on a protector option. If the option had a load error, this function returns that error. The Protector is still locked in this case, so it must be unlocked before using certain methods.

func (*Protector) Descriptor 

func (protector *Protector) Descriptor() string

Descriptor returns the protector descriptor.

func (*Protector) Destroy 

func (protector *Protector) Destroy() error

Destroy removes a protector from the filesystem. The internal key should still be wiped with Lock().

func (*Protector) Lock 

func (protector *Protector) Lock() error

Lock wipes a Protector's internal Key. It should always be called after using an unlocked Protector. This is often done with a defer statement. There is no effect if called multiple times.

func (*Protector) Revert 

func (protector *Protector) Revert() error

Revert destroys a protector if it was created, but does nothing if it was just queried from the filesystem.

func (*Protector) Rewrap 

func (protector *Protector) Rewrap(keyFn KeyFunc) error

Rewrap updates the data that is wrapping the Protector Key. This is useful if a user's password has changed, for example. The keyFn provided to rewrap the Protector key will only be called once. Requires unlocked Protector.

func (*Protector) String 

func (protector *Protector) String() string

func (*Protector) Unlock 

func (protector *Protector) Unlock(keyFn KeyFunc) (err error)

Unlock unwraps the Protector's internal key. The keyFn provided to unwrap the Protector key will be retried as necessary to get the correct key. Lock() should be called after use. Does nothing if protector is already unlocked.

type ProtectorInfo 

type ProtectorInfo struct {
	// contains filtered or unexported fields
}

ProtectorInfo is the information a caller will receive about a Protector before they have to return the corresponding key. This is currently a read-only view of metadata.ProtectorData.

func (*ProtectorInfo) Descriptor 

func (pi *ProtectorInfo) Descriptor() string

Descriptor is the Protector's descriptor used to uniquely identify it.

func (*ProtectorInfo) Name 

func (pi *ProtectorInfo) Name() string

Name is used to describe custom passphrase and raw key descriptors.

func (*ProtectorInfo) Source 

func (pi *ProtectorInfo) Source() metadata.SourceType

Source indicates the type of the descriptor (how it should be unlocked).

func (*ProtectorInfo) UID 

func (pi *ProtectorInfo) UID() int64

UID is used to identify the user for login passphrases.

type ProtectorOption 

type ProtectorOption struct {
	ProtectorInfo
	// LinkedMount is the mountpoint for a linked protector. It is nil if
	// the protector is not a linked protector (or there is a LoadError).
	LinkedMount *filesystem.Mount
	// LoadError is non-nil if there was an error in getting the data for
	// the protector.
	LoadError error
}

ProtectorOption is information about a protector relative to a Policy.

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.