Documentation ¶
Overview ¶
Package auth implements an access control model that is a subset of Linux's.
The auth package supports two kinds of access controls: user/group IDs and capabilities. Each resource in the security model is associated with a user namespace; "privileged" operations check that the operator's credentials have the required user/group IDs or capabilities within the user namespace of accessed resources.
Index ¶
- Constants
- Variables
- func ContextWithCredentials(ctx context.Context, creds *Credentials) context.Context
- func ThreadGroupIDFromContext(ctx context.Context) (tgid int32, ok bool)
- type CapabilitySet
- type Credentials
- func (c *Credentials) Fork() *Credentials
- func (c *Credentials) HasCapability(cp linux.Capability) bool
- func (c *Credentials) HasCapabilityIn(cp linux.Capability, ns *UserNamespace) bool
- func (c *Credentials) InGroup(kgid KGID) bool
- func (c *Credentials) NewChildUserNamespace() (*UserNamespace, error)
- func (c *Credentials) SetGID(gid GID) error
- func (c *Credentials) SetUID(uid UID) error
- func (c *Credentials) UseGID(gid GID) (KGID, error)
- func (c *Credentials) UseUID(uid UID) (KUID, error)
- type GID
- type IDMapEntry
- type KGID
- type KUID
- type TaskCapabilities
- type UID
- type UserNamespace
- func (ns *UserNamespace) GIDMap() []IDMapEntry
- func (ns *UserNamespace) MapFromKGID(kgid KGID) GID
- func (ns *UserNamespace) MapFromKUID(kuid KUID) UID
- func (ns *UserNamespace) MapToKGID(gid GID) KGID
- func (ns *UserNamespace) MapToKUID(uid UID) KUID
- func (ns *UserNamespace) Root() *UserNamespace
- func (ns *UserNamespace) SetGIDMap(ctx context.Context, entries []IDMapEntry) error
- func (ns *UserNamespace) SetUIDMap(ctx context.Context, entries []IDMapEntry) error
- func (ns *UserNamespace) UIDMap() []IDMapEntry
Constants ¶
const ( // CtxCredentials is a Context.Value key for Credentials. CtxCredentials contextID = iota // CtxThreadGroupID is the current thread group ID when a context represents // a task context. The value is represented as an int32. CtxThreadGroupID contextID = iota )
const ( // NoID is uint32(-1). -1 is consistently used as a special value, in Linux // and by extension in the auth package, to mean "no ID": // // - ID mapping returns -1 if the ID is not mapped. // // - Most set*id() syscalls accept -1 to mean "do not change this ID". NoID = math.MaxUint32 // OverflowUID is the default value of /proc/sys/kernel/overflowuid. The // "overflow UID" is usually [1] used when translating a user ID between // namespaces fails because the ID is not mapped. (We don't implement this // file, so the overflow UID is constant.) // // [1] "There is one notable case where unmapped user and group IDs are not // converted to the corresponding overflow ID value. When viewing a uid_map // or gid_map file in which there is no mapping for the second field, that // field is displayed as 4294967295 (-1 as an unsigned integer);" - // user_namespaces(7) OverflowUID = UID(65534) // OverflowGID is the group equivalent to OverflowUID. OverflowGID = GID(65534) // NobodyKUID is the user ID usually reserved for the least privileged user // "nobody". NobodyKUID = KUID(65534) // NobodyKGID is the group equivalent to NobodyKUID. NobodyKGID = KGID(65534) // RootKUID is the user ID usually used for the most privileged user "root". RootKUID = KUID(0) // RootKGID is the group equivalent to RootKUID. RootKGID = KGID(0) // RootUID is the root user. RootUID = UID(0) // RootGID is the root group. RootGID = GID(0) )
Variables ¶
var AllCapabilities = CapabilitySetOf(linux.CAP_LAST_CAP+1) - 1
AllCapabilities is a CapabilitySet containing all valid capabilities.
Functions ¶
func ContextWithCredentials ¶
func ContextWithCredentials(ctx context.Context, creds *Credentials) context.Context
ContextWithCredentials returns a copy of ctx carrying creds.
Types ¶
type CapabilitySet ¶
type CapabilitySet uint64
A CapabilitySet is a set of capabilities implemented as a bitset. The zero value of CapabilitySet is a set containing no capabilities.
func CapabilitySetOf ¶
func CapabilitySetOf(cp linux.Capability) CapabilitySet
CapabilitySetOf returns a CapabilitySet containing only the given capability.
func CapabilitySetOfMany ¶
func CapabilitySetOfMany(cps []linux.Capability) CapabilitySet
CapabilitySetOfMany returns a CapabilitySet containing the given capabilities.
type Credentials ¶
type Credentials struct { // Real/effective/saved user/group IDs in the root user namespace. None of // these should ever be NoID. RealKUID KUID EffectiveKUID KUID SavedKUID KUID RealKGID KGID EffectiveKGID KGID SavedKGID KGID // Supplementary groups used by set/getgroups. // // ExtraKGIDs slices are immutable, allowing multiple Credentials with the // same ExtraKGIDs to share the same slice. ExtraKGIDs []KGID // The capability sets applicable to this set of credentials. PermittedCaps CapabilitySet InheritableCaps CapabilitySet EffectiveCaps CapabilitySet BoundingCaps CapabilitySet // KeepCaps is the flag for PR_SET_KEEPCAPS which allow capabilities to be // maintained after a switch from root user to non-root user via setuid(). KeepCaps bool // The user namespace associated with the owner of the credentials. UserNamespace *UserNamespace }
Credentials contains information required to authorize privileged operations in a user namespace.
+stateify savable
func CredentialsFromContext ¶
func CredentialsFromContext(ctx context.Context) *Credentials
CredentialsFromContext returns a copy of the Credentials used by ctx, or a set of Credentials with no capabilities if ctx does not have Credentials.
func NewAnonymousCredentials ¶
func NewAnonymousCredentials() *Credentials
NewAnonymousCredentials returns a set of credentials with no capabilities in any user namespace.
func NewRootCredentials ¶
func NewRootCredentials(ns *UserNamespace) *Credentials
NewRootCredentials returns a set of credentials with KUID and KGID 0 (i.e. global root) in user namespace ns.
func NewUserCredentials ¶
func NewUserCredentials(kuid KUID, kgid KGID, extraKGIDs []KGID, capabilities *TaskCapabilities, ns *UserNamespace) *Credentials
NewUserCredentials returns a set of credentials based on the given UID, GIDs, and capabilities in a given namespace. If all arguments are their zero values, this returns the same credentials as NewRootCredentials.
func (*Credentials) Fork ¶
func (c *Credentials) Fork() *Credentials
Fork generates an identical copy of a set of credentials.
func (*Credentials) HasCapability ¶
func (c *Credentials) HasCapability(cp linux.Capability) bool
HasCapability returns true if c has capability cp in its user namespace.
func (*Credentials) HasCapabilityIn ¶
func (c *Credentials) HasCapabilityIn(cp linux.Capability, ns *UserNamespace) bool
HasCapabilityIn returns true if c has capability cp in ns.
func (*Credentials) InGroup ¶
func (c *Credentials) InGroup(kgid KGID) bool
InGroup returns true if c is in group kgid. Compare Linux's kernel/groups.c:in_group_p().
func (*Credentials) NewChildUserNamespace ¶
func (c *Credentials) NewChildUserNamespace() (*UserNamespace, error)
NewChildUserNamespace returns a new user namespace created by a caller with credentials c.
func (*Credentials) SetGID ¶
func (c *Credentials) SetGID(gid GID) error
SetGID translates the provided gid to the root user namespace and updates c's gids to it. This performs no permissions or capabilities checks, the caller is responsible for ensuring the calling context is permitted to modify c.
func (*Credentials) SetUID ¶
func (c *Credentials) SetUID(uid UID) error
SetUID translates the provided uid to the root user namespace and updates c's uids to it. This performs no permissions or capabilities checks, the caller is responsible for ensuring the calling context is permitted to modify c.
type GID ¶
type GID uint32
GID is a group ID in an unspecified user namespace.
+marshal slice:GIDSlice
func (GID) OrOverflow ¶
OrOverflow returns gid if it is valid and the overflow GID otherwise.
type IDMapEntry ¶
type IDMapEntry struct { // FirstID is the first ID in the range in the namespace. FirstID uint32 // FirstParentID is the first ID in the range in the parent namespace. FirstParentID uint32 // Length is the number of IDs in the range. Length uint32 }
An IDMapEntry represents a mapping from a range of contiguous IDs in a user namespace to an equally-sized range of contiguous IDs in the namespace's parent.
+stateify savable
type KGID ¶
type KGID uint32
KGID is a group ID in the root user namespace.
func (KGID) In ¶
func (kgid KGID) In(ns *UserNamespace) GID
In translates kgid into user namespace ns. If kgid is not mapped in ns, In returns NoID.
type KUID ¶
type KUID uint32
KUID is a user ID in the root user namespace.
func (KUID) In ¶
func (kuid KUID) In(ns *UserNamespace) UID
In translates kuid into user namespace ns. If kuid is not mapped in ns, In returns NoID.
type TaskCapabilities ¶
type TaskCapabilities struct { // Permitted is a limiting superset for the effective capabilities that // the thread may assume. PermittedCaps CapabilitySet // Inheritable is a set of capabilities preserved across an execve(2). InheritableCaps CapabilitySet // Effective is the set of capabilities used by the kernel to perform // permission checks for the thread. EffectiveCaps CapabilitySet // Bounding is a limiting superset for the capabilities that a thread // can add to its inheritable set using capset(2). BoundingCaps CapabilitySet // Ambient is a set of capabilities that are preserved across an // execve(2) of a program that is not privileged. AmbientCaps CapabilitySet }
TaskCapabilities represents all the capability sets for a task. Each of these sets is explained in greater detail in capabilities(7).
type UID ¶
type UID uint32
UID is a user ID in an unspecified user namespace.
+marshal
func (UID) OrOverflow ¶
OrOverflow returns uid if it is valid and the overflow UID otherwise.
type UserNamespace ¶
type UserNamespace struct {
// contains filtered or unexported fields
}
A UserNamespace represents a user namespace. See user_namespaces(7) for details.
+stateify savable
func NewRootUserNamespace ¶
func NewRootUserNamespace() *UserNamespace
NewRootUserNamespace returns a UserNamespace that is appropriate for a system's root user namespace.
func (*UserNamespace) GIDMap ¶
func (ns *UserNamespace) GIDMap() []IDMapEntry
GIDMap returns the group ID mappings configured for ns. If no mappings have been configured, GIDMap returns nil.
func (*UserNamespace) MapFromKGID ¶
func (ns *UserNamespace) MapFromKGID(kgid KGID) GID
MapFromKGID translates kgid, a GID in the root namespace, to a GID in ns.
func (*UserNamespace) MapFromKUID ¶
func (ns *UserNamespace) MapFromKUID(kuid KUID) UID
MapFromKUID translates kuid, a UID in the root namespace, to a UID in ns.
func (*UserNamespace) MapToKGID ¶
func (ns *UserNamespace) MapToKGID(gid GID) KGID
MapToKGID translates gid, a GID in ns, to a GID in the root namespace.
func (*UserNamespace) MapToKUID ¶
func (ns *UserNamespace) MapToKUID(uid UID) KUID
MapToKUID translates uid, a UID in ns, to a UID in the root namespace.
func (*UserNamespace) Root ¶
func (ns *UserNamespace) Root() *UserNamespace
Root returns the root of the user namespace tree containing ns.
func (*UserNamespace) SetGIDMap ¶
func (ns *UserNamespace) SetGIDMap(ctx context.Context, entries []IDMapEntry) error
SetGIDMap instructs ns to translate GIDs as specified by entries.
func (*UserNamespace) SetUIDMap ¶
func (ns *UserNamespace) SetUIDMap(ctx context.Context, entries []IDMapEntry) error
SetUIDMap instructs ns to translate UIDs as specified by entries.
Note: SetUIDMap does not place an upper bound on the number of entries, but Linux does. This restriction is implemented in SetUIDMap's caller, the implementation of /proc/[pid]/uid_map.
func (*UserNamespace) UIDMap ¶
func (ns *UserNamespace) UIDMap() []IDMapEntry
UIDMap returns the user ID mappings configured for ns. If no mappings have been configured, UIDMap returns nil.