Fix code blocks in aaf docs 61/54961/1
authorSai Gandham <sg481n@att.com>
Fri, 15 Jun 2018 13:37:30 +0000 (08:37 -0500)
committerSai Gandham <sg481n@att.com>
Fri, 15 Jun 2018 13:37:36 +0000 (08:37 -0500)
Issue-ID: AAF-359
Change-Id: Ib65b9b6eaf6357998b5d75c73e480db7410d9d17
Signed-off-by: Sai Gandham <sg481n@att.com>
docs/sections/configuration/client.rst
docs/sections/configuration/service.rst
docs/sections/installation/AAF-Integration-Guide.rst [new file with mode: 0644]
docs/sections/installation/fromsource.rst
docs/sections/installation/standalone.rst [deleted file]

index 4b8fe20..e0e8880 100644 (file)
@@ -29,4 +29,184 @@ For Beijing, full TLS is expected among all components.  AAF provides the "Certi
 
 Example Source Code
 -------------------
-Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java
\ No newline at end of file
+Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java
+
+.. code-block:: java
+
+
+  /**
+   * ============LICENSE_START====================================================
+   * org.onap.aaf
+   * ===========================================================================
+   * Copyright (c) 2018 AT&T Intellectual Property. All rights reserved.
+   * ===========================================================================
+   * Licensed under the Apache License, Version 2.0 (the "License");
+   * you may not use this file except in compliance with the License.
+   * You may obtain a copy of the License at
+   *
+   *      http://www.apache.org/licenses/LICENSE-2.0
+   *
+   * Unless required by applicable law or agreed to in writing, software
+   * distributed under the License is distributed on an "AS IS" BASIS,
+   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   * See the License for the specific language governing permissions and
+   * limitations under the License.
+   * ============LICENSE_END====================================================
+   *
+   */
+  package org.onap.aaf.client.sample;
+  import java.io.IOException;
+  import java.security.Principal;
+  import java.util.ArrayList;
+  import java.util.List;
+  import org.onap.aaf.cadi.Access;
+  import org.onap.aaf.cadi.CadiException;
+  import org.onap.aaf.cadi.LocatorException;
+  import org.onap.aaf.cadi.Permission;
+  import org.onap.aaf.cadi.PropAccess;
+  import org.onap.aaf.cadi.aaf.AAFPermission;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFConHttp;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm;
+  import org.onap.aaf.cadi.principal.UnAuthPrincipal;
+  import org.onap.aaf.cadi.util.Split;
+  import org.onap.aaf.misc.env.APIException;
+  public class Sample {
+    private static Sample singleton;
+    final private AAFConHttp aafcon;
+    final private AAFLurPerm aafLur;
+    final private AAFAuthn<?> aafAuthn;
+     
+    /**
+     * This method is to emphasize the importance of not creating the AAFObjects over and over again.
+     * @return
+     */
+    public static Sample singleton() {
+        return singleton;
+    }
+    public Sample(Access myAccess) throws APIException, CadiException, LocatorException {
+        aafcon = new AAFConHttp(myAccess);
+        aafLur = aafcon.newLur();
+        aafAuthn = aafcon.newAuthn(aafLur);
+    }
+     
+    /**
+     * Checking credentials outside of HTTP/S presents fewer options initially. There is not, for instance,
+     * the option of using 2-way TLS HTTP/S.
+     * 
+     *  However, Password Checks are still useful, and, if the Client Certificate could be obtained in other ways, the
+     *  Interface can be expanded in the future to include Certificates.
+     * @throws CadiException
+     * @throws IOException
+     */
+    public Principal checkUserPass(String fqi, String pass) throws IOException, CadiException {
+        String ok = aafAuthn.validate(fqi, pass);
+        if(ok==null) {
+            System.out.println("Success!");
+            /*
+             UnAuthPrincipal means that it is not coming from the official Authorization chain.
+             This is useful for Security Plugins which don't use Principal as the tie between
+             Authentication and Authorization
+             
+             You can also use this if you want to check Authorization without actually Authenticating, as may
+             be the case with certain Onboarding Tooling.
+            */
+            return new UnAuthPrincipal(fqi);
+        } else {
+            System.out.printf("Failure: %s\n",ok);
+            return null;
+        }
+         
+    }
+    /**
+     * An example of looking for One Permission within all the permissions user has.  CADI does cache these,
+     * so the call is not expensive.
+     *
+     * Note: If you are using "J2EE" (Servlets), CADI ties this function to the method:
+     *    HttpServletRequest.isUserInRole(String user)
+     *   
+     *  The J2EE user can expect that his servlet will NOT be called without a Validated Principal, and that
+     *  "isUserInRole()" will validate if the user has the Permission designated.
+     * 
+     */
+    public boolean oneAuthorization(Principal fqi, Permission p) {
+        return aafLur.fish(fqi, p);
+    }
+     
+    public List<Permission> allAuthorization(Principal fqi) {
+        List<Permission> pond = new ArrayList<Permission>();
+        aafLur.fishAll(fqi, pond);
+        return pond;
+    }
+     
+     
+    public static void main(String[] args) {
+        // Note: you can pick up Properties from Command line as well as VM Properties
+        // Code "user_fqi=... user_pass=..." (where user_pass can be encrypted) in the command line for this sample.
+        // Also code "perm=<perm type>|<instance>|<action>" to test a specific Permission
+        PropAccess myAccess = new PropAccess(args);
+        try {
+            /*
+             * NOTE:  Do NOT CREATE new aafcon, aafLur and aafAuthn each transaction.  They are built to be
+             * reused!
+             *
+             * This is why this code demonstrates "Sample" as a singleton.
+             */
+            singleton = new Sample(myAccess);
+            String user = myAccess.getProperty("user_fqi");
+            String pass= myAccess.getProperty("user_pass");
+             
+            if(user==null || pass==null) {
+                System.err.println("This Sample class requires properties user_fqi and user_pass");
+            } else {
+                pass =  myAccess.decrypt(pass, false); // Note, with "false", decryption will only happen if starts with "enc:"
+                // See the CODE for Java Methods used
+                Principal fqi = Sample.singleton().checkUserPass(user,pass);
+                 
+                if(fqi==null) {
+                    System.out.println("OK, normally, you would cease processing for an "
+                            + "unauthenticated user, but for the purpose of Sample, we'll keep going.\n");
+                    fqi=new UnAuthPrincipal(user);
+                }
+                 
+                // AGAIN, NOTE: If your client fails Authentication, the right behavior 99.9%
+                // of the time is to drop the transaction.  We continue for sample only.
+                 
+                // note, default String for perm
+                String permS = myAccess.getProperty("perm","org.osaaf.aaf.access|*|read");
+                String[] permA = Split.splitTrim('|', permS);
+                if(permA.length>2) {
+                    final Permission perm = new AAFPermission(permA[0],permA[1],permA[2]);
+                    // See the CODE for Java Methods used
+                    if(singleton().oneAuthorization(fqi, perm)) {
+                        System.out.printf("Success: %s has %s\n",fqi.getName(),permS);
+                    } else {
+                        System.out.printf("%s does NOT have %s\n",fqi.getName(),permS);
+                    }
+                }
+                 
+                 
+                // Another form, you can get ALL permissions in a list
+                // See the CODE for Java Methods used
+                List<Permission> permL = singleton().allAuthorization(fqi);
+                if(permL.size()==0) {
+                    System.out.printf("User %s has no Permissions THAT THE CALLER CAN SEE",fqi.getName());
+                } else {
+                    System.out.print("Success:\n");
+                    for(Permission p : permL) {
+                        System.out.printf("\t%s has %s\n",fqi.getName(),p.getKey());
+                    }
+                }
+            }
+        } catch (APIException | CadiException | LocatorException | IOException e) {
+            e.printStackTrace();
+        }
+    }
+  }
\ No newline at end of file
index ae5d030..8b48ddc 100644 (file)
@@ -48,59 +48,64 @@ b.  This might be helpful for covering separate Management Servlet implementation
 Servlet Code Snippet
 =========================
 
