v.io: v.io/v23/services/groups Index | Files

package groups

import "v.io/v23/services/groups"

Package groups defines interfaces for managing access control groups. Groups can be referenced by BlessingPatterns (e.g. in AccessLists). nolint:golint

Index

Package Files

authorizer.go groups.vdl.go pattern.go

Constants

const (
    GroupStart = "<grp:" // GroupStart indicates the start of a group name in a blessing pattern.
    GroupEnd   = ">"     // GroupEnd indicates the end of a group name in a blessing pattern.
)

Variables

var (
    ErrNoBlessings         = verror.NewIDAction("v.io/v23/services/groups.NoBlessings", verror.NoRetry)
    ErrExcessiveContention = verror.NewIDAction("v.io/v23/services/groups.ExcessiveContention", verror.RetryBackoff)
    ErrCycleFound          = verror.NewIDAction("v.io/v23/services/groups.CycleFound", verror.NoRetry)
)
var ApproximationTypeAll = [...]ApproximationType{ApproximationTypeUnder, ApproximationTypeOver}

ApproximationTypeAll holds all labels for ApproximationType.

var GroupDesc rpc.InterfaceDesc = descGroup

GroupDesc describes the Group interface.

var GroupReaderDesc rpc.InterfaceDesc = descGroupReader

GroupReaderDesc describes the GroupReader interface.

func ErrorfCycleFound Uses

func ErrorfCycleFound(ctx *context.T, format string, name string, visited string) error

ErrorfCycleFound calls ErrCycleFound.Errorf with the supplied arguments.

func ErrorfExcessiveContention Uses

func ErrorfExcessiveContention(ctx *context.T, format string) error

ErrorfExcessiveContention calls ErrExcessiveContention.Errorf with the supplied arguments.

func ErrorfNoBlessings Uses

func ErrorfNoBlessings(ctx *context.T, format string) error

ErrorfNoBlessings calls ErrNoBlessings.Errorf with the supplied arguments.

func MessageCycleFound Uses

func MessageCycleFound(ctx *context.T, message string, name string, visited string) error

MessageCycleFound calls ErrCycleFound.Message with the supplied arguments.

func MessageExcessiveContention Uses

func MessageExcessiveContention(ctx *context.T, message string) error

MessageExcessiveContention calls ErrExcessiveContention.Message with the supplied arguments.

func MessageNoBlessings Uses

func MessageNoBlessings(ctx *context.T, message string) error

MessageNoBlessings calls ErrNoBlessings.Message with the supplied arguments.

func NewErrCycleFound Uses

func NewErrCycleFound(ctx *context.T, name string, visited string) error

NewErrCycleFound returns an error with the ErrCycleFound ID. Deprecated: this function will be removed in the future, use ErrorfCycleFound or MessageCycleFound instead.

func NewErrExcessiveContention Uses

func NewErrExcessiveContention(ctx *context.T) error

NewErrExcessiveContention returns an error with the ErrExcessiveContention ID. Deprecated: this function will be removed in the future, use ErrorfExcessiveContention or MessageExcessiveContention instead.

func NewErrNoBlessings Uses

func NewErrNoBlessings(ctx *context.T) error

NewErrNoBlessings returns an error with the ErrNoBlessings ID. Deprecated: this function will be removed in the future, use ErrorfNoBlessings or MessageNoBlessings instead.

func ParamsErrCycleFound Uses

func ParamsErrCycleFound(argumentError error) (verrorComponent string, verrorOperation string, name string, visited string, returnErr error)

ParamsErrCycleFound extracts the expected parameters from the error's ParameterList.

func ParamsErrExcessiveContention Uses

