You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@accumulo.apache.org by md...@apache.org on 2013/12/28 01:51:57 UTC
[1/3] git commit: ACCUMULO-2030 Javadoc for core/security.
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 <bh...@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);
[3/3] git commit: Merge branch '1.6.0-SNAPSHOT'
Posted by md...@apache.org.
Merge branch '1.6.0-SNAPSHOT'
Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/2c37c451
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/2c37c451
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/2c37c451
Branch: refs/heads/master
Commit: 2c37c4517a4d967a0f3da94fed19aee9ae029d03
Parents: ce8a568 c41900e
Author: Mike Drob <md...@cloudera.com>
Authored: Fri Dec 27 16:51:47 2013 -0800
Committer: Mike Drob <md...@cloudera.com>
Committed: Fri Dec 27 16:51:47 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(-)
----------------------------------------------------------------------
[2/3] git commit: ACCUMULO-2030 Javadoc for core/security.
Posted by md...@apache.org.
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/master
Commit: c41900edca7c58e583323ec57c8aff2ccde91660
Parents: bea6e94
Author: Bill Havanki <bh...@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);