identity

Documentation

Overview

Package identity contains code for managing security identities in Cilium. +groupName=pkg

Index

• Constants
• Variables
• func AddReservedIdentity(ni NumericIdentity, lbl string)
• func AddUserDefinedNumericIdentity(identity NumericIdentity, label string) error
• func DelReservedNumericIdentity(identity NumericIdentity) error
• func InitWellKnownIdentities()
• func IsUserReservedIdentity(id NumericIdentity) bool
• func IterateReservedIdentities(f func(key string, value NumericIdentity))
• func RequiresGlobalIdentity(lbls labels.Labels) bool
• func UpdateReservedIdentitiesMetrics()
• type IPIdentityPair
  • func (pair *IPIdentityPair) IsHost() bool
  • func (pair *IPIdentityPair) PrefixString() string
• type Identity
  • func LookupReservedIdentity(ni NumericIdentity) *Identity
  • func NewIdentity(id NumericIdentity, lbls labels.Labels) *Identity
  • func NewIdentityFromLabelArray(id NumericIdentity, lblArray labels.LabelArray) *Identity
  • func NewIdentityFromModel(base *models.Identity) *Identity
  • func (id *Identity) GetLabelsSHA256() string
  • func (id *Identity) GetModel() *models.Identity
  • func (id *Identity) IsFixed() bool
  • func (id *Identity) IsReserved() bool
  • func (id *Identity) IsWellKnown() bool
  • func (id *Identity) Sanitize()
  • func (id *Identity) String() string
  • func (id *Identity) StringID() string
• type NumericIdentity
  • func GetAllReservedIdentities() []NumericIdentity
  • func GetReservedID(name string) NumericIdentity
  • func ParseNumericIdentity(id string) (NumericIdentity, error)
  • func (id NumericIdentity) ClusterID() int
  • func (id NumericIdentity) HasLocalScope() bool
  • func (id NumericIdentity) IsReservedIdentity() bool
  • func (id NumericIdentity) String() string
  • func (id NumericIdentity) StringID() string
  • func (id NumericIdentity) Uint32() uint32

Constants

const (
	// ClusterIDShift specifies the number of bits the cluster ID will be
	// shifted
	ClusterIDShift = 16

	// LocalIdentityFlag is the bit in the numeric identity that identifies
	// a numeric identity to have local scope
	LocalIdentityFlag = NumericIdentity(1 << 24)

	// MinimalNumericIdentity represents the minimal numeric identity not
	// used for reserved purposes.
	MinimalNumericIdentity = NumericIdentity(256)

	// MinimalAllocationIdentity is the minimum numeric identity handed out
	// by the identity allocator.
	MinimalAllocationIdentity = MinimalNumericIdentity

	// MaximumAllocationIdentity is the maximum numeric identity handed out
	// by the identity allocator
	MaximumAllocationIdentity = NumericIdentity(^uint16(0))

	// UserReservedNumericIdentity represents the minimal numeric identity that
	// can be used by users for reserved purposes.
	UserReservedNumericIdentity = NumericIdentity(128)

	// InvalidIdentity is the identity assigned if the identity is invalid
	// or not determined yet
	InvalidIdentity = NumericIdentity(0)
)

Variables

var (

	// WellKnown identities stores global state of all well-known identities.
	WellKnown = wellKnownIdentities{}

	// ErrNotUserIdentity is an error returned for an identity that is not user
	// reserved.
	ErrNotUserIdentity = errors.New("not a user reserved identity")
)

var (
	// ReservedIdentityCache that maps all reserved identities from their
	// numeric identity to their corresponding identity.
	ReservedIdentityCache = map[NumericIdentity]*Identity{}
)

Functions

func AddReservedIdentity

func AddReservedIdentity(ni NumericIdentity, lbl string)

AddReservedIdentity adds the reserved numeric identity with the respective label into the map of reserved identity cache.

func AddUserDefinedNumericIdentity

func AddUserDefinedNumericIdentity(identity NumericIdentity, label string) error

AddUserDefinedNumericIdentity adds the given numeric identity and respective label to the list of reservedIdentities. If the numeric identity is not between UserReservedNumericIdentity and MinimalNumericIdentity it will return ErrNotUserIdentity. Is not safe for concurrent use.

