svn commit: r1515678 - in /commons/sandbox/weaver/trunk/modules/privilizer/src: ./ site/ site/markdown/ site/markdown/index.md

[mb...@apache.org]

Author: mbenson
Date: Tue Aug 20 00:30:52 2013
New Revision: 1515678

URL: http://svn.apache.org/r1515678
Log:
document privilizer

Added:
    commons/sandbox/weaver/trunk/modules/privilizer/src/
    commons/sandbox/weaver/trunk/modules/privilizer/src/site/
    commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/
    commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/index.md

Added: commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/index.md
URL: http://svn.apache.org/viewvc/commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/index.md?rev=1515678&view=auto
==============================================================================
--- commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/index.md (added)
+++ commons/sandbox/weaver/trunk/modules/privilizer/src/site/markdown/index.md Tue Aug 20 00:30:52 2013
@@ -0,0 +1,96 @@
+## Apache Commons Weaver Privilizer
+
+Provides machinery to automate the handling of Java Security access
+controls in code.  This involves wrapping calls that may trigger
+`java.lang.SecurityException`s in `PrivilegedAction` objects.
+Unfortunately this is quite an expensive operation and slows code
+down considerably; when executed in an environment that has no
+`SecurityManager` activated it is an utter waste.
+The typical pattern to cope with this is:
+
+```java
+if (System.getSecurityManager() != null) {
+  AccessController.doPrivileged(new PrivilegedAction<Void>() {
+    public Void run() {
+      doSomethingThatRequiresPermissions();
+      return null;
+    }
+  });
+} else {
+  doSomethingThatRequiresPermissions();
+}
+```
+
+This becomes tedious in short order.  The immediate response of a
+typical developer:  relegate the repetitive code to a set of
+utility methods.  In the case of Java security, however, this
+approach is considered risky.  The purpose of the Privilizer, then,
+is to instrument compiled methods originally annotated with our
+`@Privileged` annotation.  This annotation is retained in the
+classfiles, but not available at runtime, and there are no runtime
+dependencies.
+
+### Basic Privilization
+
+```java
+
+@Privileged
+private void doSomethingThatRequiresPermissions() {
+  ...
+}
+```
+
+Annotating a method with the [@Privileged][privileged] annotation will cause
+the [PrivilizerWeaver][privilizerWeaver] to generate these checks automatically,
+leaving you to simply implement the code!
+
+### Blueprint Privilization
+The so-called "blueprint" feature returns to the concept of static utility
+methods.  Why are these considered a liability?  Because your trusted code
+presumptuously extends your trust via public methods to any class in the JVM,
+almost certainly contrary to the wishes of the owner of that JVM. Our
+blueprint technique allows you to define (or reuse) static utility methods
+in a secure way:  simply define these utility methods in a
+`SecurityManager`-agnostic manner and let the consuming class request that
+calls to them be treated as blueprints for `@Privileged` methods:
+
+```java
+public class Utils {
+  public static void doSomethingThatRequiresPrivileges() {
+    ...
+  }
+}
+
+@Privilizing(CallTo(Utils.class))
+public class UtilsClient {
+  public void foo() {
+    Utils.doSomethingThatRequiresPrivileges();
+  }
+}
+```
+
+The static methods of the `Utils` class will be called as though they had been
+locally declared and annotated with `@Privileged`.
+
+*Q:* What if my utility methods access static variables of their declaring class?
+
+*A:* The imported methods reference those fields via reflection; i.e. the
+    original fields are used.
+
+*Q:* Does this modify the accessibility of those fields?
+
+*A:* Yes, but only for the duration of the method implementation.  The fields'
+    accessibility is checked before execution, and if a given field is not
+    accessible on the way in, it will be restored to its original state in
+    a `finally` block.
+
+### Configuration
+The `PrivilizerWeaver` supports the following options:
+
+- `privilizer.accessLevel` : name of the highest [AccessLevel][accessLevel] to privilize (default `PRIVATE`)
+- `privilizer.policy` : name of the [Policy][policy] (determines when to check for a `SecurityManager`)
+
+[privileged]: ../../apidocs/org/apache/commons/weaver/privilizer/Privileged.html
+[privilizerWeaver]: ../../apidocs/org/apache/commons/weaver/privilizer/PrivilizerWeaver.html
+[policy]: ../../apidocs/org/apache/commons/weaver/privilizer/Policy.html
+[accessLevel]: ../../apidocs/org/apache/commons/weaver/privilizer/AccessLevel.html