access

Documentation

Overview

Package access parses Access and Group files.

If a '#' character is present in a Group or Access file the remainder of that line is ignored.

Each line of an Access file specifies a set of rights and the users and/or groups to be granted those rights:

<right>[, <right>]: <user/group>[, <user/group>, ...]

Example:

Read,List: user@domain,com, friends
Write: user@domain.com, joe@domain.com
Delete: user@domain.com # This is a comment.

Each line of a Group file specifies a user or group to be included in the group:

<user/group>

Example:

anne@domain.com # A user.
joe@domain.com
admins # A group defined in this user's tree.

Index

• Constants
• Variables
• func AddGroup(pathName upspin.PathName, contents []byte) error
• func IsAccessControlFile(pathName upspin.PathName) bool
• func IsAccessFile(pathName upspin.PathName) bool
• func IsGroupFile(pathName upspin.PathName) bool
• func ParseGroup(parsed path.Parsed, contents []byte) (group []path.Parsed, err error)
• func RemoveGroup(pathName upspin.PathName) error
• type Access
  • func New(pathName upspin.PathName) (*Access, error)
  • func Parse(pathName upspin.PathName, data []byte) (*Access, error)
  • func UnmarshalJSON(name upspin.PathName, jsonAccess []byte) (*Access, error)
  • func (a *Access) Can(requester upspin.UserName, right Right, pathName upspin.PathName, ...) (bool, error)
  • func (a *Access) IsReadableByAll() bool
  • func (a *Access) List(right Right) []path.Parsed
  • func (a *Access) MarshalJSON() ([]byte, error)
  • func (a *Access) Path() upspin.PathName
  • func (a *Access) Users(right Right, load func(upspin.PathName) ([]byte, error)) ([]upspin.UserName, error)
• type Right
  • func (r Right) String() string

Constants

const (
	// AccessFile is the base name of an access control file.
	AccessFile = "Access"

	// GroupDir is the base name of the directory of group files in the user root.
	GroupDir = "Group"
)

const (
	// All is a shorthand for AllUsers. Its appearance in a user list
	// grants access to everyone who can authenticate to the Upspin system.
	// This constant can be used in Access files, but will always be expanded
	// to the full name ("all@upspin.io") when returned from Access.Users
	// and such.
	// If it is present with the Read or "*" rights, it must be the only read write
	// explicitly granted. (Another user can have "*" rights.)
	// All is not allowed to be present in Group files.
	All = "all" // Case is ignored, so "All", "ALL", etc. also work.

	// AllUsers is a reserved Upspin name and is not valid in the text of an
	// Access file. It is the user name that is substituted for the
	// shorthand "all" in a user list. See the comment about All for more
	// details. Its appearance in a user list grants access to everyone who
	// can authenticate to the Upspin system.
	AllUsers upspin.UserName = "all@upspin.io"
)

Variables

var ErrPermissionDenied = errors.E(errors.Permission)

ErrPermissionDenied is a predeclared error reporting that a permission check has failed. It is not used in this package but is commonly used in its clients.

Functions

func AddGroup

func AddGroup(pathName upspin.PathName, contents []byte) error

AddGroup installs a group with the specified name and textual contents, which should have been read from the group file with that name. If the group is already known, its definition is replaced.

func IsAccessControlFile

func IsAccessControlFile(pathName upspin.PathName) bool

IsAccessControlFile reports whether the pathName represents a file used for access control. At the moment that means either an Access or a Group file.

func IsAccessFile

func IsAccessFile(pathName upspin.PathName) bool

IsAccessFile reports whether the pathName ends in a file named Access, which is special.

func IsGroupFile

func IsGroupFile(pathName upspin.PathName) bool

IsGroupFile reports whether the pathName contains a directory in the root named Group, which is special.

func ParseGroup

func ParseGroup(parsed path.Parsed, contents []byte) (group []path.Parsed, err error)

ParseGroup parses a group file but does not call AddGroup to install it.

func RemoveGroup

func RemoveGroup(pathName upspin.PathName) error

RemoveGroup undoes the installation of a group added by AddGroup. It returns an error if the path is bad or the group is not present.

Types

type Access

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

Access represents a parsed Access file.

func New

func New(pathName upspin.PathName) (*Access, error)

New returns a new Access granting the owner of pathName all rights. It represents rights equivalent to the those granted to the owner if no Access files are present in the owner's tree.

func Parse

func Parse(pathName upspin.PathName, data []byte) (*Access, error)

Parse parses the contents of the path name, in data, and returns the parsed Access.

func UnmarshalJSON

func UnmarshalJSON(name upspin.PathName, jsonAccess []byte) (*Access, error)

UnmarshalJSON returns an Access given its path name and its JSON encoding.

func (*Access) Can

func (a *Access) Can(requester upspin.UserName, right Right, pathName upspin.PathName, load func(upspin.PathName) ([]byte, error)) (bool, error)

Can reports whether the requesting user can access the file using the specified right according to the rules of the Access file. It also interprets the rules that the owner can always Read and List, and only the owner can create or modify Access and Group files.

The rights are applied to the path itself. For instance, for Create the question is whether the user can create the named file, not whether the user has Create rights in the directory with that name. Similarly, for List the question is whether the user can list the status of this file, or if it is a directory, list the contents of that directory. It is the caller's responsibility to apply the correct Access file to the question, and separately to verify issues such as attempts to write to a directory rather than a file.

The method loads Group files as needed by calling the provided function to read each file's contents.

If a Group file cannot be loaded or parsed that failure is reported only if the requester does not match any names that can be found in the Access file or other Group files.

func (*Access) IsReadableByAll

func (a *Access) IsReadableByAll() bool

IsReadableByAll reports whether the Access file has read:all or read:all@upspin.io

func (*Access) List

func (a *Access) List(right Right) []path.Parsed

List returns the list of users and groups granted the specified right. Unlike the Users method, List returns the original unexpanded members from the Access file. In particular, groups appear as their original group names rather than as the users they represent. The returned values are parsed path names. If they are roots, they represent users; otherwise they represent groups. List is useful mainly for diagnosing permission problems; the Users method has more quotidian uses.

func (*Access) MarshalJSON

func (a *Access) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON-encoded representation of this Access struct.

func (*Access) Path

func (a *Access) Path() upspin.PathName

Path returns the full path name of the file that was parsed.

func (*Access) Users

func (a *Access) Users(right Right, load func(upspin.PathName) ([]byte, error)) ([]upspin.UserName, error)

Users returns the user names granted a given right according to the rules of the Access file. It also interprets the rule that the owner can always Read and List. Users loads group files as needed by calling the provided function to read each file's contents.

type Right

type Right int

A Right represents a particular access permission: reading, writing, etc.

const (
	Invalid Right = iota - 1
	Read
	Write
	List
	Create
	Delete

	AllRights // The superset of rights, written as '*'.
	AnyRight  // All users holding any right, used from WhichAccess.
)

All the Rights constants.

func (Right) String

func (r Right) String() string

String returns a textual representation of the right.