func ParamsErrExcessiveContention(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrExcessiveContention extracts the expected parameters from the error's ParameterList.

func ParamsErrNoBlessings Uses

func ParamsErrNoBlessings(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoBlessings extracts the expected parameters from the error's ParameterList.

func PermissionsAuthorizer Uses

func PermissionsAuthorizer(perms access.Permissions, tagType *vdl.Type) (security.Authorizer, error)

type Approximation Uses

type Approximation struct {
    Reason  string
    Details string
}

Approximation contains information about membership approximations made during a Relate call.

func Match Uses

func Match(ctx *context.T, p security.BlessingPattern, hint ApproximationType, visitedGroups map[string]struct{}, blessings map[string]struct{}) (map[string]struct{}, []Approximation)

Match matches blessing names against a pattern. It returns an empty array if the presented blessing names do not match the pattern, or a set of suffixes when the pattern is a prefix of the blessing names. Match approximates the result if any errors are encountered during the matching process.

Match assumes presented blessing names are valid. ctx is used to make any outgoing RPCs. TODO(hpucha): Enhance to add versioning, scrub Approximation content for privacy.

func (Approximation) VDLIsZero Uses

func (x Approximation) VDLIsZero() bool

func (*Approximation) VDLRead Uses

func (x *Approximation) VDLRead(dec vdl.Decoder) error

func (Approximation) VDLReflect Uses

func (Approximation) VDLReflect(struct {
    Name string `vdl:"v.io/v23/services/groups.Approximation"`
})

func (Approximation) VDLWrite Uses

func (x Approximation) VDLWrite(enc vdl.Encoder) error

type ApproximationType Uses

type ApproximationType int

ApproximationType defines the type of approximation desired when a Relate call encounters an error (inaccessible or undefined group in a blessing pattern, cyclic group definitions, storage errors, invalid patterns etc). "Under" is used for blessing patterns in "Allow" clauses in an AccessList, while "Over" is used for blessing patterns in "Deny" clauses.

const (
    ApproximationTypeUnder ApproximationType = iota
    ApproximationTypeOver
)

func ApproximationTypeFromString Uses

func ApproximationTypeFromString(label string) (x ApproximationType, err error)

ApproximationTypeFromString creates a ApproximationType from a string label. nolint:deadcode,unused

func (*ApproximationType) Set Uses

func (x *ApproximationType) Set(label string) error

Set assigns label to x.

func (ApproximationType) String Uses

func (x ApproximationType) String() string

String returns the string label of x.

func (ApproximationType) VDLIsZero Uses

func (x ApproximationType) VDLIsZero() bool

func (*ApproximationType) VDLRead Uses

func (x *ApproximationType) VDLRead(dec vdl.Decoder) error

func (ApproximationType) VDLReflect Uses

func (ApproximationType) VDLReflect(struct {
    Name string `vdl:"v.io/v23/services/groups.ApproximationType"`
    Enum struct{ Under, Over string }
})

func (ApproximationType) VDLWrite Uses

func (x ApproximationType) VDLWrite(enc vdl.Encoder) error

type BlessingPatternChunk Uses

type BlessingPatternChunk string

BlessingPatternChunk is a substring of a BlessingPattern. As with BlessingPatterns, BlessingPatternChunks may contain references to groups. However, they may be restricted in other ways. For example, in the future BlessingPatterns may support "$" terminators, but these may be disallowed for BlessingPatternChunks.

func (BlessingPatternChunk) VDLIsZero Uses

func (x BlessingPatternChunk) VDLIsZero() bool

func (*BlessingPatternChunk) VDLRead Uses

func (x *BlessingPatternChunk) VDLRead(dec vdl.Decoder) error

func (BlessingPatternChunk) VDLReflect Uses

func (BlessingPatternChunk) VDLReflect(struct {
    Name string `vdl:"v.io/v23/services/groups.BlessingPatternChunk"`
})

func (BlessingPatternChunk) VDLWrite Uses

func (x BlessingPatternChunk) VDLWrite(enc vdl.Encoder) error

type GetRequest Uses

type GetRequest struct {
}

func (GetRequest) VDLIsZero Uses

func (x GetRequest) VDLIsZero() bool

func (*GetRequest) VDLRead Uses

func (x *GetRequest) VDLRead(dec vdl.Decoder) error

func (GetRequest) VDLReflect Uses

func (GetRequest) VDLReflect(struct {
    Name string `vdl:"v.io/v23/services/groups.GetRequest"`
})

func (GetRequest) VDLWrite Uses

func (x GetRequest) VDLWrite(enc vdl.Encoder) error

type GetResponse Uses

type GetResponse struct {
    Entries map[BlessingPatternChunk]struct{}
}

func (GetResponse) VDLIsZero Uses

func (x GetResponse) VDLIsZero() bool

func (*GetResponse) VDLRead Uses

func (x *GetResponse) VDLRead(dec vdl.Decoder) error

func (GetResponse) VDLReflect Uses

func (GetResponse) VDLReflect(struct {
    Name string `vdl:"v.io/v23/services/groups.GetResponse"`
})

func (GetResponse) VDLWrite Uses

func (x GetResponse) VDLWrite(enc vdl.Encoder) error

type GroupClientMethods Uses

type GroupClientMethods interface {
    // GroupReader implements methods to read or query a group's membership
    // information.
    GroupReaderClientMethods
    // Object provides access control for Vanadium objects.
    //
    // Vanadium services implementing dynamic access control would typically embed
    // this interface and tag additional methods defined by the service with one of
    // Admin, Read, Write, Resolve etc. For example, the VDL definition of the
    // object would be:
    //
    //   package mypackage
    //
    //   import "v.io/v23/security/access"
    //   import "v.io/v23/services/permissions"
    //
    //   type MyObject interface {
    //     permissions.Object
    //     MyRead() (string, error) {access.Read}
    //     MyWrite(string) error    {access.Write}
    //   }
    //
    // If the set of pre-defined tags is insufficient, services may define their
    // own tag type and annotate all methods with this new type.
    //
    // Instead of embedding this Object interface, define SetPermissions and
    // GetPermissions in their own interface. Authorization policies will typically
    // respect annotations of a single type. For example, the VDL definition of an
    // object would be:
    //
    //  package mypackage
    //
    //  import "v.io/v23/security/access"
    //
    //  type MyTag string
    //
    //  const (
    //    Blue = MyTag("Blue")
    //    Red  = MyTag("Red")
    //  )
    //
    //  type MyObject interface {
    //    MyMethod() (string, error) {Blue}
    //
    //    // Allow clients to change access via the access.Object interface:
    //    SetPermissions(perms access.Permissions, version string) error         {Red}
    //    GetPermissions() (perms access.Permissions, version string, err error) {Blue}
    //  }
    permissions.ObjectClientMethods
    // Create creates a new group if it doesn't already exist.
    // If perms is nil, a default Permissions is used, providing Admin access to
    // the caller.
    // Create requires the caller to have Write permission at the GroupServer.
    Create(_ *context.T, perms access.Permissions, entries []BlessingPatternChunk, _ ...rpc.CallOpt) error
    // Delete deletes the group.
    // Permissions for all group-related methods except Create() are checked
    // against the Group object.
    Delete(_ *context.T, version string, _ ...rpc.CallOpt) error
    // Add adds an entry to the group.
    Add(_ *context.T, entry BlessingPatternChunk, version string, _ ...rpc.CallOpt) error
    // Remove removes an entry from the group.
    Remove(_ *context.T, entry BlessingPatternChunk, version string, _ ...rpc.CallOpt) error
}

GroupClientMethods is the client interface containing Group methods.

A group's version covers its Permissions as well as any other data stored in the group. Clients should treat versions as opaque identifiers. For both Get and Relate, if version is set and matches the Group's current version, the response will indicate that fact but will otherwise be empty.

type GroupClientStub Uses

type GroupClientStub interface {
    GroupClientMethods
}

GroupClientStub embeds GroupClientMethods and is a placeholder for additional management operations.

func GroupClient Uses

func GroupClient(name string) GroupClientStub

GroupClient returns a client stub for Group.

type GroupReaderClientMethods Uses

type GroupReaderClientMethods interface {
    // Relate determines the relationships between the provided blessing
    // names and the members of the group.
    //
    // Given an input set of blessing names and a group defined by a set of
    // blessing patterns S, for each blessing name B in the input, Relate(B)
    // returns a set of "remainders" consisting of every blessing name B"
    // such that there exists some B' for which B = B' B" and B' is in S,
    // and "" if B is a member of S.
    //
    // For example, if a group is defined as S = {n1, n1:n2, n1:n2:n3}, then
    // Relate(n1:n2) = {n2, ""}.
    //
    // reqVersion specifies the expected version of the group's membership
    // information. If this version is set and matches the Group's current
    // version, the response will indicate that fact but will otherwise be
    // empty.
    //
    // visitedGroups is the set of groups already visited in a particular
    // chain of Relate calls, and is used to detect the presence of
    // cycles. When a cycle is detected, it is treated just like any other
    // error, and the result is approximated.
    //
    // Relate also returns information about all the errors encountered that
    // resulted in approximations, if any.
    //
    // TODO(hpucha): scrub "Approximation" for preserving privacy. Flesh
    // versioning out further. Other args we may need: option to Get() the
    // membership set when allowed (to avoid an extra RPC), options related
    // to caching this information.
    Relate(_ *context.T, blessings map[string]struct{}, hint ApproximationType, reqVersion string, visitedGroups map[string]struct{}, _ ...rpc.CallOpt) (remainder map[string]struct{}, approximations []Approximation, version string, _ error)
    // Get returns all entries in the group.
    // TODO(sadovsky): Flesh out this API.
    Get(_ *context.T, req GetRequest, reqVersion string, _ ...rpc.CallOpt) (res GetResponse, version string, _ error)
}

GroupReaderClientMethods is the client interface containing GroupReader methods.

GroupReader implements methods to read or query a group's membership information.

type GroupReaderClientStub Uses

type GroupReaderClientStub interface {
    GroupReaderClientMethods
}

GroupReaderClientStub embeds GroupReaderClientMethods and is a placeholder for additional management operations.

func GroupReaderClient Uses

func GroupReaderClient(name string) GroupReaderClientStub

GroupReaderClient returns a client stub for GroupReader.

type GroupReaderServerMethods Uses

type GroupReaderServerMethods interface {
    // Relate determines the relationships between the provided blessing
    // names and the members of the group.
    //
    // Given an input set of blessing names and a group defined by a set of
    // blessing patterns S, for each blessing name B in the input, Relate(B)
    // returns a set of "remainders" consisting of every blessing name B"
    // such that there exists some B' for which B = B' B" and B' is in S,
    // and "" if B is a member of S.
    //
    // For example, if a group is defined as S = {n1, n1:n2, n1:n2:n3}, then
    // Relate(n1:n2) = {n2, ""}.
    //
    // reqVersion specifies the expected version of the group's membership
    // information. If this version is set and matches the Group's current
    // version, the response will indicate that fact but will otherwise be
    // empty.
    //
    // visitedGroups is the set of groups already visited in a particular
    // chain of Relate calls, and is used to detect the presence of
    // cycles. When a cycle is detected, it is treated just like any other
    // error, and the result is approximated.
    //
    // Relate also returns information about all the errors encountered that
    // resulted in approximations, if any.
    //
    // TODO(hpucha): scrub "Approximation" for preserving privacy. Flesh
    // versioning out further. Other args we may need: option to Get() the
    // membership set when allowed (to avoid an extra RPC), options related
    // to caching this information.
    Relate(_ *context.T, _ rpc.ServerCall, blessings map[string]struct{}, hint ApproximationType, reqVersion string, visitedGroups map[string]struct{}) (remainder map[string]struct{}, approximations []Approximation, version string, _ error)
    // Get returns all entries in the group.
    // TODO(sadovsky): Flesh out this API.
    Get(_ *context.T, _ rpc.ServerCall, req GetRequest, reqVersion string) (res GetResponse, version string, _ error)
}

GroupReaderServerMethods is the interface a server writer implements for GroupReader.

GroupReader implements methods to read or query a group's membership information.

type GroupReaderServerStub Uses

type GroupReaderServerStub interface {
    GroupReaderServerStubMethods
    // DescribeInterfaces the GroupReader interfaces.
    Describe__() []rpc.InterfaceDesc
}

GroupReaderServerStub adds universal methods to GroupReaderServerStubMethods.

func GroupReaderServer Uses

func GroupReaderServer(impl GroupReaderServerMethods) GroupReaderServerStub

GroupReaderServer returns a server stub for GroupReader. It converts an implementation of GroupReaderServerMethods into an object that may be used by rpc.Server.

type GroupReaderServerStubMethods Uses

type GroupReaderServerStubMethods GroupReaderServerMethods

GroupReaderServerStubMethods is the server interface containing GroupReader methods, as expected by rpc.Server. There is no difference between this interface and GroupReaderServerMethods since there are no streaming methods.

type GroupServerMethods Uses

type GroupServerMethods interface {
    // GroupReader implements methods to read or query a group's membership
    // information.
    GroupReaderServerMethods
    // Object provides access control for Vanadium objects.
    //
    // Vanadium services implementing dynamic access control would typically embed
    // this interface and tag additional methods defined by the service with one of
    // Admin, Read, Write, Resolve etc. For example, the VDL definition of the
    // object would be:
    //
    //   package mypackage
    //
    //   import "v.io/v23/security/access"
    //   import "v.io/v23/services/permissions"
    //
    //   type MyObject interface {
    //     permissions.Object
    //     MyRead() (string, error) {access.Read}
    //     MyWrite(string) error    {access.Write}
    //   }
    //
    // If the set of pre-defined tags is insufficient, services may define their
    // own tag type and annotate all methods with this new type.
    //
    // Instead of embedding this Object interface, define SetPermissions and
    // GetPermissions in their own interface. Authorization policies will typically
    // respect annotations of a single type. For example, the VDL definition of an
    // object would be:
    //
    //  package mypackage
    //
    //  import "v.io/v23/security/access"
    //
    //  type MyTag string
    //
    //  const (
    //    Blue = MyTag("Blue")
    //    Red  = MyTag("Red")
    //  )
    //
    //  type MyObject interface {
    //    MyMethod() (string, error) {Blue}
    //
    //    // Allow clients to change access via the access.Object interface:
    //    SetPermissions(perms access.Permissions, version string) error         {Red}
    //    GetPermissions() (perms access.Permissions, version string, err error) {Blue}
    //  }
    permissions.ObjectServerMethods
    // Create creates a new group if it doesn't already exist.
    // If perms is nil, a default Permissions is used, providing Admin access to
    // the caller.
    // Create requires the caller to have Write permission at the GroupServer.
    Create(_ *context.T, _ rpc.ServerCall, perms access.Permissions, entries []BlessingPatternChunk) error
    // Delete deletes the group.
    // Permissions for all group-related methods except Create() are checked
    // against the Group object.
    Delete(_ *context.T, _ rpc.ServerCall, version string) error
    // Add adds an entry to the group.
    Add(_ *context.T, _ rpc.ServerCall, entry BlessingPatternChunk, version string) error
    // Remove removes an entry from the group.
    Remove(_ *context.T, _ rpc.ServerCall, entry BlessingPatternChunk, version string) error
}

GroupServerMethods is the interface a server writer implements for Group.

A group's version covers its Permissions as well as any other data stored in the group. Clients should treat versions as opaque identifiers. For both Get and Relate, if version is set and matches the Group's current version, the response will indicate that fact but will otherwise be empty.

type GroupServerStub Uses

type GroupServerStub interface {
    GroupServerStubMethods
    // DescribeInterfaces the Group interfaces.
    Describe__() []rpc.InterfaceDesc
}

GroupServerStub adds universal methods to GroupServerStubMethods.

func GroupServer Uses

func GroupServer(impl GroupServerMethods) GroupServerStub

GroupServer returns a server stub for Group. It converts an implementation of GroupServerMethods into an object that may be used by rpc.Server.

type GroupServerStubMethods Uses

type GroupServerStubMethods GroupServerMethods

GroupServerStubMethods is the server interface containing Group methods, as expected by rpc.Server. There is no difference between this interface and GroupServerMethods since there are no streaming methods.

Package groups imports 14 packages (graph). Updated 2020-10-26. Refresh now. Tools for package owners.