001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.security.visibility;
019
020import java.io.IOException;
021import java.util.List;
022
023import org.apache.hadoop.conf.Configurable;
024import org.apache.hadoop.hbase.Tag;
025import org.apache.hadoop.hbase.TagType;
026import org.apache.yetus.audience.InterfaceAudience;
027import org.apache.hadoop.hbase.coprocessor.RegionCoprocessorEnvironment;
028import org.apache.hadoop.hbase.regionserver.OperationStatus;
029import org.apache.hadoop.hbase.security.User;
030
031/**
032 * The interface which deals with visibility labels and user auths admin service as well as the cell
033 * visibility expression storage part and read time evaluation.
034 */
035@InterfaceAudience.Public
036public interface VisibilityLabelService extends Configurable {
037
038  /**
039   * System calls this after opening of regions. Gives a chance for the VisibilityLabelService to so
040   * any initialization logic.
041   * @param e
042   *          the region coprocessor env
043   */
044  void init(RegionCoprocessorEnvironment e) throws IOException;
045
046  /**
047   * Adds the set of labels into the system.
048   * @param labels
049   *          Labels to add to the system.
050   * @return OperationStatus for each of the label addition
051   */
052  OperationStatus[] addLabels(List<byte[]> labels) throws IOException;
053
054  /**
055   * Sets given labels globally authorized for the user.
056   * @param user
057   *          The authorizing user
058   * @param authLabels
059   *          Labels which are getting authorized for the user
060   * @return OperationStatus for each of the label auth addition
061   */
062  OperationStatus[] setAuths(byte[] user, List<byte[]> authLabels) throws IOException;
063
064  /**
065   * Removes given labels from user's globally authorized list of labels.
066   * @param user
067   *          The user whose authorization to be removed
068   * @param authLabels
069   *          Labels which are getting removed from authorization set
070   * @return OperationStatus for each of the label auth removal
071   */
072  OperationStatus[] clearAuths(byte[] user, List<byte[]> authLabels) throws IOException;
073
074  /**
075   * Retrieve the visibility labels for the user.
076   * @param user
077   *          Name of the user whose authorization to be retrieved
078   * @param systemCall
079   *          Whether a system or user originated call.
080   * @return Visibility labels authorized for the given user.
081   */
082  List<String> getUserAuths(byte[] user, boolean systemCall) throws IOException;
083
084  /**
085   * Retrieve the visibility labels for the groups.
086   * @param groups
087   *          Name of the groups whose authorization to be retrieved
088   * @param systemCall
089   *          Whether a system or user originated call.
090   * @return Visibility labels authorized for the given group.
091   */
092  List<String> getGroupAuths(String[] groups, boolean systemCall) throws IOException;
093
094  /**
095   * Retrieve the list of visibility labels defined in the system.
096   * @param regex  The regular expression to filter which labels are returned.
097   * @return List of visibility labels
098   */
099  List<String> listLabels(String regex) throws IOException;
100
101  /**
102   * Creates tags corresponding to given visibility expression.
103   * <br>
104   * Note: This will be concurrently called from multiple threads and implementation should
105   * take care of thread safety.
106   * @param visExpression The Expression for which corresponding Tags to be created.
107   * @param withSerializationFormat specifies whether a tag, denoting the serialization version
108   *          of the tags, to be added in the list. When this is true make sure to add the
109   *          serialization format Tag also. The format tag value should be byte type.
110   * @param checkAuths denotes whether to check individual labels in visExpression against user's
111   *          global auth label.
112   * @return The list of tags corresponds to the visibility expression. These tags will be stored
113   *         along with the Cells.
114   */
115  List<Tag> createVisibilityExpTags(String visExpression, boolean withSerializationFormat,
116      boolean checkAuths) throws IOException;
117
118  /**
119   * Creates VisibilityExpEvaluator corresponding to given Authorizations. <br>
120   * Note: This will be concurrently called from multiple threads and implementation should take
121   * care of thread safety.
122   * @param authorizations
123   *          Authorizations for the read request
124   * @return The VisibilityExpEvaluator corresponding to the given set of authorization labels.
125   */
126  VisibilityExpEvaluator getVisibilityExpEvaluator(Authorizations authorizations)
127      throws IOException;
128
129  /**
130   * System checks for user auth during admin operations. (ie. Label add, set/clear auth). The
131   * operation is allowed only for users having system auth. Also during read, if the requesting
132   * user has system auth, he can view all the data irrespective of its labels.
133   * @param user
134   *          User for whom system auth check to be done.
135   * @return true if the given user is having system/super auth
136   */
137  boolean havingSystemAuth(User user) throws IOException;
138
139  /**
140   * System uses this for deciding whether a Cell can be deleted by matching visibility expression
141   * in Delete mutation and the cell in consideration. Also system passes the serialization format
142   * of visibility tags in Put and Delete.<br>
143   * Note: This will be concurrently called from multiple threads and implementation should take
144   * care of thread safety.
145   * @param putVisTags
146   *          The visibility tags present in the Put mutation
147   * @param putVisTagFormat
148   *          The serialization format for the Put visibility tags. A <code>null</code> value for
149   *          this format means the tags are written with unsorted label ordinals
150   * @param deleteVisTags
151   *          - The visibility tags in the delete mutation (the specified Cell Visibility)
152   * @param deleteVisTagFormat
153   *          The serialization format for the Delete visibility tags. A <code>null</code> value for
154   *          this format means the tags are written with unsorted label ordinals
155   * @return true if matching tags are found
156   * @see VisibilityConstants#SORTED_ORDINAL_SERIALIZATION_FORMAT
157   */
158  boolean matchVisibility(List<Tag> putVisTags, Byte putVisTagFormat, List<Tag> deleteVisTags,
159      Byte deleteVisTagFormat) throws IOException;
160
161  /**
162   * Provides a way to modify the visibility tags of type {@link TagType}
163   * .VISIBILITY_TAG_TYPE, that are part of the cell created from the WALEdits
164   * that are prepared for replication while calling
165   * {@link org.apache.hadoop.hbase.replication.ReplicationEndpoint}
166   * .replicate().
167   * {@link org.apache.hadoop.hbase.security.visibility.VisibilityReplicationEndpoint}
168   * calls this API to provide an opportunity to modify the visibility tags
169   * before replicating.
170   *
171   * @param visTags
172   *          the visibility tags associated with the cell
173   * @param serializationFormat
174   *          the serialization format associated with the tag
175   * @return the modified visibility expression in the form of byte[]
176   * @throws IOException
177   */
178  byte[] encodeVisibilityForReplication(final List<Tag> visTags,
179      final Byte serializationFormat) throws IOException;
180
181}