| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| // Package permissions defines an interface for managing access control |
| // permissions. |
| package permissions |
| |
| import ( |
| "v.io/v23/security/access" |
| ) |
| |
| // 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 Object 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(perms access.Permissions, version string) error {access.Admin} |
| |
| // 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() (perms access.Permissions, version string | error) {access.Admin} |
| } |