View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.apache.hadoop.hbase.security.access;
20  
21  import com.google.common.collect.ArrayListMultimap;
22  import com.google.common.collect.ListMultimap;
23  import org.apache.commons.logging.Log;
24  import org.apache.commons.logging.LogFactory;
25  import org.apache.hadoop.conf.Configuration;
26  import org.apache.hadoop.hbase.HColumnDescriptor;
27  import org.apache.hadoop.hbase.HConstants;
28  import org.apache.hadoop.hbase.HTableDescriptor;
29  import org.apache.hadoop.hbase.KeyValue;
30  import org.apache.hadoop.hbase.catalog.MetaReader;
31  import org.apache.hadoop.hbase.client.Delete;
32  import org.apache.hadoop.hbase.client.Get;
33  import org.apache.hadoop.hbase.client.HTable;
34  import org.apache.hadoop.hbase.client.Put;
35  import org.apache.hadoop.hbase.client.Result;
36  import org.apache.hadoop.hbase.client.ResultScanner;
37  import org.apache.hadoop.hbase.client.Scan;
38  import org.apache.hadoop.hbase.io.HbaseObjectWritable;
39  import org.apache.hadoop.hbase.io.hfile.Compression;
40  import org.apache.hadoop.hbase.master.MasterServices;
41  import org.apache.hadoop.hbase.regionserver.HRegion;
42  import org.apache.hadoop.hbase.regionserver.InternalScanner;
43  import org.apache.hadoop.hbase.regionserver.StoreFile;
44  import org.apache.hadoop.hbase.filter.CompareFilter.CompareOp;
45  import org.apache.hadoop.hbase.filter.RegexStringComparator;
46  import org.apache.hadoop.hbase.filter.QualifierFilter;
47  import org.apache.hadoop.hbase.util.Bytes;
48  import org.apache.hadoop.hbase.util.Pair;
49  import org.apache.hadoop.io.Text;
50  
51  import java.io.ByteArrayOutputStream;
52  import java.io.DataInput;
53  import java.io.DataOutput;
54  import java.io.DataOutputStream;
55  import java.io.IOException;
56  import java.util.*;
57  
58  /**
59   * Maintains lists of permission grants to users and groups to allow for
60   * authorization checks by {@link AccessController}.
61   *
62   * <p>
63   * Access control lists are stored in an "internal" metadata table named
64   * {@code _acl_}. Each table's permission grants are stored as a separate row,
65   * keyed by the table name. KeyValues for permissions assignments are stored
66   * in one of the formats:
67   * <pre>
68   * Key                      Desc
69   * --------                 --------
70   * user                     table level permissions for a user [R=read, W=write]
71   * @group                   table level permissions for a group
72   * user,family              column family level permissions for a user
73   * @group,family            column family level permissions for a group
74   * user,family,qualifier    column qualifier level permissions for a user
75   * @group,family,qualifier  column qualifier level permissions for a group
76   * </pre>
77   * All values are encoded as byte arrays containing the codes from the
78   * {@link org.apache.hadoop.hbase.security.access.TablePermission.Action} enum.
79   * </p>
80   */
81  public class AccessControlLists {
82    /** Internal storage table for access control lists */
83    public static final String ACL_TABLE_NAME_STR = "_acl_";
84    public static final byte[] ACL_TABLE_NAME = Bytes.toBytes(ACL_TABLE_NAME_STR);
85    public static final byte[] ACL_GLOBAL_NAME = ACL_TABLE_NAME;
86    /** Column family used to store ACL grants */
87    public static final String ACL_LIST_FAMILY_STR = "l";
88    public static final byte[] ACL_LIST_FAMILY = Bytes.toBytes(ACL_LIST_FAMILY_STR);
89  
90    /** Table descriptor for ACL internal table */
91    public static final HTableDescriptor ACL_TABLEDESC = new HTableDescriptor(
92        ACL_TABLE_NAME);
93    static {
94      ACL_TABLEDESC.addFamily(
95          new HColumnDescriptor(ACL_LIST_FAMILY,
96              10, // Ten is arbitrary number.  Keep versions to help debugging.
97              Compression.Algorithm.NONE.getName(), true, true, 8 * 1024,
98              HConstants.FOREVER, StoreFile.BloomType.NONE.toString(),
99              HConstants.REPLICATION_SCOPE_LOCAL));
100   }
101 
102   /**
103    * Delimiter to separate user, column family, and qualifier in
104    * _acl_ table info: column keys */
105   public static final char ACL_KEY_DELIMITER = ',';
106   /** Prefix character to denote group names */
107   public static final String GROUP_PREFIX = "@";
108   /** Configuration key for superusers */
109   public static final String SUPERUSER_CONF_KEY = "hbase.superuser";
110 
111   private static Log LOG = LogFactory.getLog(AccessControlLists.class);
112 
113   /**
114    * Check for existence of {@code _acl_} table and create it if it does not exist
115    * @param master reference to HMaster
116    */
117   static void init(MasterServices master) throws IOException {
118     if (!MetaReader.tableExists(master.getCatalogTracker(), ACL_TABLE_NAME_STR)) {
119       master.createTable(ACL_TABLEDESC, null);
120     }
121   }
122 
123   /**
124    * Stores a new user permission grant in the access control lists table.
125    * @param conf the configuration
126    * @param userPerm the details of the permission to be granted
127    * @throws IOException in the case of an error accessing the metadata table
128    */
129   static void addUserPermission(Configuration conf, UserPermission userPerm)
130       throws IOException {
131     Permission.Action[] actions = userPerm.getActions();
132 
133     Put p = new Put(userPerm.isGlobal() ? ACL_GLOBAL_NAME : userPerm.getTable());
134     byte[] key = userPermissionKey(userPerm);
135 
136     if ((actions == null) || (actions.length == 0)) {
137       LOG.warn("No actions associated with user '"+Bytes.toString(userPerm.getUser())+"'");
138       return;
139     }
140 
141     byte[] value = new byte[actions.length];
142     for (int i = 0; i < actions.length; i++) {
143       value[i] = actions[i].code();
144     }
145     p.add(ACL_LIST_FAMILY, key, value);
146     if (LOG.isDebugEnabled()) {
147       LOG.debug("Writing permission for table "+
148           Bytes.toString(userPerm.getTable())+" "+
149           Bytes.toString(key)+": "+Bytes.toStringBinary(value)
150       );
151     }
152     HTable acls = null;
153     try {
154       acls = new HTable(conf, ACL_TABLE_NAME);
155       acls.put(p);
156     } finally {
157       if (acls != null) acls.close();
158     }
159   }
160 
161   /**
162    * Removes a previously granted permission from the stored access control
163    * lists.  The {@link TablePermission} being removed must exactly match what
164    * is stored -- no wildcard matching is attempted.  Ie, if user "bob" has
165    * been granted "READ" access to the "data" table, but only to column family
166    * plus qualifier "info:colA", then trying to call this method with only
167    * user "bob" and the table name "data" (but without specifying the
168    * column qualifier "info:colA") will have no effect.
169    *
170    * @param conf the configuration
171    * @param userPerm the details of the permission to be revoked
172    * @throws IOException if there is an error accessing the metadata table
173    */
174   static void removeUserPermission(Configuration conf, UserPermission userPerm)
175       throws IOException {
176 
177     Delete d = new Delete(userPerm.isGlobal() ? ACL_GLOBAL_NAME : userPerm.getTable());
178     byte[] key = userPermissionKey(userPerm);
179 
180     if (LOG.isDebugEnabled()) {
181       LOG.debug("Removing permission "+ userPerm.toString());
182     }
183     d.deleteColumns(ACL_LIST_FAMILY, key);
184     HTable acls = null;
185     try {
186       acls = new HTable(conf, ACL_TABLE_NAME);
187       acls.delete(d);
188     } finally {
189       if (acls != null) acls.close();
190     }
191   }
192 
193   /**
194    * Remove specified table from the _acl_ table.
195    */
196   static void removeTablePermissions(Configuration conf, byte[] tableName)
197       throws IOException{
198     Delete d = new Delete(tableName);
199 
200     if (LOG.isDebugEnabled()) {
201       LOG.debug("Removing permissions of removed table "+ Bytes.toString(tableName));
202     }
203 
204     HTable acls = null;
205     try {
206       acls = new HTable(conf, ACL_TABLE_NAME);
207       acls.delete(d);
208     } finally {
209       if (acls != null) acls.close();
210     }
211   }
212 
213   /**
214    * Remove specified table column from the _acl_ table.
215    */
216   static void removeTablePermissions(Configuration conf, byte[] tableName, byte[] column)
217       throws IOException{
218 
219     if (LOG.isDebugEnabled()) {
220       LOG.debug("Removing permissions of removed column " + Bytes.toString(column) +
221                 " from table "+ Bytes.toString(tableName));
222     }
223 
224     HTable acls = null;
225     try {
226       acls = new HTable(conf, ACL_TABLE_NAME);
227 
228       Scan scan = new Scan();
229       scan.addFamily(ACL_LIST_FAMILY);
230 
231       String columnName = Bytes.toString(column);
232       scan.setFilter(new QualifierFilter(CompareOp.EQUAL, new RegexStringComparator(
233                      String.format("(%s%s%s)|(%s%s)$",
234                      ACL_KEY_DELIMITER, columnName, ACL_KEY_DELIMITER,
235                      ACL_KEY_DELIMITER, columnName))));
236 
237       Set<byte[]> qualifierSet = new TreeSet<byte[]>(Bytes.BYTES_COMPARATOR);
238       ResultScanner scanner = acls.getScanner(scan);
239       try {
240         for (Result res : scanner) {
241           for (byte[] q : res.getFamilyMap(ACL_LIST_FAMILY).navigableKeySet()) {
242             qualifierSet.add(q);
243           }
244         }
245       } finally {
246         scanner.close();
247       }
248 
249       if (qualifierSet.size() > 0) {
250         Delete d = new Delete(tableName);
251         for (byte[] qualifier : qualifierSet) {
252           d.deleteColumns(ACL_LIST_FAMILY, qualifier);
253         }
254         acls.delete(d);
255       }
256     } finally {
257       if (acls != null) acls.close();
258     }
259   }
260 
261   /**
262    * Build qualifier key from user permission:
263    *  username
264    *  username,family
265    *  username,family,qualifier
266    */
267   static byte[] userPermissionKey(UserPermission userPerm) {
268     byte[] qualifier = userPerm.getQualifier();
269     byte[] family = userPerm.getFamily();
270     byte[] key = userPerm.getUser();
271 
272     if (family != null && family.length > 0) {
273       key = Bytes.add(key, Bytes.add(new byte[]{ACL_KEY_DELIMITER}, family));
274       if (qualifier != null && qualifier.length > 0) {
275         key = Bytes.add(key, Bytes.add(new byte[]{ACL_KEY_DELIMITER}, qualifier));
276       }
277     }
278 
279     return key;
280   }
281 
282   /**
283    * Returns {@code true} if the given region is part of the {@code _acl_}
284    * metadata table.
285    */
286   static boolean isAclRegion(HRegion region) {
287     return Bytes.equals(ACL_TABLE_NAME, region.getTableDesc().getName());
288   }
289 
290   /**
291    * Returns {@code true} if the given table is {@code _acl_} metadata table.
292    */
293   static boolean isAclTable(HTableDescriptor desc) {
294     return Bytes.equals(ACL_TABLE_NAME, desc.getName());
295   }
296 
297   /**
298    * Loads all of the permission grants stored in a region of the {@code _acl_}
299    * table.
300    *
301    * @param aclRegion
302    * @return
303    * @throws IOException
304    */
305   static Map<byte[],ListMultimap<String,TablePermission>> loadAll(
306       HRegion aclRegion)
307     throws IOException {
308 
309     if (!isAclRegion(aclRegion)) {
310       throw new IOException("Can only load permissions from "+ACL_TABLE_NAME_STR);
311     }
312 
313     Map<byte[],ListMultimap<String,TablePermission>> allPerms =
314         new TreeMap<byte[],ListMultimap<String,TablePermission>>(Bytes.BYTES_COMPARATOR);
315     
316     // do a full scan of _acl_ table
317 
318     Scan scan = new Scan();
319     scan.addFamily(ACL_LIST_FAMILY);
320 
321     InternalScanner iScanner = null;
322     try {
323       iScanner = aclRegion.getScanner(scan);
324 
325       while (true) {
326         List<KeyValue> row = new ArrayList<KeyValue>();
327 
328         boolean hasNext = iScanner.next(row);
329         ListMultimap<String,TablePermission> perms = ArrayListMultimap.create();
330         byte[] table = null;
331         for (KeyValue kv : row) {
332           if (table == null) {
333             table = kv.getRow();
334           }
335           Pair<String,TablePermission> permissionsOfUserOnTable =
336               parseTablePermissionRecord(table, kv);
337           if (permissionsOfUserOnTable != null) {
338             String username = permissionsOfUserOnTable.getFirst();
339             TablePermission permissions = permissionsOfUserOnTable.getSecond();
340             perms.put(username, permissions);
341           }
342         }
343         if (table != null) {
344           allPerms.put(table, perms);
345         }
346         if (!hasNext) {
347           break;
348         }
349       }
350     } finally {
351       if (iScanner != null) {
352         iScanner.close();
353       }
354     }
355 
356     return allPerms;
357   }
358 
359   /**
360    * Load all permissions from the region server holding {@code _acl_},
361    * primarily intended for testing purposes.
362    */
363   static Map<byte[],ListMultimap<String,TablePermission>> loadAll(
364       Configuration conf) throws IOException {
365     Map<byte[],ListMultimap<String,TablePermission>> allPerms =
366         new TreeMap<byte[],ListMultimap<String,TablePermission>>(Bytes.BYTES_COMPARATOR);
367 
368     // do a full scan of _acl_, filtering on only first table region rows
369 
370     Scan scan = new Scan();
371     scan.addFamily(ACL_LIST_FAMILY);
372 
373     HTable acls = null;
374     ResultScanner scanner = null;
375     try {
376       acls = new HTable(conf, ACL_TABLE_NAME);
377       scanner = acls.getScanner(scan);
378       for (Result row : scanner) {
379         ListMultimap<String,TablePermission> resultPerms =
380             parseTablePermissions(row.getRow(), row);
381         allPerms.put(row.getRow(), resultPerms);
382       }
383     } finally {
384       if (scanner != null) scanner.close();
385       if (acls != null) acls.close();
386     }
387 
388     return allPerms;
389   }
390 
391   /**
392    * Reads user permission assignments stored in the <code>l:</code> column
393    * family of the first table row in <code>_acl_</code>.
394    *
395    * <p>
396    * See {@link AccessControlLists class documentation} for the key structure
397    * used for storage.
398    * </p>
399    */
400   static ListMultimap<String, TablePermission> getTablePermissions(Configuration conf,
401       byte[] tableName) throws IOException {
402     if (tableName == null) tableName = ACL_TABLE_NAME;
403 
404     // for normal user tables, we just read the table row from _acl_
405     ListMultimap<String, TablePermission> perms = ArrayListMultimap.create();
406     HTable acls = null;
407     try {
408       acls = new HTable(conf, ACL_TABLE_NAME);
409       Get get = new Get(tableName);
410       get.addFamily(ACL_LIST_FAMILY);
411       Result row = acls.get(get);
412       if (!row.isEmpty()) {
413         perms = parseTablePermissions(tableName, row);
414       } else {
415         LOG.info("No permissions found in " + ACL_TABLE_NAME_STR + " for table "
416             + Bytes.toString(tableName));
417       }
418     } finally {
419       if (acls != null) acls.close();
420     }
421 
422     return perms;
423   }
424 
425   /**
426    * Returns the currently granted permissions for a given table as a list of
427    * user plus associated permissions.
428    */
429   static List<UserPermission> getUserPermissions(
430       Configuration conf, byte[] tableName)
431   throws IOException {
432     ListMultimap<String,TablePermission> allPerms = getTablePermissions(
433       conf, tableName);
434 
435     List<UserPermission> perms = new ArrayList<UserPermission>();
436 
437     for (Map.Entry<String, TablePermission> entry : allPerms.entries()) {
438       UserPermission up = new UserPermission(Bytes.toBytes(entry.getKey()),
439           entry.getValue().getTable(), entry.getValue().getFamily(),
440           entry.getValue().getQualifier(), entry.getValue().getActions());
441       perms.add(up);
442     }
443     return perms;
444   }
445 
446   private static ListMultimap<String,TablePermission> parseTablePermissions(
447       byte[] table, Result result) {
448     ListMultimap<String,TablePermission> perms = ArrayListMultimap.create();
449     if (result != null && result.size() > 0) {
450       for (KeyValue kv : result.raw()) {
451 
452         Pair<String,TablePermission> permissionsOfUserOnTable =
453             parseTablePermissionRecord(table, kv);
454 
455         if (permissionsOfUserOnTable != null) {
456           String username = permissionsOfUserOnTable.getFirst();
457           TablePermission permissions = permissionsOfUserOnTable.getSecond();
458           perms.put(username, permissions);
459         }
460       }
461     }
462     return perms;
463   }
464 
465   private static Pair<String,TablePermission> parseTablePermissionRecord(
466       byte[] table, KeyValue kv) {
467     // return X given a set of permissions encoded in the permissionRecord kv.
468     byte[] family = kv.getFamily();
469 
470     if (!Bytes.equals(family, ACL_LIST_FAMILY)) {
471       return null;
472     }
473 
474     byte[] key = kv.getQualifier();
475     byte[] value = kv.getValue();
476     if (LOG.isDebugEnabled()) {
477       LOG.debug("Read acl: kv ["+
478                 Bytes.toStringBinary(key)+": "+
479                 Bytes.toStringBinary(value)+"]");
480     }
481 
482     // check for a column family appended to the key
483     // TODO: avoid the string conversion to make this more efficient
484     String username = Bytes.toString(key);
485     int idx = username.indexOf(ACL_KEY_DELIMITER);
486     byte[] permFamily = null;
487     byte[] permQualifier = null;
488     if (idx > 0 && idx < username.length()-1) {
489       String remainder = username.substring(idx+1);
490       username = username.substring(0, idx);
491       idx = remainder.indexOf(ACL_KEY_DELIMITER);
492       if (idx > 0 && idx < remainder.length()-1) {
493         permFamily = Bytes.toBytes(remainder.substring(0, idx));
494         permQualifier = Bytes.toBytes(remainder.substring(idx+1));
495       } else {
496         permFamily = Bytes.toBytes(remainder);
497       }
498     }
499 
500     return new Pair<String,TablePermission>(
501         username, new TablePermission(table, permFamily, permQualifier, value));
502   }
503 
504   /**
505    * Writes a set of permissions as {@link org.apache.hadoop.io.Writable} instances
506    * to the given output stream.
507    * @param out
508    * @param perms
509    * @param conf
510    * @throws IOException
511    */
512   public static void writePermissions(DataOutput out,
513       ListMultimap<String,? extends Permission> perms, Configuration conf)
514   throws IOException {
515     Set<String> keys = perms.keySet();
516     out.writeInt(keys.size());
517     for (String key : keys) {
518       Text.writeString(out, key);
519       HbaseObjectWritable.writeObject(out, perms.get(key), List.class, conf);
520     }
521   }
522 
523   /**
524    * Writes a set of permissions as {@link org.apache.hadoop.io.Writable} instances
525    * and returns the resulting byte array.
526    */
527   public static byte[] writePermissionsAsBytes(
528       ListMultimap<String,? extends Permission> perms, Configuration conf) {
529     try {
530       ByteArrayOutputStream bos = new ByteArrayOutputStream();
531       writePermissions(new DataOutputStream(bos), perms, conf);
532       return bos.toByteArray();
533     } catch (IOException ioe) {
534       // shouldn't happen here
535       LOG.error("Error serializing permissions", ioe);
536     }
537     return null;
538   }
539 
540   /**
541    * Reads a set of permissions as {@link org.apache.hadoop.io.Writable} instances
542    * from the input stream.
543    */
544   public static <T extends Permission> ListMultimap<String,T> readPermissions(
545       DataInput in, Configuration conf) throws IOException {
546     ListMultimap<String,T> perms = ArrayListMultimap.create();
547     int length = in.readInt();
548     for (int i=0; i<length; i++) {
549       String user = Text.readString(in);
550       List<T> userPerms =
551           (List)HbaseObjectWritable.readObject(in, conf);
552       perms.putAll(user, userPerms);
553     }
554 
555     return perms;
556   }
557 
558   /**
559    * Returns whether or not the given name should be interpreted as a group
560    * principal.  Currently this simply checks if the name starts with the
561    * special group prefix character ("@").
562    */
563   public static boolean isGroupPrincipal(String name) {
564     return name != null && name.startsWith(GROUP_PREFIX);
565   }
566 
567   /**
568    * Returns the actual name for a group principal (stripped of the
569    * group prefix).
570    */
571   public static String getGroupName(String aclKey) {
572     if (!isGroupPrincipal(aclKey)) {
573       return aclKey;
574     }
575 
576     return aclKey.substring(GROUP_PREFIX.length());
577   }
578 }