package auth

import "gvisor.dev/gvisor/pkg/sentry/kernel/auth"

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 

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 implement this
	// file as read-only, 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)
)
const (
	// MaxKeyDescSize is the maximum size of the "Description" field of keys.
	// Corresponds to `KEY_MAX_DESC_SIZE` in Linux.
	MaxKeyDescSize = 4096
)

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.

func FixupVfsCapDataOnGet 

func FixupVfsCapDataOnGet(creds *Credentials, value string) (string, error)

FixupVfsCapDataOnGet may convert the given value to v2 file capabilities. It is analogous to security/commoncap.c:cap_inode_getsecurity().

func FixupVfsCapDataOnSet 

func FixupVfsCapDataOnSet(creds *Credentials, value string, kuid KUID, kgid KGID) (string, error)

FixupVfsCapDataOnSet may convert the given value to v3 file capabilities. It is analogous to security/commoncap.c:cap_convert_nscap().

func HandlePrivilegedRoot 

func HandlePrivilegedRoot(creds *Credentials, hasVFSCaps bool, filename string) bool

HandlePrivilegedRoot updates creds for a privileged root user as per `Capabilities and execution of programs by root` in capabilities(7). It returns true if the file effective bit should be considered set.

func HandleVfsCaps 

func HandleVfsCaps(vfsCaps linux.VfsNsCapData, creds *Credentials) (bool, bool, error)

HandleVfsCaps updates creds based on the given vfsCaps. It returns two booleans; the first indicates whether the effective flag is set, and the second second indicates whether the file capability is applied.

func ThreadGroupIDFromContext 

func ThreadGroupIDFromContext(ctx context.Context) (tgid int32, ok bool)

ThreadGroupIDFromContext returns the current thread group ID when ctx represents a task context.

func UpdateCredsForNewTask 

func UpdateCredsForNewTask(creds *Credentials, fileCaps string, filename string) error

UpdateCredsForNewTask updates creds for a new task as per capabilities(7).

func VfsCapDataOf 

func VfsCapDataOf(data []byte) (linux.VfsNsCapData, error)

VfsCapDataOf returns a VfsCapData containing the file capabilities for the given slice of bytes. For each field of the cap data, which are in the structure of either vfs_cap_data or vfs_ns_cap_data, the bytes are ordered in little endian.

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.

func (*CapabilitySet) Add 

func (cs *CapabilitySet) Add(cp linux.Capability)

Add adds the given capability to the CapabilitySet.

func (*CapabilitySet) Clear 

func (cs *CapabilitySet) Clear(cp linux.Capability)

Clear removes the given capability from the CapabilitySet.

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 CredentialsOrNilFromContext 

func CredentialsOrNilFromContext(ctx context.Context) *Credentials

CredentialsOrNilFromContext returns a copy of the Credentials used by ctx, or nil 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) HasCapabilityOnFile 

func (c *Credentials) HasCapabilityOnFile(cp linux.Capability, kuid KUID, kgid KGID) bool

HasCapabilityOnFile returns true if creds has the given capability with respect to a file with the given owning UID and GID, consistent with Linux's kernel/capability.c:capable_wrt_inode_uidgid().

func (*Credentials) HasKeyPermission 

func (c *Credentials) HasKeyPermission(k *Key, possessed *PossessedKeys, permission KeyPermission) bool

HasKeyPermission returns whether the credentials grant `permission` on `k`.

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) LoadSeccheckData 

func (c *Credentials) LoadSeccheckData(mask seccheck.FieldMask, info *pb.ContextData)

LoadSeccheckData sets credential data based on mask.

func (*Credentials) NewChildUserNamespace 

func (c *Credentials) NewChildUserNamespace() (*UserNamespace, error)

NewChildUserNamespace returns a new user namespace created by a caller with credentials c.

func (*Credentials) PossessedKeys 

func (c *Credentials) PossessedKeys(sessionKeyring, processKeyring, threadKeyring *Key) *PossessedKeys

PossessedKeys returns a new fully-expanded set of PossessedKeys. The keys passed in are the set of keys that a task directly possesses: session keyring, process keyring, thread keyring. Each key may be nil. PossessedKeys is short-lived; it should only live for so long as there are no changes to the KeySet or to any key permissions.

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.

func (*Credentials) UseGID 

func (c *Credentials) UseGID(gid GID) (KGID, error)

UseGID checks that c can use gid in its user namespace, then translates it to the root user namespace.

func (*Credentials) UseUID 

func (c *Credentials) UseUID(uid UID) (KUID, error)

UseUID checks that c can use uid in its user namespace, then translates it to the root user namespace.

The checks UseUID does are common, but you should verify that it's doing exactly what you want.

type GID 

type GID uint32

GID is a group ID in an unspecified user namespace.

+marshal slice:GIDSlice

func (GID) Ok 

func (gid GID) Ok() bool

Ok returns true if gid is not -1.

func (GID) OrOverflow 

func (gid GID) OrOverflow() GID

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.

func (KGID) Ok 

func (kgid KGID) Ok() bool

Ok returns true if kgid is not -1.

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.

func (KUID) Ok 

func (kuid KUID) Ok() bool

Ok returns true if kuid is not -1.

type Key 