-public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
-    HttpServletRequest request;
-    try {
-        request = (HttpServletRequest)req;
-    } catch (ClassCastException e) {
-        throw new ServletException("Only serving HTTP today",e);
-    }
+.. code-block:: java
+
+  public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
+      HttpServletRequest request;
+      try {
+          request = (HttpServletRequest)req;
+      } catch (ClassCastException e) {
+         throw new ServletException("Only serving HTTP today",e);
+      }
      
-    // Note: CADI is OVERLOADING the concept of "isUserInRole".. You need to think "doesUserHavePermssion()"
-    // Assume that you have CREATED and GRANTED An AAF Permission in YOUR Namespace
-    // Example Permission:   "org.onap.aaf.myapp.myPerm * write"
+      // Note: CADI is OVERLOADING the concept of "isUserInRole".. You need to think "doesUserHavePermssion()"
+      // Assume that you have CREATED and GRANTED An AAF Permission in YOUR Namespace
+      // Example Permission:   "org.onap.aaf.myapp.myPerm * write"
  
-    // Think in your head, "Does user have write permission on any instance of org.onap.aaf.myapp.myPerm
-    if(request.isUserInRole("org.onap.aaf.myapp.myPerm|*|write")) { 
-        // *** Do something here that someone with "myPerm write" permissions is allowed to do
-    } else {
-        // *** Do something reasonable if user is denied, like an Error Message
-    }
+      // Think in your head, "Does user have write permission on any instance of org.onap.aaf.myapp.myPerm
+      if(request.isUserInRole("org.onap.aaf.myapp.myPerm|*|write")) { 
+          // *** Do something here that someone with "myPerm write" permissions is allowed to do
+      } else {
+          // *** Do something reasonable if user is denied, like an Error Message
+      }
  