func DelReservedNumericIdentity

func DelReservedNumericIdentity(identity NumericIdentity) error

DelReservedNumericIdentity deletes the given Numeric Identity from the list of reservedIdentities. If the numeric identity is not between UserReservedNumericIdentity and MinimalNumericIdentity it will return ErrNotUserIdentity. Is not safe for concurrent use.

func InitWellKnownIdentities

func InitWellKnownIdentities()

InitWellKnownIdentities establishes all well-known identities

func IsUserReservedIdentity

func IsUserReservedIdentity(id NumericIdentity) bool

IsUserReservedIdentity returns true if the given NumericIdentity belongs to the space reserved for users.

func IterateReservedIdentities

func IterateReservedIdentities(f func(key string, value NumericIdentity))

IterateReservedIdentities iterates over all reservedIdentities and executes the given function for each key, value pair in reservedIdentities.

func RequiresGlobalIdentity

func RequiresGlobalIdentity(lbls labels.Labels) bool

RequiresGlobalIdentity returns true if the label combination requires a global identity

func UpdateReservedIdentitiesMetrics

func UpdateReservedIdentitiesMetrics()

UpdateReservedIdentitiesMetrics updates identity metrics based on the reserved identities.

Types

type IPIdentityPair

type IPIdentityPair struct {
	IP       net.IP          `json:"IP"`
	Mask     net.IPMask      `json:"Mask"`
	HostIP   net.IP          `json:"HostIP"`
	ID       NumericIdentity `json:"ID"`
	Key      uint8           `json:"Key"`
	Metadata string          `json:"Metadata"`
}

IPIdentityPair is a pairing of an IP and the security identity to which that IP corresponds. May include an optional Mask which, if present, denotes that the IP represents a CIDR with the specified Mask.

WARNING - STABLE API This structure is written as JSON to the key-value store. Do NOT modify this structure in ways which are not JSON forward compatible.

func (*IPIdentityPair) IsHost

func (pair *IPIdentityPair) IsHost() bool

IsHost determines whether the IP in the pair represents a host (true) or a CIDR prefix (false)

func (*IPIdentityPair) PrefixString

func (pair *IPIdentityPair) PrefixString() string

PrefixString returns the IPIdentityPair's IP as either a host IP in the format w.x.y.z if 'host' is true, or as a prefix in the format the w.x.y.z/N if 'host' is false.

type Identity

type Identity struct {
	// Identity's ID.
	ID NumericIdentity `json:"id"`
	// Set of labels that belong to this Identity.
	Labels labels.Labels `json:"labels"`
	// SHA256 of labels.
	LabelsSHA256 string `json:"labelsSHA256"`

	// LabelArray contains the same labels as Labels in a form of a list, used
	// for faster lookup.
	LabelArray labels.LabelArray `json:"-"`

	// CIDRLabel is the primary identity label when the identity represents
	// a CIDR. The Labels field will consist of all matching prefixes, e.g.
	// 10.0.0.0/8
	// 10.0.0.0/7
	// 10.0.0.0/6
	// [...]
	// reserved:world
	//
	// The CIDRLabel field will only contain 10.0.0.0/8
	CIDRLabel labels.Labels `json:"-"`

	// ReferenceCount counts the number of references pointing to this
	// identity. This field is used by the owning cache of the identity.
	ReferenceCount int `json:"-"`
}

Identity is the representation of the security context for a particular set of labels.

func LookupReservedIdentity

func LookupReservedIdentity(ni NumericIdentity) *Identity

LookupReservedIdentity looks up a reserved identity by its NumericIdentity and returns it if found. Returns nil if not found.

func NewIdentity

func NewIdentity(id NumericIdentity, lbls labels.Labels) *Identity

NewIdentity creates a new identity

func NewIdentityFromLabelArray

func NewIdentityFromLabelArray(id NumericIdentity, lblArray labels.LabelArray) *Identity

NewIdentityFromLabelArray creates a new identity

func NewIdentityFromModel

func NewIdentityFromModel(base *models.Identity) *Identity

func (*Identity) GetLabelsSHA256

func (id *Identity) GetLabelsSHA256() string

