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;
022import org.apache.hadoop.conf.Configurable;
023import org.apache.hadoop.hbase.Tag;
024import org.apache.hadoop.hbase.TagType;
025import org.apache.hadoop.hbase.coprocessor.RegionCoprocessorEnvironment;
026import org.apache.hadoop.hbase.regionserver.OperationStatus;
027import org.apache.hadoop.hbase.security.User;
028import org.apache.yetus.audience.InterfaceAudience;
029
030/**
031 * The interface which deals with visibility labels and user auths admin service as well as the cell
032 * visibility expression storage part and read time evaluation.
033 */
034@InterfaceAudience.Public
035public interface VisibilityLabelService extends Configurable {
036
037  /**
038   * System calls this after opening of regions. Gives a chance for the VisibilityLabelService to so
039   * any initialization logic. n * the region coprocessor env
040   */
041  void init(RegionCoprocessorEnvironment e) throws IOException;
042
043  /**
044   * Adds the set of labels into the system. n * Labels to add to the system.
045   * @return OperationStatus for each of the label addition
046   */
047  OperationStatus[] addLabels(List<byte[]> labels) throws IOException;
048
049  /**
050   * Sets given labels globally authorized for the user. n * The authorizing user n * Labels which
051   * are getting authorized for the user
052   * @return OperationStatus for each of the label auth addition
053   */
054  OperationStatus[] setAuths(byte[] user, List<byte[]> authLabels) throws IOException;
055
056  /**
057   * Removes given labels from user's globally authorized list of labels. n * The user whose
058   * authorization to be removed n * Labels which are getting removed from authorization set
059   * @return OperationStatus for each of the label auth removal
060   */
061  OperationStatus[] clearAuths(byte[] user, List<byte[]> authLabels) throws IOException;
062
063  /**
064   * Retrieve the visibility labels for the user. n * Name of the user whose authorization to be
065   * retrieved n * Whether a system or user originated call.
066   * @return Visibility labels authorized for the given user.
067   */
068  List<String> getUserAuths(byte[] user, boolean systemCall) throws IOException;
069
070  /**
071   * Retrieve the visibility labels for the groups. n * Name of the groups whose authorization to be
072   * retrieved n * Whether a system or user originated call.
073   * @return Visibility labels authorized for the given group.
074   */
075  List<String> getGroupAuths(String[] groups, boolean systemCall) throws IOException;
076
077  /**
078   * Retrieve the list of visibility labels defined in the system.
079   * @param regex The regular expression to filter which labels are returned.
080   * @return List of visibility labels
081   */
082  List<String> listLabels(String regex) throws IOException;
083
084  /**
085   * Creates tags corresponding to given visibility expression. <br>
086   * Note: This will be concurrently called from multiple threads and implementation should take
087   * care of thread safety.
088   * @param visExpression           The Expression for which corresponding Tags to be created.
089   * @param withSerializationFormat specifies whether a tag, denoting the serialization version of
090   *                                the tags, to be added in the list. When this is true make sure
091   *                                to add the serialization format Tag also. The format tag value
092   *                                should be byte type.
093   * @param checkAuths              denotes whether to check individual labels in visExpression
094   *                                against user's global auth label.
095   * @return The list of tags corresponds to the visibility expression. These tags will be stored
096   *         along with the Cells.
097   */
098  List<Tag> createVisibilityExpTags(String visExpression, boolean withSerializationFormat,
099    boolean checkAuths) throws IOException;
100
101  /**
102   * Creates VisibilityExpEvaluator corresponding to given Authorizations. <br>
103   * Note: This will be concurrently called from multiple threads and implementation should take
104   * care of thread safety. n * Authorizations for the read request
105   * @return The VisibilityExpEvaluator corresponding to the given set of authorization labels.
106   */
107  VisibilityExpEvaluator getVisibilityExpEvaluator(Authorizations authorizations)
108    throws IOException;
109
110  /**
111   * System checks for user auth during admin operations. (ie. Label add, set/clear auth). The
112   * operation is allowed only for users having system auth. Also during read, if the requesting
113   * user has system auth, he can view all the data irrespective of its labels. n * User for whom
114   * system auth check to be done.
115   * @return true if the given user is having system/super auth
116   */
117  boolean havingSystemAuth(User user) throws IOException;
118
119  /**
120   * System uses this for deciding whether a Cell can be deleted by matching visibility expression
121   * in Delete mutation and the cell in consideration. Also system passes the serialization format
122   * of visibility tags in Put and Delete.<br>
123   * Note: This will be concurrently called from multiple threads and implementation should take
124   * care of thread safety. n * The visibility tags present in the Put mutation n * The
125   * serialization format for the Put visibility tags. A <code>null</code> value for this format
126   * means the tags are written with unsorted label ordinals n * - The visibility tags in the delete
127   * mutation (the specified Cell Visibility) n * The serialization format for the Delete visibility
128   * tags. A <code>null</code> value for this format means the tags are written with unsorted label
129   * ordinals
130   * @return true if matching tags are found
131   * @see VisibilityConstants#SORTED_ORDINAL_SERIALIZATION_FORMAT
132   */
133  boolean matchVisibility(List<Tag> putVisTags, Byte putVisTagFormat, List<Tag> deleteVisTags,
134    Byte deleteVisTagFormat) throws IOException;
135
136  /**
137   * Provides a way to modify the visibility tags of type {@link TagType} .VISIBILITY_TAG_TYPE, that
138   * are part of the cell created from the WALEdits that are prepared for replication while calling
139   * {@link org.apache.hadoop.hbase.replication.ReplicationEndpoint} .replicate().
140   * {@link org.apache.hadoop.hbase.security.visibility.VisibilityReplicationEndpoint} calls this
141   * API to provide an opportunity to modify the visibility tags before replicating. n * the
142   * visibility tags associated with the cell n * the serialization format associated with the tag
143   * @return the modified visibility expression in the form of byte[] n
144   */
145  byte[] encodeVisibilityForReplication(final List<Tag> visTags, final Byte serializationFormat)
146    throws IOException;
147
148}