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 (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
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 ¶
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 ¶
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 ¶
IsAccessFile reports whether the pathName ends in a file named Access, which is special.
func IsGroupFile ¶
IsGroupFile reports whether the pathName contains a directory in the root named Group, which is special.
func ParseGroup ¶
ParseGroup parses a group file but does not call AddGroup to install it.
func RemoveGroup ¶
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 ¶
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 UnmarshalJSON ¶
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 ¶
IsReadableByAll reports whether the Access file has read:all or read:all@upspin.io
func (*Access) List ¶
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 ¶
MarshalJSON returns a JSON-encoded representation of this Access struct.
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.
Source Files