-}
+    }
 
 Here is a working TestServlet, where you can play with different Permissions that you own on the URL, i.e.:
 https://<your machine:port>/caditest/testme?PERM=org.onap.aaf.myapp.myPerm|*|write
 
 Sample Servlet (Working example)
 ================================
-package org.onap.aaf.cadi.debug;
-import java.io.FileInputStream;
-import java.io.IOException;
-import java.net.InetAddress;
-import java.net.UnknownHostException;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.Map.Entry;
-import java.util.Properties;
-import javax.servlet.Servlet;
-import javax.servlet.ServletConfig;
-import javax.servlet.ServletException;
-import javax.servlet.ServletRequest;
-import javax.servlet.ServletResponse;
-import javax.servlet.http.HttpServletRequest;
-import org.eclipse.jetty.server.Server;
-import org.eclipse.jetty.server.ServerConnector;
-import org.eclipse.jetty.server.handler.ContextHandler;
-import org.eclipse.jetty.servlet.FilterHolder;
-import org.eclipse.jetty.servlet.FilterMapping;
-import org.eclipse.jetty.servlet.ServletContextHandler;
-import org.eclipse.jetty.servlet.ServletHandler;
-import org.onap.aaf.cadi.filter.CadiFilter;
-import org.onap.aaf.cadi.filter.RolesAllowed;
-import org.onap.aaf.cadi.jetty.MiniJASPIWrap;
+
+.. code-block:: java
+
+  package org.onap.aaf.cadi.debug;
+  import java.io.FileInputStream;
+  import java.io.IOException;
+  import java.net.InetAddress;
+  import java.net.UnknownHostException;
+  import java.util.HashMap;
+  import java.util.Map;
+  import java.util.Map.Entry;
+  import java.util.Properties;
+  import javax.servlet.Servlet;
+  import javax.servlet.ServletConfig;
+  import javax.servlet.ServletException;
+  import javax.servlet.ServletRequest;
+  import javax.servlet.ServletResponse;
+  import javax.servlet.http.HttpServletRequest;
+  import org.eclipse.jetty.server.Server;
+  import org.eclipse.jetty.server.ServerConnector;
+  import org.eclipse.jetty.server.handler.ContextHandler;
+  import org.eclipse.jetty.servlet.FilterHolder;
+  import org.eclipse.jetty.servlet.FilterMapping;
+  import org.eclipse.jetty.servlet.ServletContextHandler;
+  import org.eclipse.jetty.servlet.ServletHandler;
+  import org.onap.aaf.cadi.filter.CadiFilter;
+  import org.onap.aaf.cadi.filter.RolesAllowed;
+  import org.onap.aaf.cadi.jetty.MiniJASPIWrap;
  
