1# -*- coding: utf-8 -*- 2# Copyright 2012 Google Inc. All Rights Reserved. 3# 4# Licensed under the Apache License, Version 2.0 (the "License"); 5# you may not use this file except in compliance with the License. 6# You may obtain a copy of the License at 7# 8# http://www.apache.org/licenses/LICENSE-2.0 9# 10# Unless required by applicable law or agreed to in writing, software 11# distributed under the License is distributed on an "AS IS" BASIS, 12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13# See the License for the specific language governing permissions and 14# limitations under the License. 15"""Additional help about Access Control Lists.""" 16 17from __future__ import absolute_import 18 19from gslib.help_provider import HelpProvider 20 21_DETAILED_HELP_TEXT = (""" 22<B>OVERVIEW</B> 23 Access Control Lists (ACLs) allow you to control who can read and write 24 your data, and who can read and write the ACLs themselves. 25 26 If not specified at the time an object is uploaded (e.g., via the gsutil cp 27 -a option), objects will be created with a default object ACL set on the 28 bucket (see "gsutil help defacl"). You can replace the ACL on an object 29 or bucket using the "gsutil acl set" command, or 30 modify the existing ACL using the "gsutil acl ch" command (see "gsutil help 31 acl"). 32 33 34<B>BUCKET VS OBJECT ACLS</B> 35 In Google Cloud Storage, the bucket ACL works as follows: 36 37 - Users granted READ access are allowed to list the bucket contents and read 38 bucket metadata other than its ACL. 39 40 - Users granted WRITE access are allowed READ access and also are allowed to 41 write and delete objects in that bucket, including overwriting previously 42 written objects. 43 44 - Users granted OWNER access are allowed WRITE access and also are allowed to 45 read and write the bucket's ACL. 46 47 The object ACL works as follows: 48 49 - Users granted READ access are allowed to read the object's data and 50 metadata. 51 52 - Users granted OWNER access are allowed READ access and also are allowed to 53 read and write the object's ACL. 54 55 A couple of points are worth noting, that sometimes surprise users: 56 57 1. There is no WRITE access for objects; attempting to set an ACL with WRITE 58 permission for an object will result in an error. 59 60 2. The bucket ACL plays no role in determining who can read objects; only the 61 object ACL matters for that purpose. This is different from how things 62 work in Linux file systems, where both the file and directory permission 63 control file read access. It also means, for example, that someone with 64 OWNER over the bucket may not have read access to objects in the bucket. 65 This is by design, and supports useful cases. For example, you might want 66 to set up bucket ownership so that a small group of administrators have 67 OWNER on the bucket (with the ability to delete data to control storage 68 costs), but not grant those users read access to the object data (which 69 might be sensitive data that should only be accessed by a different 70 specific group of users). 71 72 73<B>CANNED ACLS</B> 74 The simplest way to set an ACL on a bucket or object is using a "canned 75 ACL". The available canned ACLs are: 76 77 project-private 78 Gives permission to the project team based on their roles. Anyone who is 79 part of the team has READ permission, and project owners and project editors 80 have OWNER permission. This is the default ACL for newly created 81 buckets. This is also the default ACL for newly created objects unless the 82 default object ACL for that bucket has been changed. For more details see 83 "gsutil help projects". 84 85 private 86 Gives the requester (and only the requester) OWNER permission for a 87 bucket or object. 88 89 public-read 90 Gives all users (whether logged in or anonymous) READ permission. When 91 you apply this to an object, anyone on the Internet can read the object 92 without authenticating. 93 94 NOTE: By default, publicly readable objects are served with a Cache-Control 95 header allowing such objects to be cached for 3600 seconds. If you need to 96 ensure that updates become visible immediately, you should set a 97 Cache-Control header of "Cache-Control:private, max-age=0, no-transform" on 98 such objects. For help doing this, see 'gsutil help setmeta'. 99 100 NOTE: Setting a bucket ACL to public-read will remove all OWNER and WRITE 101 permissions from everyone except the project owner group. Setting an object 102 ACL to public-read will remove all OWNER and WRITE permissions from 103 everyone except the object owner. For this reason, we recommend using 104 the "acl ch" command to make these changes; see "gsutil help acl ch" for 105 details. 106 107 public-read-write 108 Gives all users READ and WRITE permission. This ACL applies only to buckets. 109 NOTE: Setting a bucket to public-read-write will allow anyone on the 110 Internet to upload anything to your bucket. You will be responsible for this 111 content. 112 113 NOTE: Setting a bucket ACL to public-read-write will remove all OWNER 114 permissions from everyone except the project owner group. Setting an object 115 ACL to public-read-write will remove all OWNER permissions from 116 everyone except the object owner. For this reason, we recommend using 117 the "acl ch" command to make these changes; see "gsutil help acl ch" for 118 details. 119 120 authenticated-read 121 Gives the requester OWNER permission and gives all authenticated 122 Google account holders READ permission. 123 124 bucket-owner-read 125 Gives the requester OWNER permission and gives the bucket owner READ 126 permission. This is used only with objects. 127 128 bucket-owner-full-control 129 Gives the requester OWNER permission and gives the bucket owner 130 OWNER permission. This is used only with objects. 131 132 133<B>ACL JSON</B> 134 When you use a canned ACL, it is translated into an JSON representation 135 that can later be retrieved and edited to specify more fine-grained 136 detail about who can read and write buckets and objects. By running 137 the "gsutil acl get" command you can retrieve the ACL JSON, and edit it to 138 customize the permissions. 139 140 As an example, if you create an object in a bucket that has no default 141 object ACL set and then retrieve the ACL on the object, it will look 142 something like this: 143 144 [ 145 { 146 "entity": "group-00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7", 147 "entityId": "00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7", 148 "role": "OWNER" 149 }, 150 { 151 "entity": "group-00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51", 152 "entityId": "00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51", 153 "role": "OWNER" 154 }, 155 { 156 "entity": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71", 157 "entityId": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71", 158 "role": "READER" 159 } 160 ] 161 162 The ACL consists collection of elements, each of which specifies an Entity 163 and a Role. Entities are the way you specify an individual or group of 164 individuals, and Roles specify what access they're permitted. 165 166 This particular ACL grants OWNER to two groups (which means members 167 of those groups are allowed to read the object and read and write the ACL), 168 and READ permission to a third group. The project groups are (in order) 169 the project owners group, editors group, and viewers group. 170 171 The 64 digit hex identifiers (following any prefixes like "group-") used in 172 this ACL are called canonical IDs. They are used to identify predefined 173 groups associated with the project that owns the bucket: the Project Owners, 174 Project Editors, and All Project Team Members groups. For more information 175 the permissions and roles of these project groups, see "gsutil help projects". 176 177 Here's an example of an ACL specified using the group-by-email and 178 group-by-domain entities: 179 180[ 181 { 182 "entity": "group-travel-companion-owners@googlegroups.com" 183 "email": "travel-companion-owners@googlegroups.com", 184 "role": "OWNER", 185 } 186 { 187 "domain": "example.com", 188 "entity": "domain-example.com" 189 "role": "READER", 190 }, 191] 192 193 This ACL grants members of an email group OWNER, and grants READ 194 access to any user in a domain (which must be a Google Apps for Business 195 domain). By applying email group grants to a collection of objects 196 you can edit access control for large numbers of objects at once via 197 http://groups.google.com. That way, for example, you can easily and quickly 198 change access to a group of company objects when employees join and leave 199 your company (i.e., without having to individually change ACLs across 200 potentially millions of objects). 201 202 203<B>SHARING SCENARIOS</B> 204 For more detailed examples how to achieve various useful sharing use 205 cases see https://developers.google.com/storage/docs/collaboration 206""") 207 208 209class CommandOptions(HelpProvider): 210 """Additional help about Access Control Lists.""" 211 212 # Help specification. See help_provider.py for documentation. 213 help_spec = HelpProvider.HelpSpec( 214 help_name='acls', 215 help_name_aliases=[ 216 'ACL', 'access control', 'access control list', 'authorization', 217 'canned', 'canned acl'], 218 help_type='additional_help', 219 help_one_line_summary='Working With Access Control Lists', 220 help_text=_DETAILED_HELP_TEXT, 221 subcommand_help_text={}, 222 ) 223