acl

README

go-acl

Go support for Access Control Lists

---

Minimum Requirements

• minimum supported compiler version is Go 1.9

Documentation

Overview

Package acl implements POSIX.1e draft 17-compliant manipulation of access control lists (ACLs). See the acl manpage for details: http://linux.die.net/man/5/acl

Currently, only Linux is supported. On systems which are not supported, all calls will return the error syscall.ENOTSUP.

Index

• Constants
• func Add(path string, entries ...Entry) error
• func FAdd(f *os.File, entries ...Entry) error
• func FSet(f *os.File, acl ACL) error
• func FSetDefault(f *os.File, acl ACL) error
• func Set(path string, acl ACL) error
• func SetDefault(path string, acl ACL) error
• func ToUnix(a ACL) os.FileMode
• type ACL
  • func FGet(f *os.File) (ACL, error)
  • func FGetDefault(f *os.File) (ACL, error)
  • func FromUnix(perms os.FileMode) ACL
  • func Get(path string) (ACL, error)
  • func GetDefault(path string) (ACL, error)
  • func (a ACL) IsValid() bool
  • func (a ACL) String() string
  • func (a ACL) StringLong() string
• type Entry
  • func (e Entry) String() string
  • func (e Entry) StringLong() string
• type Tag
  • func (t Tag) String() string
  • func (t Tag) StringLong() string

Constants

const (
	TagUserObj  Tag = tagUserObj  // Permissions of the file owner
	TagUser         = tagUser     // Permissions of a specified user
	TagGroupObj     = tagGroupObj // Permissions of the file group
	TagGroup        = tagGroup    // Permissions of a specified group

	// Maximum allowed access rights of any entry
	// with the tag TagUser, TagGroupObj, or TagGroup
	TagMask  = tagMask
	TagOther = tagOther // Permissions of a process not matching any other entry
)

Functions

func Add

func Add(path string, entries ...Entry) error

Add adds the given entries to the ACL on path. Any matching entries that exist on the file will be overwritten. Two entries match if they have the same tag (and, if that tag is TagUser or TagGroup, they also have the same qualifier).

In order to ensure that the new ACL is valid, after being calculated from the old ACL and the new entries, the new ACL is modified as follows: If the ACL includes named user or group entries (with the tags TagUser or TagGroup) but no mask entry, a mask entry is added. This entry's permissions are the union of all permissions affected by the entry (namely, all entries with the tags TagUser, TagGroup, or TagGroupObj).

func FAdd

func FAdd(f *os.File, entries ...Entry) error

FAdd adds the given entries to the ACL like Add, but on an *os.File

func FSet

func FSet(f *os.File, acl ACL) error

FSet sets the access ACL on an *os.File, returning any error encountered.

func FSetDefault

func FSetDefault(f *os.File, acl ACL) error

FSetDefault sets the default ACL on an *os.File, returning any error encountered.

func Set

func Set(path string, acl ACL) error

Set sets the access ACL on path, returning any error encountered.

func SetDefault

func SetDefault(path string, acl ACL) error

SetDefault sets the default ACL on path, returning any error encountered.

func ToUnix

func ToUnix(a ACL) os.FileMode

ToUnix returns the unix permissions bitmask encoded by a. If a is not valid as defined by a.IsValid, the behavior of ToUnix is undefined.

Types

type ACL

type ACL []Entry

ACL represents an access control list as defined in the POSIX.1e draft standard. If an ACL is not valid (see the IsValid method), the behavior of the functions and methods of this package is undefined.

func FGet

func FGet(f *os.File) (ACL, error)

FGet retrieves the access ACL associated with an *os.File, returning any error encountered.

func FGetDefault

func FGetDefault(f *os.File) (ACL, error)

FGetDefault retrieves the default ACL associated with an *os.File, returning any error encountered.

func FromUnix

func FromUnix(perms os.FileMode) ACL

FromUnix generates an ACL equivalent to the given unix permissions bitmask. All non-permission bits in perms are ignored.

func Get

func Get(path string) (ACL, error)

Get retrieves the access ACL associated with path, returning any error encountered.

func GetDefault

func GetDefault(path string) (ACL, error)

GetDefault retrieves the default ACL associated with path, returning any error encountered.

func (ACL) IsValid

func (a ACL) IsValid() bool

IsValid returns whether a is a valid ACL as defined by the POSIX.1e draft standard.

Specifically, a valid ACL must conform to the following rules:

• it contains exactly one entry each with the tag TagUserObj, TagGroupObj, and TagOther
• it may contain zero or more entries with the tags TagUser or TagGroup
• if it contains any entries with the tag TagUser or TagGroup, it must contain exactly one entry with the tag TagMask; otherwise, such an entry is optional (there can be zero or one)
• all qualifiers must be unique among entries of the same tag type (TagUser or TagGroup)

func (ACL) String

func (a ACL) String() string

String implements the POSIX.1e short text form. For example:

u::rwx,g::r-x,o::---,u:dvader:r--,m::r--

This output is produced by an ACL in which the file owner has read, write, and execute; the file group has read and execute; other has no permissions; the user dvader has read; and the mask is read.

func (ACL) StringLong

func (a ACL) StringLong() string

StringLong implements the POSIX.1e long text form. The long text form of the example given above is:

user::rwx
group::r-x
other::---
user:dvader:r--
mask::r--

type Entry

type Entry struct {
	Tag Tag

	// The Qualifier specifies what entity (user or group)
	// this entry applies to. If the Tag is TagUser, it is
	// a UID; if the Tag is TagGroup, it is a GID; otherwise
	// the field is ignored. Note that the qualifier must
	// be a UID or GID - it cannot be, for example, a user name.
	Qualifier string

	// ACL permissions are taken from a traditional rwx
	// (read/write/execute) permissions vector. The Perms
	// field stores these as the lowest three bits -
	// the bits in any higher positions are ignored.
	Perms os.FileMode
}

Entry represents an entry in an ACL.

func (Entry) String

func (e Entry) String() string

String implements the POSIX.1e short text form.

func (Entry) StringLong

func (e Entry) StringLong() string

StringLong implements the POSIX.1e long text form.

type Tag

type Tag tag

Tag is the type of an ACL entry tag.

func (Tag) String

func (t Tag) String() string

String implements the POSIX.1e short text form.

func (Tag) StringLong

func (t Tag) StringLong() string

StringLong implements the POSIX.1e long text form.