-public class CSPServletTest {
+  public class CSPServletTest {
     public static void main(String[] args) {
         // Go ahead and print Test reports in cadi-core first
         Test.main(args);
@@ -226,27 +231,30 @@ public class CSPServletTest {
         public void destroy() {
         }
     }
-}
+   }
  
 Java Direct (AAFLur) Method
 ===========================
 The AAFLur is the exact component used within all the Plugins mentioned above.  It is written so that it can be called standalone as well, see the Example as follows
-package org.onap.aaf.example;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Properties;
-
-import org.onap.aaf.cadi.Access;
-import org.onap.aaf.cadi.Permission;
-import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn;
-import org.onap.aaf.cadi.aaf.v2_0.AAFCon;
-import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm;
-import org.onap.aaf.cadi.config.Config;
-import org.onap.aaf.cadi.lur.aaf.AAFPermission;
-import org.onap.aaf.cadi.lur.aaf.test.TestAccess;
-
-public class ExamplePerm2_0 {
+
+.. code-block:: java
+
+  package org.onap.aaf.example;
+
+  import java.util.ArrayList;
+  import java.util.List;
+  import java.util.Properties;
+
+  import org.onap.aaf.cadi.Access;
+  import org.onap.aaf.cadi.Permission;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFCon;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm;
+  import org.onap.aaf.cadi.config.Config;
+  import org.onap.aaf.cadi.lur.aaf.AAFPermission;
+  import org.onap.aaf.cadi.lur.aaf.test.TestAccess;
+
+  public class ExamplePerm2_0 {
        public static void main(String args[]) {
                // Normally, these should be set in environment.  Setting here for clarity
                Properties props = System.getProperties();
@@ -259,8 +267,8 @@ public class ExamplePerm2_0 {
                props.setProperty(Config.AAF_USER_EXPIRES,Integer.toString(5*60000));   // 5 minutes for found items to live in cache
                props.setProperty(Config.AAF_HIGH_COUNT,Integer.toString(400));         // Maximum number of items in Cache);
                props.setProperty(Config.CADI_KEYFILE,"keyfile"); //Note: Be sure to generate with java -jar <cadi_path>/lib/cadi-core*.jar keygen keyfile
-//             props.setProperty("DME2_EP_REGISTRY_CLASS","DME2FS");
-//             props.setProperty("AFT_DME2_EP_REGISTRY_FS_DIR","../../authz/dme2reg");
+  //           props.setProperty("DME2_EP_REGISTRY_CLASS","DME2FS");
+  //           props.setProperty("AFT_DME2_EP_REGISTRY_FS_DIR","../../authz/dme2reg");
 
                
                // Link or reuse to your Logging mechanism
@@ -335,8 +343,9 @@ public class ExamplePerm2_0 {
                }
 
        }
-}
+  }
 
+  
 There are two current AAF Lurs which you can utilize:
 •    Org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm is the default, and will fish based on the Three-fold "Permission" standard in AAF
 To run this code, you will need from a SWM deployment (org.onap.aaf.cadi:cadi, then soft link to jars needed):
diff --git a/docs/sections/installation/AAF-Integration-Guide.rst b/docs/sections/installation/AAF-Integration-Guide.rst
new file mode 100644 (file)
index 0000000..9732764
--- /dev/null
@@ -0,0 +1,76 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
+
+AAF Integration Guide
+============================
+.. code:: bash
+
+   cadi.properties Template
+  # This is a normal Java Properties File
+  # Comments are with Pound Signs at beginning of lines,
+  # and multi-line expression of properties can be obtained by backslash at end of line
+  #hostname=
+
+  cadi_loglevel=WARN
+  cadi_keyfile=conf/keyfile
+
+
+  # Configure AAF
+  aaf_url=http://172.18.0.2:8101
+  #if you are running aaf service from a docker image you have to use aaf service IP and port number
+  aaf_id=<yourAPPID>@onap.org
+  aaf_password=enc:<encrypt>
+
+  aaf_dme_timeout=5000
+  # Note, User Expires for not Unit Test should be something like 900000 (15 mins) default is 10 mins
+  # 15 seconds is so that Unit Tests don't delay compiles, etc
+  aaf_user_expires=15000
+  # High count... Rough top number of objects held in Cache per cycle.  If high is reached, more are
+  # recycled next time.  Depending on Memory usage, 2000 is probably decent.  1000 is default
+  aaf_high_count=100
+
+
+How to create CADI Keyfile & Encrypt Password
+---------------------------------------------
+
+Password Encryption
+-------------------
+CADI provides a method to encrypt data so that Passwords and other sensitive data can be stored safely.
+
+Keygen (Generate local Symmetrical Key)
+A Keyfile is created by Cadi Utility.
+
+.. code:: bash
+
+  java -jar cadi-core-<version>.jar keygen <keyfile>
+Given this key file unlocks any passwords created, it should be stored in your configuration directory and protected with appropriate access permissions. For instance, if your container is Tomcat, and runs with a "tomcat" id, then you should:
+
+.. code:: bash
+
+  java -jar cadi-core-<version>.jar keygen keyfile
+  chmod 400 keyfile
+  chown tomcat:tomcat keyfile
+  
+Digest - Encrypt a Password
+---------------------------
+The password is obtained by using the Cadi digest Utility (contained in the cadi-core-<version>.jar).
+
+.. code:: bash
+
+  java -jar cadi-core-<version>.jar digest <your_password> <keyfile>
+   • "<keyfile>" is created by Cadi Utility, #keygen
+   • Understand that if you change the keyfile, then you need to rerun "digest" on passwords used in the users/groups definitions.
+   • Note: You cannot mix versions of cadi; the version used to digest your password must be the same version used at runtime.
+   
+CADI PROPERTIES
+   CADI properties, typically named "cadi.properties", must have passwords encrypted.
+      1.       Take the results of the "Digest" command and prepend "enc:"
+      2.       Use this as the value of your property
+         
+Example:   aaf_password=enc:fMKMBfKHlRWL68cxD5XSIWNKRNYi5dih2LEHRFMIsut
+
index 6586ff5..19ac622 100644 (file)
@@ -5,3 +5,186 @@
 AAF From Source Code
 ====================
 
+Example Source Code
+-------------------
+Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java
+
+.. code-block:: java
+
+
+  /**
+   * ============LICENSE_START====================================================
+   * org.onap.aaf
+   * ===========================================================================
+   * Copyright (c) 2018 AT&T Intellectual Property. All rights reserved.
+   * ===========================================================================
+   * Licensed under the Apache License, Version 2.0 (the "License");
+   * you may not use this file except in compliance with the License.
+   * You may obtain a copy of the License at
+   *
+   *      http://www.apache.org/licenses/LICENSE-2.0
+   *
+   * Unless required by applicable law or agreed to in writing, software
+   * distributed under the License is distributed on an "AS IS" BASIS,
+   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   * See the License for the specific language governing permissions and
+   * limitations under the License.
+   * ============LICENSE_END====================================================
+   *
+   */
+  package org.onap.aaf.client.sample;
+  import java.io.IOException;
+  import java.security.Principal;
+  import java.util.ArrayList;
+  import java.util.List;
+  import org.onap.aaf.cadi.Access;
+  import org.onap.aaf.cadi.CadiException;
+  import org.onap.aaf.cadi.LocatorException;
+  import org.onap.aaf.cadi.Permission;
+  import org.onap.aaf.cadi.PropAccess;
+  import org.onap.aaf.cadi.aaf.AAFPermission;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFConHttp;
+  import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm;
+  import org.onap.aaf.cadi.principal.UnAuthPrincipal;
+  import org.onap.aaf.cadi.util.Split;
+  import org.onap.aaf.misc.env.APIException;
+  public class Sample {
+    private static Sample singleton;
+    final private AAFConHttp aafcon;
+    final private AAFLurPerm aafLur;
+    final private AAFAuthn<?> aafAuthn;
+     
+    /**
+     * This method is to emphasize the importance of not creating the AAFObjects over and over again.
+     * @return
+     */
+    public static Sample singleton() {
+        return singleton;
+    }
+    public Sample(Access myAccess) throws APIException, CadiException, LocatorException {
+        aafcon = new AAFConHttp(myAccess);
+        aafLur = aafcon.newLur();
+        aafAuthn = aafcon.newAuthn(aafLur);
+    }
+     
+    /**
+     * Checking credentials outside of HTTP/S presents fewer options initially. There is not, for instance,
+     * the option of using 2-way TLS HTTP/S.
+     * 
+     *  However, Password Checks are still useful, and, if the Client Certificate could be obtained in other ways, the
+     *  Interface can be expanded in the future to include Certificates.
+     * @throws CadiException
+     * @throws IOException
+     */
+    public Principal checkUserPass(String fqi, String pass) throws IOException, CadiException {
+        String ok = aafAuthn.validate(fqi, pass);
+        if(ok==null) {
+            System.out.println("Success!");
+            /*
+             UnAuthPrincipal means that it is not coming from the official Authorization chain.
+             This is useful for Security Plugins which don't use Principal as the tie between
+             Authentication and Authorization
+             
+             You can also use this if you want to check Authorization without actually Authenticating, as may
+             be the case with certain Onboarding Tooling.
+            */
+            return new UnAuthPrincipal(fqi);
+        } else {
+            System.out.printf("Failure: %s\n",ok);
+            return null;
+        }
+         
+    }
+    /**
+     * An example of looking for One Permission within all the permissions user has.  CADI does cache these,
+     * so the call is not expensive.
+     *
+     * Note: If you are using "J2EE" (Servlets), CADI ties this function to the method:
+     *    HttpServletRequest.isUserInRole(String user)
+     *   
+     *  The J2EE user can expect that his servlet will NOT be called without a Validated Principal, and that
+     *  "isUserInRole()" will validate if the user has the Permission designated.
+     * 
+     */
+    public boolean oneAuthorization(Principal fqi, Permission p) {
+        return aafLur.fish(fqi, p);
+    }
+     
+    public List<Permission> allAuthorization(Principal fqi) {
+        List<Permission> pond = new ArrayList<Permission>();
+        aafLur.fishAll(fqi, pond);
+        return pond;
+    }
+     
+     
+    public static void main(String[] args) {
+        // Note: you can pick up Properties from Command line as well as VM Properties
+        // Code "user_fqi=... user_pass=..." (where user_pass can be encrypted) in the command line for this sample.
+        // Also code "perm=<perm type>|<instance>|<action>" to test a specific Permission
+        PropAccess myAccess = new PropAccess(args);
+        try {
+            /*
+             * NOTE:  Do NOT CREATE new aafcon, aafLur and aafAuthn each transaction.  They are built to be
+             * reused!
+             *
+             * This is why this code demonstrates "Sample" as a singleton.
+             */
+            singleton = new Sample(myAccess);
+            String user = myAccess.getProperty("user_fqi");
+            String pass= myAccess.getProperty("user_pass");
+             
+            if(user==null || pass==null) {
+                System.err.println("This Sample class requires properties user_fqi and user_pass");
+            } else {
+                pass =  myAccess.decrypt(pass, false); // Note, with "false", decryption will only happen if starts with "enc:"
+                // See the CODE for Java Methods used
+                Principal fqi = Sample.singleton().checkUserPass(user,pass);
+                 
+                if(fqi==null) {
+                    System.out.println("OK, normally, you would cease processing for an "
+                            + "unauthenticated user, but for the purpose of Sample, we'll keep going.\n");
+                    fqi=new UnAuthPrincipal(user);
+                }
+                 
+                // AGAIN, NOTE: If your client fails Authentication, the right behavior 99.9%
+                // of the time is to drop the transaction.  We continue for sample only.
+                 
+                // note, default String for perm
+                String permS = myAccess.getProperty("perm","org.osaaf.aaf.access|*|read");
+                String[] permA = Split.splitTrim('|', permS);
+                if(permA.length>2) {
+                    final Permission perm = new AAFPermission(permA[0],permA[1],permA[2]);
+                    // See the CODE for Java Methods used
+                    if(singleton().oneAuthorization(fqi, perm)) {
+                        System.out.printf("Success: %s has %s\n",fqi.getName(),permS);
+                    } else {
+                        System.out.printf("%s does NOT have %s\n",fqi.getName(),permS);
+                    }
+                }
+                 
+                 
+                // Another form, you can get ALL permissions in a list
+                // See the CODE for Java Methods used
+                List<Permission> permL = singleton().allAuthorization(fqi);
+                if(permL.size()==0) {
+                    System.out.printf("User %s has no Permissions THAT THE CALLER CAN SEE",fqi.getName());
+                } else {
+                    System.out.print("Success:\n");
+                    for(Permission p : permL) {
+                        System.out.printf("\t%s has %s\n",fqi.getName(),p.getKey());
+                    }
+                }
+            }
+        } catch (APIException | CadiException | LocatorException | IOException e) {
+            e.printStackTrace();
+        }
+    }
+  }
\ No newline at end of file
diff --git a/docs/sections/installation/standalone.rst b/docs/sections/installation/standalone.rst
deleted file mode 100644 (file)
index 5c8cb65..0000000
+++ /dev/null
@@ -1,7 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
-
-Standalone Java Installation
-============================
-