groups

package
v0.1.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2020 License: BSD-3-Clause Imports: 14 Imported by: 5

README 

WORK IN PROGRESS. DO NOT DEPEND ON ANYTHING IN THIS DIRECTORY.

This directory defines types and interfaces pertaining to groups for access
control.

Group support is under development. Code and interfaces in this directory may
change at any time.

Documentation

Overview

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

Index

Constants

View Source 
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

View Source 
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)
)
View Source 
var ApproximationTypeAll = [...]ApproximationType{ApproximationTypeUnder, ApproximationTypeOver}

ApproximationTypeAll holds all labels for ApproximationType.

View Source 
var GroupDesc rpc.InterfaceDesc = descGroup

GroupDesc describes the Group interface.

View Source 
var GroupReaderDesc rpc.InterfaceDesc = descGroupReader

GroupReaderDesc describes the GroupReader interface.

Functions

func ErrorfCycleFound added in v0.1.10 

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

ErrorfCycleFound calls ErrCycleFound.Errorf with the supplied arguments.

func ErrorfExcessiveContention added in v0.1.10 

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

ErrorfExcessiveContention calls ErrExcessiveContention.Errorf with the supplied arguments.

func ErrorfNoBlessings added in v0.1.10 

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

ErrorfNoBlessings calls ErrNoBlessings.Errorf with the supplied arguments.

func MessageCycleFound added in v0.1.10 

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

MessageCycleFound calls ErrCycleFound.Message with the supplied arguments.

func MessageExcessiveContention added in v0.1.10 

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

MessageExcessiveContention calls ErrExcessiveContention.Message with the supplied arguments.

func MessageNoBlessings added in v0.1.10 

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

MessageNoBlessings calls ErrNoBlessings.Message with the supplied arguments.

func NewErrCycleFound 

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 

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 

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 added in v0.1.10 

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 added in v0.1.10 

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

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

func ParamsErrNoBlessings added in v0.1.10 

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

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

func PermissionsAuthorizer 

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

Types

type Approximation 

type Approximation struct {
	Reason  string
	Details string
}

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

func Match 

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 

func (x Approximation) VDLIsZero() bool

func (*Approximation) VDLRead 

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

func (Approximation) VDLReflect 

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

func (Approximation) VDLWrite 

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

type ApproximationType 

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 

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

ApproximationTypeFromString creates a ApproximationType from a string label.

func (*ApproximationType) Set 

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

Set assigns label to x.

func (ApproximationType) String 

func (x ApproximationType) String() string

String returns the string label of x.

func (ApproximationType) VDLIsZero 

func (x ApproximationType) VDLIsZero() bool

func (*ApproximationType) VDLRead 

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

func (ApproximationType) VDLReflect 

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

func (ApproximationType) VDLWrite 

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

type BlessingPatternChunk 

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 

func (x BlessingPatternChunk) VDLIsZero() bool

func (*BlessingPatternChunk) VDLRead 

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

func (BlessingPatternChunk) VDLReflect 

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

func (BlessingPatternChunk) VDLWrite 

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

type GetRequest 

type GetRequest struct {
}

func (GetRequest) VDLIsZero 

func (x GetRequest) VDLIsZero() bool

func (*GetRequest) VDLRead 

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

func (GetRequest) VDLReflect 

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

func (GetRequest) VDLWrite 

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

type GetResponse 

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

func (GetResponse) VDLIsZero 

func (x GetResponse) VDLIsZero() bool

func (*GetResponse) VDLRead 

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

func (GetResponse) VDLReflect 

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

func (GetResponse) VDLWrite 

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

type GroupClientMethods 

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 

type GroupClientStub interface {
	GroupClientMethods
}

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

func GroupClient 

func GroupClient(name string) GroupClientStub

GroupClient returns a client stub for Group.

type GroupReaderClientMethods 

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 

type GroupReaderClientStub interface {
	GroupReaderClientMethods
}

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

func GroupReaderClient 

func GroupReaderClient(name string) GroupReaderClientStub

GroupReaderClient returns a client stub for GroupReader.

type GroupReaderServerMethods 

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 

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

GroupReaderServerStub adds universal methods to GroupReaderServerStubMethods.

func GroupReaderServer 

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 

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 

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 

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

GroupServerStub adds universal methods to GroupServerStubMethods.

func GroupServer 

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 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.