Updated Branches: refs/heads/1.6.0-SNAPSHOT bea6e9417 -> c41900edc refs/heads/master ce8a568a6 -> 2c37c4517
ACCUMULO-2030 Javadoc for core/security. Signed-off-by: Mike Drob <md...@cloudera.com> Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/c41900ed Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/c41900ed Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/c41900ed Branch: refs/heads/1.6.0-SNAPSHOT Commit: c41900edca7c58e583323ec57c8aff2ccde91660 Parents: bea6e94 Author: Bill Havanki <bhava...@cloudera.com> Authored: Mon Oct 7 16:57:07 2013 -0400 Committer: Mike Drob <md...@cloudera.com> Committed: Fri Dec 27 16:48:49 2013 -0800 ---------------------------------------------------------------------- .../core/security/AuthorizationContainer.java | 8 +- .../accumulo/core/security/Authorizations.java | 75 ++++++++++++++--- .../core/security/ColumnVisibility.java | 89 ++++++++++++++------ .../accumulo/core/security/Credentials.java | 26 ++++++ .../core/security/NamespacePermission.java | 25 +++++- .../core/security/SystemPermission.java | 25 +++++- .../accumulo/core/security/TablePermission.java | 25 +++++- .../core/security/VisibilityConstraint.java | 9 ++ .../core/security/VisibilityEvaluator.java | 41 ++++++++- .../core/security/VisibilityParseException.java | 12 ++- 10 files changed, 287 insertions(+), 48 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java b/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java index 041bf3c..382e20b 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java +++ b/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java @@ -18,9 +18,15 @@ package org.apache.accumulo.core.security; import org.apache.accumulo.core.data.ByteSequence; +/** + * An interface for classes that contain a collection of authorizations. + */ public interface AuthorizationContainer { /** - * Checks for the existence of this UTF-8 encoded authorization. + * Checks whether this object contains the given authorization. + * + * @param auth authorization, as a string encoded in UTF-8 + * @return true if authorization is in this collection */ public boolean contains(ByteSequence auth); } http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java b/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java index 5cecefb..67349d4 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java +++ b/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java @@ -34,17 +34,28 @@ import org.apache.accumulo.core.util.ArgumentChecker; import org.apache.accumulo.core.util.ByteBufferUtil; import org.apache.commons.codec.binary.Base64; +/** + * A collection of authorization strings. + */ public class Authorizations implements Iterable<byte[]>, Serializable, AuthorizationContainer { private static final long serialVersionUID = 1L; private Set<ByteSequence> auths = new HashSet<ByteSequence>(); - private List<byte[]> authsList = new ArrayList<byte[]>(); + private List<byte[]> authsList = new ArrayList<byte[]>(); // sorted order + /** + * An empty set of authorizations. + */ public static final Authorizations EMPTY = new Authorizations(); private static final boolean[] validAuthChars = new boolean[256]; + /** + * A special header string used when serializing instances of this class. + * + * @see #serialize() + */ public static final String HEADER = "!AUTH1:"; static { @@ -88,8 +99,11 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * A convenience constructor that accepts a collection of string authorizations that have each already been encoded as UTF-8 bytes. + * Constructs an authorization object from a collection of string authorizations that have each already been encoded as UTF-8 bytes. Warning: This method + * does not verify that each encoded string is valid UTF-8. * + * @param authorizations collection of authorizations, as strings encoded in UTF-8 + * @throws IllegalArgumentException if authorizations is null * @see #Authorizations(String...) */ public Authorizations(Collection<byte[]> authorizations) { @@ -100,8 +114,11 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * A convenience constructor that accepts a collection of string authorizations that have each already been encoded as UTF-8 bytes. + * Constructs an authorization object from a list of string authorizations that have each already been encoded as UTF-8 bytes. Warning: This method does not + * verify that each encoded string is valid UTF-8. * + * @param authorizations list of authorizations, as strings encoded in UTF-8 and placed in buffers + * @throws IllegalArgumentException if authorizations is null * @see #Authorizations(String...) */ public Authorizations(List<ByteBuffer> authorizations) { @@ -113,10 +130,12 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Constructs an authorizations object a serialized form. This is NOT a constructor for a set of authorizations of size one. + * Constructs an authorizations object from a serialized form. This is NOT a constructor for a set of authorizations of size one. Warning: This method does + * not verify that the encoded serialized form is valid UTF-8. * * @param authorizations - * a serialized authorizations string produced by {@link #getAuthorizationsArray()} or {@link #serialize()} (converted to UTF-8 bytes) + * a serialized authorizations string produced by {@link #getAuthorizationsArray()} or {@link #serialize()}, converted to UTF-8 bytes + * @throws IllegalArgumentException if authorizations is null */ public Authorizations(byte[] authorizations) { @@ -153,6 +172,7 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza * * @param authorizations * array of authorizations + * @throws IllegalArgumentException if authorizations is null */ public Authorizations(String... authorizations) { setAuthorizations(authorizations); @@ -170,17 +190,19 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Retrieve a serialized form of the underlying set of authorizations. + * Returns a serialized form of these authorizations. * - * @see #Authorizations(byte[]) + * @return serialized form of these authorizations, as a string encoded in UTF-8 + * @see #serialize() */ public byte[] getAuthorizationsArray() { return serialize().getBytes(Constants.UTF8); } /** - * Retrieve authorizations as a list of strings that have been encoded as UTF-8 bytes. - * + * Gets the authorizations in sorted order. The returned list is not modifiable. + * + * @return authorizations, each as a string encoded in UTF-8 * @see #Authorizations(Collection) */ public List<byte[]> getAuthorizations() { @@ -194,7 +216,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Retrieve authorizations as a list of strings that have been encoded as UTF-8 bytes. + * Gets the authorizations in sorted order. The returned list is not modifiable. + * + * @return authorizations, each as a string encoded in UTF-8 and within a buffer + * @see #Authorizations(List) */ public List<ByteBuffer> getAuthorizationsBB() { return ByteBufferUtil.toImmutableByteBufferList(getAuthorizations()); @@ -214,14 +239,20 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Checks for the existence of this UTF-8 encoded authorization. + * Checks whether this object contains the given authorization. + * + * @param auth authorization, as a string encoded in UTF-8 + * @return true if authorization is in this collection */ public boolean contains(byte[] auth) { return auths.contains(new ArrayByteSequence(auth)); } /** - * Checks for the existence of this UTF-8 encoded authorization. + * Checks whether this object contains the given authorization. Warning: This method does not verify that the encoded string is valid UTF-8. + * + * @param auth authorization, as a string encoded in UTF-8 + * @return true if authorization is in this collection */ @Override public boolean contains(ByteSequence auth) { @@ -229,7 +260,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Checks for the existence of this authorization. + * Checks whether this object contains the given authorization. + * + * @param auth authorization + * @return true if authorization is in this collection */ public boolean contains(String auth) { return auths.contains(auth.getBytes(Constants.UTF8)); @@ -258,10 +292,20 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza return result; } + /** + * Gets the size of this collection of authorizations. + * + * @return collection size + */ public int size() { return auths.size(); } + /** + * Checks if this collection of authorizations is empty. + * + * @return true if this collection contains no authorizations + */ public boolean isEmpty() { return auths.isEmpty(); } @@ -272,7 +316,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable, Authoriza } /** - * Returns a serialized form of these authorizations. Convert to UTF-8 bytes to deserialize with {@link #Authorizations(byte[])} + * Returns a serialized form of these authorizations. Convert the returned + * string to UTF-8 bytes to deserialize with {@link #Authorizations(byte[])}. + * + * @return serialized form of authorizations */ public String serialize() { StringBuilder sb = new StringBuilder(HEADER); http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java b/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java index bd16b84..eb99807 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java +++ b/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java @@ -42,13 +42,16 @@ public class ColumnVisibility { /** * Accessor for the underlying byte string. - * + * * @return byte array representation of a visibility expression */ public byte[] getExpression() { return expression; } + /** + * The node types in a parse tree for a visibility expression. + */ public static enum NodeType { EMPTY, TERM, OR, AND, } @@ -58,7 +61,13 @@ public class ColumnVisibility { */ private static final Node EMPTY_NODE = new Node(NodeType.EMPTY, 0); + /** + * A node in the parse tree for a visibility expression. + */ public static class Node { + /** + * An empty list of nodes. + */ public final static List<Node> EMPTY = Collections.emptyList(); NodeType type; int start; @@ -115,10 +124,20 @@ public class ColumnVisibility { } } + /** + * A node comparator. Nodes sort according to node type, terms sort + * lexicographically. AND and OR nodes sort by number of children, or if + * the same by corresponding children. + */ public static class NodeComparator implements Comparator<Node> { byte[] text; + /** + * Creates a new comparator. + * + * @param text expression string, encoded in UTF-8 + */ public NodeComparator(byte[] text) { this.text = text; } @@ -209,8 +228,8 @@ public class ColumnVisibility { } /** - * Generates a byte[] that represents a normalized, but logically equivalent, form of the supplied expression. - * + * Generates a byte[] that represents a normalized, but logically equivalent, form of this evaluator's expression. + * * @return normalized expression in byte[] form */ public byte[] flatten() { @@ -371,7 +390,7 @@ public class ColumnVisibility { } /** - * Empty visibility. Normally, elements with empty visibility can be seen by everyone. Though, one could change this behavior with filters. + * Creates an empty visibility. Normally, elements with empty visibility can be seen by everyone. Though, one could change this behavior with filters. * * @see #ColumnVisibility(String) */ @@ -380,50 +399,51 @@ public class ColumnVisibility { } /** - * Set the column visibility for a Mutation. - * + * Creates a column visibility for a Mutation. + * * @param expression * An expression of the rights needed to see this mutation. The expression is a sequence of characters from the set [A-Za-z0-9_-] along with the - * binary operators "&" and "|" indicating that both operands are necessary, or the either is necessary. The following are valid expressions for + * binary operators "&" and "|" indicating that both operands are necessary, or that either is necessary. The following are valid expressions for * visibility: - * + * * <pre> * A * A|B - * (A|B)&(C|D) - * orange|(red&yellow) - * + * (A|B)&(C|D) + * orange|(red&yellow) + * * </pre> - * + * * <P> * The following are not valid expressions for visibility: - * + * * <pre> - * A|B&C + * A|B&C * A=B * A|B| - * A&|B + * A&|B * () * ) * dog|!cat * </pre> - * + * * <P> * You can use any character you like in your column visibility expression with quoting. If your quoted term contains '"' or '\' then escape * them with '\'. The {@link #quote(String)} method will properly quote and escape terms for you. - * + * * <pre> * "A#C"<span />&<span />B * </pre> - * + * */ public ColumnVisibility(String expression) { this(expression.getBytes(Constants.UTF8)); } /** - * A convenience method for constructing from a string already encoded in UTF-8 bytes and contained in a {@link Text} object. - * + * Creates a column visibility for a Mutation. + * + * @param expression visibility expression * @see #ColumnVisibility(String) */ public ColumnVisibility(Text expression) { @@ -431,8 +451,9 @@ public class ColumnVisibility { } /** - * A convenience method for constructing from a string already encoded in UTF-8 bytes. - * + * Creates a column visibility for a Mutation from a string already encoded in UTF-8 bytes. + * + * @param expression visibility expression, encoded as UTF-8 bytes * @see #ColumnVisibility(String) */ public ColumnVisibility(byte[] expression) { @@ -456,6 +477,9 @@ public class ColumnVisibility { /** * Compares two ColumnVisibilities for string equivalence, not as a meaningful comparison of terms and conditions. + * + * @param otherLe other column visibility + * @return true if this visibility equals the other via string comparison */ public boolean equals(ColumnVisibility otherLe) { return Arrays.equals(expression, otherLe.expression); @@ -466,16 +490,21 @@ public class ColumnVisibility { return Arrays.hashCode(expression); } + /** + * Gets the parse tree for this column visibility. + * + * @return parse tree node + */ public Node getParseTree() { return node; } /** - * Use to properly quote terms in a column visibility expression. If no quoting is needed, then nothing is done. - * + * Properly quotes terms in a column visibility expression. If no quoting is needed, then nothing is done. + * * <p> * Examples of using quote : - * + * * <pre> * import static org.apache.accumulo.core.security.ColumnVisibility.quote; * . @@ -483,15 +512,19 @@ public class ColumnVisibility { * . * ColumnVisibility cv = new ColumnVisibility(quote("A#C") + "&" + quote("FOO")); * </pre> - * + * + * @param term term to quote + * @return quoted term (unquoted if unnecessary) */ public static String quote(String term) { return new String(quote(term.getBytes(Constants.UTF8)), Constants.UTF8); } /** - * A convenience method to quote terms which are already encoded as UTF-8 bytes. - * + * Properly quotes terms in a column visibility expression. If no quoting is needed, then nothing is done. + * + * @param term term to quote, encoded as UTF-8 bytes + * @return quoted term (unquoted if unnecessary), encoded as UTF-8 bytes * @see #quote(String) */ public static byte[] quote(byte[] term) { http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/Credentials.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/Credentials.java b/core/src/main/java/org/apache/accumulo/core/security/Credentials.java index 45708a8..f04e115 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/Credentials.java +++ b/core/src/main/java/org/apache/accumulo/core/security/Credentials.java @@ -41,15 +41,31 @@ public class Credentials { private String principal; private AuthenticationToken token; + /** + * Creates a new credentials object. + * + * @param principal unique identifier for the entity (e.g. a user or service) authorized for these credentials + * @param token authentication token used to prove that the principal for these credentials has been properly verified + */ public Credentials(String principal, AuthenticationToken token) { this.principal = principal; this.token = token; } + /** + * Gets the principal. + * + * @return unique identifier for the entity (e.g. a user or service) authorized for these credentials + */ public String getPrincipal() { return principal; } + /** + * Gets the authentication token. + * + * @return authentication token used to prove that the principal for these credentials has been properly verified + */ public AuthenticationToken getToken() { return token; } @@ -57,6 +73,10 @@ public class Credentials { /** * Converts the current object to the relevant thrift type. The object returned from this contains a non-destroyable version of the * {@link AuthenticationToken}, so this should be used just before placing on the wire, and references to it should be tightly controlled. + * + * @param instance client instance + * @return Thrift credentials + * @throws RuntimeException if the authentication token has been destroyed (expired) */ public TCredentials toThrift(Instance instance) { TCredentials tCreds = new TCredentials(getPrincipal(), getToken().getClass().getName(), @@ -69,6 +89,9 @@ public class Credentials { /** * Converts the current object to a serialized form. The object returned from this contains a non-destroyable version of the {@link AuthenticationToken}, so * references to it should be tightly controlled. + * + * @return serialized form of these credentials + * @throws AccumuloSecurityException */ public final String serialize() { return (getPrincipal() == null ? "-" : Base64.encodeBase64String(getPrincipal().getBytes(Constants.UTF8))) + ":" @@ -78,6 +101,9 @@ public class Credentials { /** * Converts the serialized form to an instance of {@link Credentials}. The original serialized form will not be affected. + * + * @param serializedForm serialized form of credentials + * @return deserialized credentials */ public static final Credentials deserialize(String serializedForm) { String[] split = serializedForm.split(":", 3); http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java b/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java index fb6847b..1066bc4 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java +++ b/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java @@ -19,8 +19,14 @@ package org.apache.accumulo.core.security; import java.util.ArrayList; import java.util.List; +/** + * Accumulo namespace permissions. Each permission has an associated byte ID. + */ public enum NamespacePermission { - // One can add new permissions, with new numbers, but please don't change or use numbers previously assigned + /* + * One may add new permissions, but new permissions must use new numbers. + * Current numbers in use must not be changed. + */ READ((byte) 0), WRITE((byte) 1), ALTER_NAMESPACE((byte) 2), @@ -41,10 +47,20 @@ public enum NamespacePermission { this.permID = id; } + /** + * Gets the byte ID of this permission. + * + * @return byte ID + */ public byte getId() { return this.permID; } + /** + * Returns a list of printable permission values. + * + * @return list of namespace permission values, as "Namespace." + permission name + */ public static List<String> printableValues() { NamespacePermission[] a = NamespacePermission.values(); @@ -56,6 +72,13 @@ public enum NamespacePermission { return list; } + /** + * Gets the permission matching the given byte ID. + * + * @param id byte ID + * @return system permission + * @throws IndexOutOfBoundsException if the byte ID is invalid + */ public static NamespacePermission getPermissionById(byte id) { NamespacePermission result = mapping[id]; if (result != null) http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java b/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java index 6bdb8e6..d9109ec 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java +++ b/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java @@ -20,8 +20,14 @@ import java.util.ArrayList; import java.util.HashMap; import java.util.List; +/** + * Accumulo system permissions. Each permission has an associated byte ID. + */ public enum SystemPermission { - // One can add new permissions, with new numbers, but please don't change or use numbers previously assigned + /* + * One may add new permissions, but new permissions must use new numbers. + * Current numbers in use must not be changed. + */ GRANT((byte) 0), CREATE_TABLE((byte) 1), DROP_TABLE((byte) 2), @@ -47,10 +53,20 @@ public enum SystemPermission { this.permID = id; } + /** + * Gets the byte ID of this permission. + * + * @return byte ID + */ public byte getId() { return this.permID; } + /** + * Returns a list of printable permission values. + * + * @return list of system permission values, as "System." + permission name + */ public static List<String> printableValues() { SystemPermission[] a = SystemPermission.values(); @@ -62,6 +78,13 @@ public enum SystemPermission { return list; } + /** + * Gets the permission matching the given byte ID. + * + * @param id byte ID + * @return system permission + * @throws IndexOutOfBoundsException if the byte ID is invalid + */ public static SystemPermission getPermissionById(byte id) { if (mapping.containsKey(id)) return mapping.get(id); http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java b/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java index 912b5fb..05895f5 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java +++ b/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java @@ -19,8 +19,14 @@ package org.apache.accumulo.core.security; import java.util.ArrayList; import java.util.List; +/** + * Accumulo table permissions. Each permission has an associated byte ID. + */ public enum TablePermission { - // One can add new permissions, with new numbers, but please don't change or use numbers previously assigned + /* + * One may add new permissions, but new permissions must use new numbers. + * Current numbers in use must not be changed. + */ // CREATE_LOCALITY_GROUP(0), // DROP_LOCALITY_GROUP(1), READ((byte) 2), @@ -42,10 +48,20 @@ public enum TablePermission { this.permID = id; } + /** + * Gets the byte ID of this permission. + * + * @return byte ID + */ public byte getId() { return this.permID; } + /** + * Returns a list of printable permission values. + * + * @return list of table permission values, as "Table." + permission name + */ public static List<String> printableValues() { TablePermission[] a = TablePermission.values(); @@ -57,6 +73,13 @@ public enum TablePermission { return list; } + /** + * Gets the permission matching the given byte ID. + * + * @param id byte ID + * @return table permission + * @throws IndexOutOfBoundsException if the byte ID is invalid + */ public static TablePermission getPermissionById(byte id) { TablePermission result = mapping[id]; if (result != null) http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java b/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java index ae29cc7..43d89fa 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java +++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java @@ -25,6 +25,15 @@ import org.apache.accumulo.core.data.ColumnUpdate; import org.apache.accumulo.core.data.Mutation; import org.apache.accumulo.core.util.BadArgumentException; +/** + * A constraint that checks the visibility of columns against the actor's + * authorizations. Violation codes: + * <p> + * <ul> + * <li>1 = failure to parse visibility expression</li> + * <li>2 = insufficient authorization</li> + * </ul> + */ public class VisibilityConstraint implements Constraint { @Override http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java b/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java index 45b595f..725b2c7 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java +++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java @@ -21,9 +21,20 @@ import java.util.ArrayList; import org.apache.accumulo.core.constraints.Constraint.Environment; import org.apache.accumulo.core.security.ColumnVisibility.Node; +/** + * A class which evaluates visibility expressions against a set of authorizations. + */ public class VisibilityEvaluator { private AuthorizationContainer auths; + /** + * Creates a new {@link Authorizations} object with escaped forms of the + * authorizations in the given object. + * + * @param auths original authorizations + * @return authorizations object with escaped authorization strings + * @see #escape(byte[], boolean) + */ static Authorizations escape(Authorizations auths) { ArrayList<byte[]> retAuths = new ArrayList<byte[]>(auths.getAuthorizations().size()); @@ -33,6 +44,14 @@ public class VisibilityEvaluator { return new Authorizations(retAuths); } + /** + * Properly escapes an authorization string. The string can be quoted if + * desired. + * + * @param auth authorization string, as UTF-8 encoded bytes + * @param quote true to wrap escaped authorization in quotes + * @return escaped authorization string + */ public static byte[] escape(byte[] auth, boolean quote) { int escapeCount = 0; @@ -59,18 +78,38 @@ public class VisibilityEvaluator { return auth; } + /** + * Creates a new evaluator for the authorizations found in the given + * environment. + * + * @param environment environment containing authorizations + */ VisibilityEvaluator(Environment env) { this.auths = env.getAuthorizationsContainer(); } /** - * The VisibilityEvaluator computes a trie from the given Authorizations, that ColumnVisibility expressions can be evaluated against. + * Creates a new evaluator for the given collection of authorizations. + * Each authorization string is escaped before handling, and the original + * strings are unchanged. + * + * @param authorizations authorizations object */ public VisibilityEvaluator(Authorizations authorizations) { this.auths = escape((Authorizations) authorizations); } + /** + * Evaluates the given column visibility against the authorizations provided to this evaluator. + * A visibility passes evaluation if all authorizations in it are contained in those known to the evaluator, and + * all AND and OR subexpressions have at least two children. + * + * @param visibility column visibility to evaluate + * @return true if visibility passes evaluation + * @throws VisibilityParseException if an AND or OR subexpression has less than two children, or a subexpression is of an unknown type + */ public boolean evaluate(ColumnVisibility visibility) throws VisibilityParseException { + // The VisibilityEvaluator computes a trie from the given Authorizations, that ColumnVisibility expressions can be evaluated against. return evaluate(visibility.getExpression(), visibility.getParseTree()); } http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java b/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java index 2f46dc9..5b4a9f5 100644 --- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java +++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java @@ -18,10 +18,20 @@ package org.apache.accumulo.core.security; import java.text.ParseException; +/** + * An exception thrown when a visibility string cannot be parsed. + */ public class VisibilityParseException extends ParseException { private static final long serialVersionUID = 1L; private String visibility; - + + /** + * Creates a new exception. + * + * @param reason reason string + * @param visibility visibility that could not be parsed + * @param errorOffset offset into visibility where parsing failed + */ public VisibilityParseException(String reason, byte[] visibility, int errorOffset) { super(reason, errorOffset); this.visibility = new String(visibility);
