actions

package
v0.2.7 Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2020 License: Apache-2.0 Imports: 15 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 (
	ErrNoConfigFile     = errors.New("global config file does not exist")
	ErrBadConfigFile    = errors.New("global config file has invalid data")
	ErrConfigFileExists = errors.New("global config file already exists")
	ErrBadConfig        = errors.New("invalid Config structure provided")
	ErrLocked           = errors.New("key needs to be unlocked first")
)

Errors relating to Config files or Config structures.

View Source 
var (
	ErrMissingPolicyMetadata  = util.SystemError("missing policy metadata for encrypted directory")
	ErrPolicyMetadataMismatch = util.SystemError("inconsistent metadata between filesystem and directory")
	ErrDifferentFilesystem    = errors.New("policies may only protect files on the same filesystem")
	ErrOnlyProtector          = errors.New("cannot remove the only protector for a policy")
	ErrAlreadyProtected       = errors.New("policy already protected by protector")
	ErrNotProtected           = errors.New("policy not protected by protector")
	ErrAccessDeniedPossiblyV2 = errors.New("permission denied")
)

Errors relating to Policies

View Source 
var (
	ErrProtectorName        = errors.New("login protectors do not need a name")
	ErrMissingProtectorName = errors.New("custom protectors must have a name")
	ErrDuplicateName        = errors.New("protector with this name already exists")
	ErrDuplicateUID         = errors.New("login protector for this user already exists")
)

Errors relating to Protectors

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.

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, 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
}

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 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.

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

func (policy *Policy) IsFullyDeprovisioned() bool

IsFullyDeprovisioned returns true if the policy has been fully deprovisioned, including by all users and with all files protected by it having been closed.

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, 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(protector *Protector) error

RemoveProtector updates the data that is wrapping the Policy Key so that the provided Protector is no longer protecting the specified Policy. If an error is returned, no data has been changed. Note that no protector links are removed (in the case where the protector and policy are on different filesystems). The policy and protector 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) (*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.