GetLabelsSHA256 returns the SHA256 of the labels associated with the identity. The SHA is calculated if not already cached.

func (*Identity) GetModel

func (id *Identity) GetModel() *models.Identity

func (*Identity) IsFixed

func (id *Identity) IsFixed() bool

IsFixed returns whether the identity represents a fixed identity (true), or not (false).

func (*Identity) IsReserved

func (id *Identity) IsReserved() bool

IsReserved returns whether the identity represents a reserved identity (true), or not (false).

func (*Identity) IsWellKnown

func (id *Identity) IsWellKnown() bool

IsWellKnown returns whether the identity represents a well known identity (true), or not (false).

func (*Identity) Sanitize

func (id *Identity) Sanitize()

Sanitize takes a partially initialized Identity (for example, deserialized from json) and reconstitutes the full object from what has been restored.

func (*Identity) String

func (id *Identity) String() string

StringID returns the identity identifier as string

func (*Identity) StringID

func (id *Identity) StringID() string

StringID returns the identity identifier as string

type NumericIdentity

type NumericIdentity uint32

NumericIdentity is the numeric representation of a security identity.

Bits:

 0-15: identity identifier
16-23: cluster identifier
   24: LocalIdentityFlag: Indicates that the identity has a local scope

const (
	// IdentityUnknown represents an unknown identity
	IdentityUnknown NumericIdentity = iota

	// ReservedIdentityHost represents the local host
	ReservedIdentityHost

	// ReservedIdentityWorld represents any endpoint outside of the cluster
	ReservedIdentityWorld

	// ReservedIdentityUnmanaged represents unmanaged endpoints.
	ReservedIdentityUnmanaged

	// ReservedIdentityHealth represents the local cilium-health endpoint
	ReservedIdentityHealth

	// ReservedIdentityInit is the identity given to endpoints that have not
	// received any labels yet.
	ReservedIdentityInit

	// ReservedETCDOperator is the reserved identity used for the etcd-operator
	// managed by Cilium.
	ReservedETCDOperator NumericIdentity = 100

	// ReservedCiliumKVStore is the reserved identity used for the kvstore
	// managed by Cilium (etcd-operator).
	ReservedCiliumKVStore NumericIdentity = 101

	// ReservedKubeDNS is the reserved identity used for kube-dns.
	ReservedKubeDNS NumericIdentity = 102

	// ReservedEKSKubeDNS is the reserved identity used for kube-dns on EKS
	ReservedEKSKubeDNS NumericIdentity = 103

	// ReservedCoreDNS is the reserved identity used for CoreDNS
	ReservedCoreDNS NumericIdentity = 104

	// ReservedCiliumOperator is the reserved identity used for the Cilium operator
	ReservedCiliumOperator NumericIdentity = 105

	// ReservedEKSCoreDNS is the reserved identity used for CoreDNS on EKS
	ReservedEKSCoreDNS NumericIdentity = 106

	// ReservedCiliumEtcdOperator is the reserved identity used for the Cilium etcd operator
	ReservedCiliumEtcdOperator NumericIdentity = 107
)

func GetAllReservedIdentities

func GetAllReservedIdentities() []NumericIdentity

GetAllReservedIdentities returns a list of all reserved numeric identities.

func GetReservedID

func GetReservedID(name string) NumericIdentity

func ParseNumericIdentity

func ParseNumericIdentity(id string) (NumericIdentity, error)

func (NumericIdentity) ClusterID

func (id NumericIdentity) ClusterID() int

ClusterID returns the cluster ID associated with the identity

func (NumericIdentity) HasLocalScope

func (id NumericIdentity) HasLocalScope() bool

HasLocalScope returns true if the identity has a local scope

func (NumericIdentity) IsReservedIdentity

func (id NumericIdentity) IsReservedIdentity() bool

IsReservedIdentity returns whether id is one of the special reserved identities.

func (NumericIdentity) String

func (id NumericIdentity) String() string

func (NumericIdentity) StringID

func (id NumericIdentity) StringID() string

func (NumericIdentity) Uint32

func (id NumericIdentity) Uint32() uint32

Uint32 normalizes the ID for use in BPF program.