requestprompts

Documentation

Overview

Package requestrules provides support for holding outstanding request prompts for AppArmor prompting.

Index

• func MockSendReply(f func(listenerReq *listener.Request, allowedPermission any) error) (restore func())
• type Prompt
  • func (p *Prompt) MarshalJSON() ([]byte, error)
• type PromptDB
  • func New(...) (*PromptDB, error)
  • func (pdb *PromptDB) AddOrMerge(metadata *prompting.Metadata, path string, requestedPermissions []string, ...) (*Prompt, bool, error)
  • func (pdb *PromptDB) Close() error
  • func (pdb *PromptDB) HandleNewRule(metadata *prompting.Metadata, constraints *prompting.RuleConstraints) ([]prompting.IDType, error)
  • func (pdb *PromptDB) PromptWithID(user uint32, id prompting.IDType, clientActivity bool) (*Prompt, error)
  • func (pdb *PromptDB) Prompts(user uint32, clientActivity bool) ([]*Prompt, error)
  • func (pdb *PromptDB) Reply(user uint32, id prompting.IDType, outcome prompting.OutcomeType, ...) (*Prompt, error)

Functions

func MockSendReply

func MockSendReply(f func(listenerReq *listener.Request, allowedPermission any) error) (restore func())

MockSendReply mocks the function to send a reply back to the listener so tests, both for this package and for consumers of this package, can mock the listener.

Types

type Prompt

type Prompt struct {
	ID          prompting.IDType
	Timestamp   time.Time
	Snap        string
	Interface   string
	Constraints *promptConstraints
	// contains filtered or unexported fields
}

Prompt contains information about a request for which a user should be prompted.

func (*Prompt) MarshalJSON

func (p *Prompt) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Prompt to JSON. TODO: consider having instead a MarshalForClient -> json.RawMessage method

type PromptDB

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

PromptDB stores outstanding prompts in memory and ensures that new prompts are created with a unique ID.

func New

func New(notifyPrompt func(userID uint32, promptID prompting.IDType, data map[string]string) error) (*PromptDB, error)

New creates and returns a new prompt database.

The given notifyPrompt closure will be called when a prompt is added, merged, modified, or resolved. In order to guarantee the order of notices, notifyPrompt is called with the prompt DB lock held, so it should not block for a substantial amount of time (such as to lock and modify snapd state).

func (*PromptDB) AddOrMerge

func (pdb *PromptDB) AddOrMerge(metadata *prompting.Metadata, path string, requestedPermissions []string, outstandingPermissions []string, listenerReq *listener.Request) (*Prompt, bool, error)

AddOrMerge checks if the given prompt contents are identical to an existing prompt and, if so, merges with it by adding the given listenerReq to it. Otherwise, adds a new prompt with the given contents to the prompt DB. If an error occurs, no change is made to the DB.

If the prompt was merged with an identical existing prompt, returns the existing prompt and true, indicating it was merged. If a new prompt was added, returns the new prompt and false, indicating the prompt was not merged.

The caller must ensure that the given permissions are in the order in which they appear in the available permissions list for the given interface.

func (*PromptDB) Close

func (pdb *PromptDB) Close() error

Close removes all outstanding prompts and records a notice for each one.

This should be called when snapd is shutting down, to notify prompt clients that the given prompts are no longer awaiting a reply.

func (*PromptDB) HandleNewRule

func (pdb *PromptDB) HandleNewRule(metadata *prompting.Metadata, constraints *prompting.RuleConstraints) ([]prompting.IDType, error)

HandleNewRule checks if any existing prompts are satisfied by the given rule contents and, if so, sends back a decision to their listener requests.

A prompt is satisfied by the given rule contents if the user, snap, interface, and path of the prompt match those of the rule, and all outstanding permissions are covered by permissions in the rule constraints or at least one of the outstanding permissions is covered by a rule permission which has an outcome of "deny".

Records a notice for any prompt which was satisfied, or which had some of its permissions satisfied by the rule contents. In the future, only the outstanding unsatisfied permissions of a partially-satisfied prompt must be satisfied for the prompt as a whole to be satisfied.

Returns the IDs of any prompts which were fully satisfied by the given rule contents.

Since rule is new, we don't check the expiration timestamps for any permissions, since any permissions with lifespan timespan were validated to have a non-zero duration, and we handle this rule as it was at its creation.

func (*PromptDB) PromptWithID

func (pdb *PromptDB) PromptWithID(user uint32, id prompting.IDType, clientActivity bool) (*Prompt, error)

PromptWithID returns the prompt with the given ID for the given user.

If clientActivity is true, reset the expiration timeout for prompts for the given user.

func (*PromptDB) Prompts

func (pdb *PromptDB) Prompts(user uint32, clientActivity bool) ([]*Prompt, error)

Prompts returns a slice of all outstanding prompts for the given user.

If clientActivity is true, reset the expiration timeout for prompts for the given user.

func (*PromptDB) Reply

func (pdb *PromptDB) Reply(user uint32, id prompting.IDType, outcome prompting.OutcomeType, clientActivity bool) (*Prompt, error)

Reply resolves the prompt with the given ID using the given outcome by sending a reply to all associated listener requests, then removing the prompt from the prompt DB.

Records a notice for the prompt, and returns the prompt's former contents.

If clientActivity is true, reset the expiration timeout for prompts for the given user.