type Key struct {
	// ID is the ID of the key, also often referred to as "serial number".
	// Note that key IDs passed in syscalls may be negative when they refer to
	// "special keys", sometimes also referred to as "shortcut IDs".
	// Key IDs of real instantiated keys are always > 0.
	// The key ID never changes and is unique within a KeySet (i.e. a user
	// namespace).
	// It must be chosen with cryptographic randomness to make enumeration
	// attacks harder.
	ID KeySerial

	// Description is a description of the key. It is also often referred to the
	// "name" of the key. Keys are canonically identified by their ID, but the
	// syscall ABI also allows look up keys by their description.
	// It may not be larger than `KeyMaxDescSize`.
	// Confusingly, the information returned by the KEYCTL_DESCRIBE operation,
	// which you'd think means "get the key description", actually returns a
	// superset of this `Description`.
	Description string
	// contains filtered or unexported fields
}

Key represents a key in the keyrings subsystem.

+stateify savable

func (*Key) KGID 

func (k *Key) KGID() KGID

KGID returns the KGID (group ID) of the key.

func (*Key) KUID 

func (k *Key) KUID() KUID

KUID returns the KUID (owner ID) of the key.

func (*Key) Permissions 

func (k *Key) Permissions() KeyPermissions

Permissions returns the permission bits of the key.

func (*Key) String 

func (k *Key) String() string

String is a human-friendly representation of the key. Notably, this is *not* the string returned to userspace when requested using `KEYCTL_DESCRIBE`.

func (*Key) Type 

func (*Key) Type() KeyType

Type returns the type of this key.

type KeyPermission 

type KeyPermission int

KeyPermission represents a permission on a key. 

const (
	KeyView KeyPermission = iota
	KeyRead
	KeyWrite
	KeySearch
	KeyLink
	KeySetAttr
)

List of known key permissions.

type KeyPermissions 

type KeyPermissions uint64

KeyPermissions is the full set of permissions on a single Key. 

const (
	// Default session keyring name.
	DefaultSessionKeyringName = "_ses"

	// Default permissions for unnamed session keyrings:
	// Possessors have full permissions.
	// Owners have view and read permissions.
	DefaultUnnamedSessionKeyringPermissions KeyPermissions = ((keyPermissionAll << keyPossessorPermissionsShift) |
		((keyPermissionView | keyPermissionRead) << keyOwnerPermissionsShift))

	// Default permissions for named session keyrings:
	// Possessors have full permissions.
	// Owners have view, read, and link permissions.
	DefaultNamedSessionKeyringPermissions KeyPermissions = ((keyPermissionAll << keyPossessorPermissionsShift) |
		((keyPermissionView | keyPermissionRead | keyPermissionLink) << keyOwnerPermissionsShift))
)

Default key settings.

func (KeyPermissions) String 

func (p KeyPermissions) String() string

String returns a human-readable version of the permission bits.

type KeySerial 

type KeySerial int32

KeySerial is a key ID type. Only strictly positive IDs are valid key IDs. The zero ID is meaningless but is specified when creating new keyrings. Strictly negative IDs are used for special key IDs which are internally translated to real key IDs (e.g. KEY_SPEC_SESSION_KEYRING is translated to the caller process's session keyring).

type KeySet 

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

KeySet is a set of keys.

+stateify savable

func (*KeySet) Do 

func (s *KeySet) Do(fn func(*LockedKeySet) error) error

Do executes the given function as a transaction on the KeySet. It returns the error that `fn` returns. This is the only function where functions that lock the KeySet.mu for writing may be called.

func (*KeySet) ForEach 

func (s *KeySet) ForEach(fn func(*Key) bool)

ForEach iterates over all keys. If `fn` returns true, iteration stops immediately. Callers must exercise care to only process keys to which they have access.

func (*KeySet) Lookup 

func (s *KeySet) Lookup(keyID KeySerial) (*Key, error)

Lookup looks up a key by ID. Callers must exercise care to verify that the key can be accessed with proper credentials.

type KeyType 

type KeyType string

KeyType is the type of a key. This is an enum, but is also exposed to userspace in KEYCTL_DESCRIBE. For this reason, it must match Linux. 

const (
	KeyTypeKeyring KeyType = "keyring"
)

List of known key types.

type LockedKeySet 

type LockedKeySet struct {
	*KeySet
}

LockedKeySet is a KeySet in a transaction. It exposes functions that can mutate the KeySet or its keys.

func (*LockedKeySet) Add 

func (s *LockedKeySet) Add(description string, creds *Credentials, perms KeyPermissions) (*Key, error)

Add adds a new Key to the KeySet.

func (*LockedKeySet) SetPerms 

func (s *LockedKeySet) SetPerms(key *Key, newPerms KeyPermissions)

SetPerms sets the permissions on a given key. The caller must have SetAttr permission on the key.

type PossessedKeys 

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

PossessedKeys is an opaque type used during key permission check. When iterating over all keys, the possessed set of keys should only be built once. Since key possession is a recursive property, it can be expensive to determine. PossessedKeys holds all possessed keys at the time it is computed. PossessedKeys is short-lived; it should only live for so long as there are no changes to the KeySet or to any key permissions.

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) Ok 

func (uid UID) Ok() bool

Ok returns true if uid is not -1.

func (UID) OrOverflow 

func (uid UID) OrOverflow() UID

OrOverflow returns uid if it is valid and the overflow UID otherwise.

type UserNamespace 

type UserNamespace struct {

	// Keys is the set of keys in this namespace.
	Keys KeySet
	// 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. Note that namespaces returned by separate calls to this function are *distinct* namespaces. Once a root namespace is created by this function, the returned value must be reused to refer to the same 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.

Source Files

auth.go capability_set.go context.go credentials.go id.go id_map.go id_map_functions.go key.go user_namespace.go

Version
v0.0.0-20250605235530-a6711d1e1dc6 (latest)
Published
Jun 5, 2025
Platform
linux/amd64
Imports
12 packages
Last checked
4 hours ago –

Tools for package owners.