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  package org.apache.hadoop.hbase.security.visibility;
19  
20  import java.io.IOException;
21  import java.util.List;
22  
23  import org.apache.hadoop.conf.Configurable;
24  import org.apache.hadoop.hbase.Tag;
25  import org.apache.hadoop.hbase.TagType;
26  import org.apache.hadoop.hbase.classification.InterfaceAudience;
27  import org.apache.hadoop.hbase.classification.InterfaceStability;
28  import org.apache.hadoop.hbase.coprocessor.RegionCoprocessorEnvironment;
29  import org.apache.hadoop.hbase.regionserver.OperationStatus;
30  
31  /**
32   * The interface which deals with visibility labels and user auths admin service as well as the cell
33   * visibility expression storage part and read time evaluation.
34   */
35  @InterfaceAudience.Public
36  @InterfaceStability.Evolving
37  public interface VisibilityLabelService extends Configurable {
38  
39    /**
40     * System calls this after opening of regions. Gives a chance for the VisibilityLabelService to so
41     * any initialization logic.
42     * @param e
43     *          the region coprocessor env
44     */
45    void init(RegionCoprocessorEnvironment e) throws IOException;
46  
47    /**
48     * Adds the set of labels into the system.
49     * @param labels
50     *          Labels to add to the system.
51     * @return OperationStatus for each of the label addition
52     */
53    OperationStatus[] addLabels(List<byte[]> labels) throws IOException;
54  
55    /**
56     * Sets given labels globally authorized for the user.
57     * @param user
58     *          The authorizing user
59     * @param authLabels
60     *          Labels which are getting authorized for the user
61     * @return OperationStatus for each of the label auth addition
62     */
63    OperationStatus[] setAuths(byte[] user, List<byte[]> authLabels) throws IOException;
64  
65    /**
66     * Removes given labels from user's globally authorized list of labels.
67     * @param user
68     *          The user whose authorization to be removed
69     * @param authLabels
70     *          Labels which are getting removed from authorization set
71     * @return OperationStatus for each of the label auth removal
72     */
73    OperationStatus[] clearAuths(byte[] user, List<byte[]> authLabels) throws IOException;
74  
75    /**
76     * @param user
77     *          Name of the user whose authorization to be retrieved
78     * @param systemCall
79     *          Whether a system or user originated call.
80     * @return Visibility labels authorized for the given user.
81     */
82    List<String> getAuths(byte[] user, boolean systemCall) throws IOException;
83  
84    /**
85     * Retrieve the list of visibility labels defined in the system.
86     * @param regex  The regular expression to filter which labels are returned.
87     * @return List of visibility labels
88     */
89    List<String> listLabels(String regex) throws IOException;
90  
91    /**
92     * Creates tags corresponding to given visibility expression.
93     * <br>
94     * Note: This will be concurrently called from multiple threads and implementation should
95     * take care of thread safety.
96     * @param visExpression The Expression for which corresponding Tags to be created.
97     * @param withSerializationFormat specifies whether a tag, denoting the serialization version
98     *          of the tags, to be added in the list. When this is true make sure to add the
99     *          serialization format Tag also. The format tag value should be byte type.
100    * @param checkAuths denotes whether to check individual labels in visExpression against user's
101    *          global auth label.
102    * @return The list of tags corresponds to the visibility expression. These tags will be stored
103    *         along with the Cells.
104    */
105   List<Tag> createVisibilityExpTags(String visExpression, boolean withSerializationFormat,
106       boolean checkAuths) throws IOException;
107 
108   /**
109    * Creates VisibilityExpEvaluator corresponding to given Authorizations. <br>
110    * Note: This will be concurrently called from multiple threads and implementation should take
111    * care of thread safety.
112    * @param authorizations
113    *          Authorizations for the read request
114    * @return The VisibilityExpEvaluator corresponding to the given set of authorization labels.
115    */
116   VisibilityExpEvaluator getVisibilityExpEvaluator(Authorizations authorizations)
117       throws IOException;
118 
119   /**
120    * System checks for user auth during admin operations. (ie. Label add, set/clear auth). The
121    * operation is allowed only for users having system auth. Also during read, if the requesting
122    * user has system auth, he can view all the data irrespective of its labels.
123    * @param user
124    *          User for whom system auth check to be done.
125    * @return true if the given user is having system/super auth
126    */
127   boolean havingSystemAuth(byte[] user) throws IOException;
128 
129   /**
130    * System uses this for deciding whether a Cell can be deleted by matching visibility expression
131    * in Delete mutation and the cell in consideration. Also system passes the serialization format
132    * of visibility tags in Put and Delete.<br>
133    * Note: This will be concurrently called from multiple threads and implementation should take
134    * care of thread safety.
135    * @param putVisTags
136    *          The visibility tags present in the Put mutation
137    * @param putVisTagFormat
138    *          The serialization format for the Put visibility tags. A <code>null</code> value for
139    *          this format means the tags are written with unsorted label ordinals
140    * @param deleteVisTags
141    *          - The visibility tags in the delete mutation (the specified Cell Visibility)
142    * @param deleteVisTagFormat
143    *          The serialization format for the Delete visibility tags. A <code>null</code> value for
144    *          this format means the tags are written with unsorted label ordinals
145    * @return true if matching tags are found
146    * @see VisibilityConstants#SORTED_ORDINAL_SERIALIZATION_FORMAT
147    */
148   boolean matchVisibility(List<Tag> putVisTags, Byte putVisTagFormat, List<Tag> deleteVisTags,
149       Byte deleteVisTagFormat) throws IOException;
150 
151   /**
152    * Provides a way to modify the visibility tags of type {@link TagType}
153    * .VISIBILITY_TAG_TYPE, that are part of the cell created from the WALEdits
154    * that are prepared for replication while calling
155    * {@link org.apache.hadoop.hbase.replication.ReplicationEndpoint}
156    * .replicate().
157    * {@link org.apache.hadoop.hbase.security.visibility.VisibilityReplicationEndpoint}
158    * calls this API to provide an opportunity to modify the visibility tags
159    * before replicating.
160    *
161    * @param visTags
162    *          the visibility tags associated with the cell
163    * @param serializationFormat
164    *          the serialization format associated with the tag
165    * @return the modified visibility expression in the form of byte[]
166    * @throws IOException
167    */
168   byte[] encodeVisibilityForReplication(final List<Tag> visTags,
169       final Byte serializationFormat) throws IOException;
170 }