permissions

Documentation

Overview

Package permissions defines an interface for managing access control permissions.

Index

• Variables
• type ObjectClientMethods
• type ObjectClientStub
  • func ObjectClient(name string) ObjectClientStub
• type ObjectServerMethods
• type ObjectServerStub
  • func ObjectServer(impl ObjectServerMethods) ObjectServerStub
• type ObjectServerStubMethods

Variables

var ObjectDesc rpc.InterfaceDesc = descObject

ObjectDesc describes the Object interface.

Types

type ObjectClientMethods

type ObjectClientMethods interface {
	// SetPermissions replaces the current Permissions for an object.  version
	// allows for optional, optimistic concurrency control.  If non-empty,
	// version's value must come from GetPermissions.  If any client has
	// successfully called SetPermissions in the meantime, the version will be
	// stale and SetPermissions will fail.  If empty, SetPermissions performs an
	// unconditional update.
	//
	// Permissions objects are expected to be small.  It is up to the
	// implementation to define the exact limit, though it should probably be
	// around 100KB.  Large lists of principals can be represented concisely using
	// blessings.
	//
	// There is some ambiguity when calling SetPermissions on a mount point.
	// Does it affect the mount itself or does it affect the service endpoint
	// that the mount points to?  The chosen behavior is that it affects the
	// service endpoint.  To modify the mount point's Permissions, use
	// ResolveToMountTable to get an endpoint and call SetPermissions on that.
	// This means that clients must know when a name refers to a mount point to
	// change its Permissions.
	SetPermissions(_ *context.T, perms access.Permissions, version string, _ ...rpc.CallOpt) error
	// GetPermissions returns the complete, current Permissions for an object. The
	// returned version can be passed to a subsequent call to SetPermissions for
	// optimistic concurrency control. A successful call to SetPermissions will
	// invalidate version, and the client must call GetPermissions again to get
	// the current version.
	GetPermissions(*context.T, ...rpc.CallOpt) (perms access.Permissions, version string, _ error)
}

ObjectClientMethods is the client interface containing Object methods.

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}
}

type ObjectClientStub

type ObjectClientStub interface {
	ObjectClientMethods
	rpc.UniversalServiceMethods
}

ObjectClientStub adds universal methods to ObjectClientMethods.

func ObjectClient

func ObjectClient(name string) ObjectClientStub

ObjectClient returns a client stub for Object.

type ObjectServerMethods

type ObjectServerMethods interface {
	// SetPermissions replaces the current Permissions for an object.  version
	// allows for optional, optimistic concurrency control.  If non-empty,
	// version's value must come from GetPermissions.  If any client has
	// successfully called SetPermissions in the meantime, the version will be
	// stale and SetPermissions will fail.  If empty, SetPermissions performs an
	// unconditional update.
	//
	// Permissions objects are expected to be small.  It is up to the
	// implementation to define the exact limit, though it should probably be
	// around 100KB.  Large lists of principals can be represented concisely using
	// blessings.
	//
	// There is some ambiguity when calling SetPermissions on a mount point.
	// Does it affect the mount itself or does it affect the service endpoint
	// that the mount points to?  The chosen behavior is that it affects the
	// service endpoint.  To modify the mount point's Permissions, use
	// ResolveToMountTable to get an endpoint and call SetPermissions on that.
	// This means that clients must know when a name refers to a mount point to
	// change its Permissions.
	SetPermissions(_ *context.T, _ rpc.ServerCall, perms access.Permissions, version string) error
	// GetPermissions returns the complete, current Permissions for an object. The
	// returned version can be passed to a subsequent call to SetPermissions for
	// optimistic concurrency control. A successful call to SetPermissions will
	// invalidate version, and the client must call GetPermissions again to get
	// the current version.
	GetPermissions(*context.T, rpc.ServerCall) (perms access.Permissions, version string, _ error)
}

ObjectServerMethods is the interface a server writer implements for Object.

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}
}

type ObjectServerStub

type ObjectServerStub interface {
	ObjectServerStubMethods
	// Describe the Object interfaces.
	Describe__() []rpc.InterfaceDesc
}

ObjectServerStub adds universal methods to ObjectServerStubMethods.

func ObjectServer

func ObjectServer(impl ObjectServerMethods) ObjectServerStub

ObjectServer returns a server stub for Object. It converts an implementation of ObjectServerMethods into an object that may be used by rpc.Server.

type ObjectServerStubMethods

type ObjectServerStubMethods ObjectServerMethods

ObjectServerStubMethods is the server interface containing Object methods, as expected by rpc.Server. There is no difference between this interface and ObjectServerMethods since there are no streaming methods.