This is an automated email from the ASF dual-hosted git repository.
kturner pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/accumulo-access.git
The following commit(s) were added to refs/heads/main by this push:
new eb3de35 improves project documentation (#15)
eb3de35 is described below
commit eb3de35356f25ec690dc658f1e2c16450c6cd3e6
Author: Keith Turner <ktur...@apache.org>
AuthorDate: Tue Sep 26 11:37:03 2023 -0400
improves project documentation (#15)
---
README.md | 32 +++++++----------
SPECIFICATION.md | 40 ++++++++++++++++------
.../apache/accumulo/access/AccessEvaluator.java | 5 ++-
.../apache/accumulo/access/AccessExpression.java | 38 +++++++++++---------
.../access/IllegalAccessExpressionException.java | 4 +--
5 files changed, 67 insertions(+), 52 deletions(-)
diff --git a/README.md b/README.md
index 2b86199..e43991c 100644
--- a/README.md
+++ b/README.md
@@ -21,33 +21,25 @@
# Accumulo Access Control Library
-This library is a stand-alone java library that provides the functionality of
the Apache Accumulo ColumnVisibility for use outside of Accumulo.
+Java library that provides the same functionality, semantics, and syntax as the
+Apache Accumulo [ColumnVisibility][1] and [VisibilityEvaluator][2] classes.
+This functionality is provided in a standalone java library that has no
+dependencies (for example no Hadoop, Zookeeper, Thrift, etc dependencies).
-## Concepts
-
- * AccessExpression - a boolean expression of attributes required to access an
object (e.g. Key/Value pair in Accumulo). See SPECIFICATION.md.
- * Authorizations - a set of attributes, typically attributed to the entity
trying to access an object.
- * AccessEvaluator - An object that determines if the entity can access the
object using the entity's Authorizations and the objects AccessExpression.
-
-## Goals
-
- * Create a standalone java library that offers the Accumulo visibility
functionality
- * Support the same syntax and semantics as ColumnVisibility and
VisibilityEvaluator initially. This will allow ColumnVisibility and
VisibilityEvaluator to adapt to use this new library for their implementation.
- * Have no dependencies for this new library
- * Use no external types (like Hadoop types) in its API.
- * Use semantic versioning.
+For a conceptual overview of what an access expression is see the
+[specification](SPECIFICATION.md) document. See the [getting started
+guide](contrib/getting-started/README.md) for an example of how to use
+this java library.
## Public API
-The following types constitute the public API of this library. All other types
are package private and are not part of the public API.
+The following types constitute the public API of this library. All other types
+are package private and are not part of the public API.
*
[IllegalAccessExpressionException](src/main/java/org/apache/accumulo/access/IllegalAccessExpressionException.java).
*
[AccessEvaluator](src/main/java/org/apache/accumulo/access/AccessEvaluator.java).
*
[AccessExpression](src/main/java/org/apache/accumulo/access/AccessExpression.java).
*
[Authorizations](src/main/java/org/apache/accumulo/access/Authorizations.java).
-For an example of using this library see the [unit
test](src/test/java/org/apache/accumulo/access/AccessEvaluatorTest.java).
-
-See the [specification](SPECIFICATION.md) for details about access expressions.
-
-See the [getting started guide](contrib/getting-started/README.md) for a
simple example of how to use this java library.
+[1]:https://github.com/apache/accumulo/blob/rel/2.1.2/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java
+[2]:https://github.com/apache/accumulo/blob/rel/2.1.2/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
diff --git a/SPECIFICATION.md b/SPECIFICATION.md
index 51d99db..303857f 100644
--- a/SPECIFICATION.md
+++ b/SPECIFICATION.md
@@ -25,6 +25,12 @@ This document specifies the format of an Apache Accumulo
AccessExpression. An Ac
is an encoding of a boolean expression of the attributes that an entity is
required to have to
access a particular piece of data.
+## Concepts
+
+* AccessExpression - a boolean expression of attributes required to access an
object (e.g. Key/Value pair in Accumulo).
+* Authorizations - a set of attributes, typically attributed to the entity
trying to access an object.
+* AccessEvaluator - An object that determines if the entity can access the
object using the entity's Authorizations and the objects AccessExpression.
+
## Syntax
The formal definition of the AccessExpression UTF-8 string representation is
provided by
@@ -50,6 +56,20 @@ escaped = "\" DQUOTE / "\\"
slash = "/"
```
+The following are examples of proper expressions that the above rules would
match.
+
+ * `BLUE`
+ * `RED&BLUE`
+ * `RED&BLUE&GREEN`
+ * `(RED&BLUE)|(GREEN&(PINK|PURPLE))`
+
+The following are example of improper expressions that the rules would not
match and reasons they do not match.
+
+* `&BLUE` : Must start with an access token or a paren expression
+* `(RED&BLUE)|` : An access token or paren expression must follow a `|`
+* `RED&BLUE|GREEN` : Once a `&` is seen then can only have `&` and not `|`,
unless using parenthesis.
+* `RED|BLUE&GREEN` : Once a `|` is seen then can only have `|`and not `&`,
unless using parenthesis.
+
## Serialization
An AccessExpression is a UTF-8 string. It can be serialized using a byte array
as long as it
@@ -66,28 +86,28 @@ boolean algebra.
* The symbol `|` in an access expression represents [logical disjunction][5]
which is represented in a boolean algebra as `∨`.
-When evaluating an access expression set existence checks are done against a
-subjects set of authorizations. The following is an algorithm for evaluation an
+When evaluating an access expression set existence checks are done against an
+entities set of authorizations. The following is an algorithm for evaluation an
access expression.
1. For each access-token in an access expression check if it exists in the
- subjects set of authorizations. Replace the access-token with `true` if it
+ entities set of authorizations. Replace the access-token with `true` if it
exists in the set and `false` otherwise.
2. Evaluate the expression using boolean algebra and only if its true can the
- subject access the data labeled with the access expression.
+ entity access the data labeled with the access expression.
The following is an example of evaluating the access expression
-`RED&(BLUE|GREEN)` using boolean algebra for a subject with the authorization
+`RED&(BLUE|GREEN)` using boolean algebra for an entity with the authorization
set `{RED,GREEN}`. In the example below `RED ∈ {RED,GREEN}` translates to does
`RED` exist in the set `{RED,GREEN}` which it does, so it is true.
1. RED ∈ {RED,GREEN} ∧ ( BLUE ∈ {RED,GREEN} ∨ GREEN ∈ {RED,GREEN} )
2. true ∧ ( false ∨ true )
-Since `true ∧ ( false ∨ true )` is true then the subject with authorizations
+Since `true ∧ ( false ∨ true )` is true then the entity with authorizations
`{RED,GREEN}` can access data labeled with the access expression
`RED&(BLUE|GREEN)`. The access expression `(RED&BLUE)|(GREEN&PINK)` is an
-example of an access expression that is false for a subject with authorizations
+example of an access expression that is false for an entity with authorizations
`{RED,GREEN}` and it would look like the following using boolean algebra.
1. ( RED ∈ {RED,GREEN} ∧ BLUE ∈ {RED,GREEN} ) ∨ ( GREEN ∈ {RED,GREEN} ∧ PINK ∈
@@ -95,7 +115,7 @@ example of an access expression that is false for a subject
with authorizations
2. ( true ∧ false ) ∨ ( true ∧ false )
An empty access expression always evaluates to true and this is only thing a
-subject with the empty set of authorizations can access.
+entity with the empty set of authorizations can access.
## Escaping
@@ -103,10 +123,10 @@ Access tokens can only contain alpha numeric characters
or the characters
`_`,`-`,`.`,`:`, or `/` unless quoted using `"`. Within quotes the characters
`"` and `\` must escaped by prefixing with `\`. For example to use `abc\xyz` as
an access-token it would need to be quoted and escaped like `"abc\\xyz"`. When
-checking if an access-token exists in the subjects authorizations set it must
+checking if an access-token exists in the entities authorizations set it must
be unquoted and unescaped.
-Evaluating `"abc!12"&"abc\\xyz"&GHI`for a subject with authorizations
+Evaluating `"abc!12"&"abc\\xyz"&GHI`for an entity with authorizations
`{abc\xyz,abc!12}` looks like the following in boolean algebra which evaluates
to `false`.
diff --git a/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
b/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
index 0f579d0..34f45c1 100644
--- a/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
+++ b/src/main/java/org/apache/accumulo/access/AccessEvaluator.java
@@ -22,8 +22,7 @@ import java.util.Collection;
/**
* <p>
- * An implementation of the Accumulo visibility standard as specified in this
document (TODO write
- * the document based on current Accumulo implementation and post somewhere).
+ * Used to decide if an entity with one more sets of authorizations can access
zero or more access expression.
*
* <p>
* Below is an example that should print false and then print true.
@@ -37,7 +36,7 @@ import java.util.Collection;
* }
* </pre>
*
- *
+ * @see <a href="https://github.com/apache/accumulo-access";>Accumulo Access
Documentation</a>
* @since 1.0.0
*/
public interface AccessEvaluator {
diff --git a/src/main/java/org/apache/accumulo/access/AccessExpression.java
b/src/main/java/org/apache/accumulo/access/AccessExpression.java
index 8bf8ada..c7022f0 100644
--- a/src/main/java/org/apache/accumulo/access/AccessExpression.java
+++ b/src/main/java/org/apache/accumulo/access/AccessExpression.java
@@ -19,16 +19,9 @@
package org.apache.accumulo.access;
/**
- * An opaque type that contains a parsed visibility expression. When this type
is constructed with
+ * An opaque type that contains a parsed access expression. When this type is
constructed with
* {@link #of(String)} and then used with {@link
AccessEvaluator#canAccess(AccessExpression)} it can
- * be more efficient and avoid reparsing the expression.
- *
- * <p>
- * For reviewers : this type is similar to ColumnVisibility. This interface
and impl have goal of
- * being immutable which differs from column visibility. ColumnVisibility
leaks internal
- * implementation details in its public API, this type does not.
- *
- * TODO needs better javadoc.
+ * be more efficient and avoid re-parsing the expression.
*
* Below is an example of using this API.
*
@@ -53,6 +46,7 @@ package org.apache.accumulo.access;
* [🦖, CAT, 🦕]
* </pre>
*
+ * @see <a href="https://github.com/apache/accumulo-access";>Accumulo Access
Documentation</a>
* @since 1.0.0
*/
public interface AccessExpression {
@@ -63,7 +57,13 @@ public interface AccessExpression {
String getExpression();
/**
- * TODO give examples
+ * Deduplicate, sort, and flatten expressions.
+ *
+ * <p>As an example of flattening, the expression {@code A&(B&C)} can be
flattened to {@code A&B&C}.
+ *
+ * <p>As an example of sorting, the expression {@code (Z&Y)|(C&B)} can be
sorted to {@code (B&C)|(Y&Z)}
+ *
+ * <p>As an example of deduplication, the expression {@code X&Y&X} is
equivalent to {@code X&Y}
*
* @return A normalized version of the visibility expression that removes
duplicates and orders
* the expression in a consistent way.
@@ -80,7 +80,9 @@ public interface AccessExpression {
return new AccessExpressionImpl(expression);
}
- // TODO document utf8 expectations
+ /**
+ * @param expression is expected to be encoded using UTF-8
+ */
static AccessExpression of(byte[] expression) throws
IllegalAccessExpressionException {
return new AccessExpressionImpl(expression);
}
@@ -93,18 +95,20 @@ public interface AccessExpression {
}
/**
- * Authorizations occurring a visibility expression can only contain the
characters TODO unless
- * quoted. Use this method to quote authorizations that occur in a
visibility expression. This
- * method will only quote if its needed.
+ * Authorizations occurring in an access expression can only contain the
characters listed in the
+ * <a
href="https://github.com/apache/accumulo-access/blob/main/SPECIFICATION.md";>specification</a>
+ * unless quoted. Use this method to quote authorizations that occur in an
access expression. This
+ * method will only quote if it is needed.
*/
static byte[] quote(byte[] authorization) {
return AccessExpressionImpl.quote(authorization);
}
/**
- * Authorizations occurring a visibility expression can only contain the
characters TODO unless
- * quoted. Use this method to quote authorizations that occur in a
visibility expression. This
- * method will only quote if its needed.
+ * Authorizations occurring in an access expression can only contain the
characters listed in the
+ * <a
href="https://github.com/apache/accumulo-access/blob/main/SPECIFICATION.md";>specification</a>
+ * unless quoted. Use this method to quote authorizations that occur in an
access expression. This
+ * method will only quote if it is needed.
*/
static String quote(String authorization) {
return AccessExpressionImpl.quote(authorization);
diff --git
a/src/main/java/org/apache/accumulo/access/IllegalAccessExpressionException.java
b/src/main/java/org/apache/accumulo/access/IllegalAccessExpressionException.java
index 77424b8..180c844 100644
---
a/src/main/java/org/apache/accumulo/access/IllegalAccessExpressionException.java
+++
b/src/main/java/org/apache/accumulo/access/IllegalAccessExpressionException.java
@@ -21,9 +21,9 @@ package org.apache.accumulo.access;
import java.util.regex.PatternSyntaxException;
/**
- * TODO document
+ * An exception that is thrown when an access expression is not correct.
*
- * @since ???
+ * @since 1.0.0
*/
public final class IllegalAccessExpressionException extends
PatternSyntaxException {
private static final long serialVersionUID = 1L;
