[jboss-cvs] JBossAS SVN: r63108 - in projects/security/security-docs/trunk/docs/guide/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed May 16 23:04:57 EDT 2007
Author: anil.saldhana at jboss.com
Date: 2007-05-16 23:04:57 -0400 (Wed, 16 May 2007)
New Revision: 63108
Added:
projects/security/security-docs/trunk/docs/guide/en/modules/auditmgr.xml
projects/security/security-docs/trunk/docs/guide/en/modules/authenticationmgr.xml
projects/security/security-docs/trunk/docs/guide/en/modules/authorizationmgr.xml
projects/security/security-docs/trunk/docs/guide/en/modules/mappingmgr.xml
projects/security/security-docs/trunk/docs/guide/en/modules/securityconfiguration.xml
projects/security/security-docs/trunk/docs/guide/en/modules/securitycontext.xml
Removed:
projects/security/security-docs/trunk/docs/guide/en/modules/howto.xml
projects/security/security-docs/trunk/docs/guide/en/modules/introduction.xml
projects/security/security-docs/trunk/docs/guide/en/modules/styles.xml
Modified:
projects/security/security-docs/trunk/docs/guide/en/master.xml
Log:
SECURITY-53: integration doc
Modified: projects/security/security-docs/trunk/docs/guide/en/master.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/master.xml 2007-05-16 22:22:13 UTC (rev 63107)
+++ projects/security/security-docs/trunk/docs/guide/en/master.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -1,56 +1,50 @@
-<?xml version='1.0' encoding="iso-8859-1"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
- "../../../support/docbook-dtd/docbookx.dtd"
-[
-<!ENTITY introduction SYSTEM "modules/introduction.xml">
-<!ENTITY howto SYSTEM "modules/howto.xml">
-<!ENTITY styles SYSTEM "modules/styles.xml">
-]>
-<book lang="en">
- <bookinfo>
- <title>How to use the JBoss DocBook system</title>
- <subtitle>A guide for content developers</subtitle>
- <releaseinfo>1.0</releaseinfo>
- </bookinfo>
-
- <toc/>
-
- <preface id="target" revision="1">
- <title>Target Audience</title>
- <para> All JBoss documentation content developers and style developers
- should read this document. You should also read this if you want to
- build JBoss DocBooks from the public CVS tree. </para>
- </preface>
-
- <preface id="preface" revision="1">
- <title>Preface</title>
- <para> This document introduces the new unified DocBook system for JBoss
- documentation in the public CVS tree. There are a couple of reasons
- why we did this. </para>
- <itemizedlist>
- <listitem> It provides a unified set of styles to make sure that all
- JBoss DocBooks have a consistent look and feel. </listitem>
- <listitem> The styles can be managed from a central location. We can
- design new styles or fix bugs without worrying about
- "deployment" issues. </listitem>
- <listitem> The libraries and build scripts can also be managed from
- a central location. </listitem>
- <listitem> The build process is simplified and standardized. Just
- follow the simple instructions in this guide to setup your docs
- directory and copy a very simple <literal>build.xml</literal>
- file. </listitem>
- <listitem> Last but not least, we can reduce the duplication of
- style sheets, XSLs and libraries in the system. </listitem>
- </itemizedlist>
-
- <para> If you have questions, please feel free to contact Michael Yuan
- or Norman Richards for more information. </para>
- </preface>
-
-&introduction;
-
-&howto;
-
-&styles;
-
-</book>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+"../../../support/docbook-dtd/docbookx.dtd" [
+<!ENTITY securitycontext SYSTEM "modules/securitycontext.xml">
+<!ENTITY authenticationmgr SYSTEM "modules/authenticationmgr.xml">
+<!ENTITY authorizationmgr SYSTEM "modules/authorizationmgr.xml">
+<!ENTITY mappingmgr SYSTEM "modules/mappingmgr.xml">
+<!ENTITY auditmgr SYSTEM "modules/auditmgr.xml">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>JBoss Security Integration Guide</title>
+
+ <subtitle>A guide for System Integrators</subtitle>
+
+ <releaseinfo>2.0</releaseinfo>
+ </bookinfo>
+
+ <toc></toc>
+
+ <preface id="target" revision="1">
+ <title>Target Audience</title>
+
+ <para>JEMS Projects as well as third party system integrators.</para>
+ </preface>
+
+ <preface id="preface" revision="1">
+ <title>Preface</title>
+
+ <para>This is an Integration Document that will be used by projects that
+ intend to integrate the JBoss Security SPI and the default
+ implementation.</para>
+
+ <para>If you have questions, please feel free to contact the JBoss
+ Security team.</para>
+
+ <para>Project Lead: Anil Saldhana <a
+ href="mailto:anil.saldhana at redhat.com"/></para>
+ </preface>
+
+ &securitycontext;
+
+ &authenticationmgr;
+
+ &authorizationmgr;
+
+ &mappingmgr;
+
+ &auditmgr;
+</book>
Added: projects/security/security-docs/trunk/docs/guide/en/modules/auditmgr.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/auditmgr.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/auditmgr.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="auditmgr">
+ <title>Audit Manager</title>
+
+ <para>The Audit Manager is an interface that is used to audit security
+ information to various sinks . The AuditManager interface is:</para>
+
+ <programlisting>package org.jboss.security.audit;
+
+/**
+ * An interface that defines the Security Audit Service
+ */
+public interface AuditManager
+{
+ /**
+ * Audit the information available in the audit event
+ * @param ae the Audit Event
+ * @see AuditEvent
+ */
+ public void audit(AuditEvent ae);
+}</programlisting>
+
+ <para>The AuditEvent is the container object for the audit information and
+ it looks as follows:</para>
+
+ <programlisting>package org.jboss.security.audit;
+
+/**
+ * Holder of audit information
+ */
+public class AuditEvent
+{
+ private String auditLevel = AuditLevel.INFO;
+
+ private Map<String,Object> contextMap = new HashMap<String,Object>();
+
+ private Exception underlyingException = null;
+
+ public AuditEvent(String level)
+ {
+ this.auditLevel = level;
+ }
+
+ public AuditEvent(String level, Map<String,Object> map)
+ {
+ this(level);
+ this.contextMap = map;
+ }
+
+ public AuditEvent(String level, Map<String,Object> map, Exception ex)
+ {
+ this(level,map);
+ this.underlyingException = ex;
+ }
+
+ /**
+ * Return the Audit Level
+ * @return
+ */
+ public String getAuditLevel()
+ {
+ return this.auditLevel;
+ }
+
+ /**
+ * Get the Contextual Map
+ * @return Map that is final
+ */
+ public Map getContextMap()
+ {
+ return contextMap;
+ }
+
+ /**
+ * Set a non-modifiable Context Map
+ * @param cmap Map that is final
+ */
+ public void setContextMap(final Map<String,Object> cmap)
+ {
+ this.contextMap = cmap;
+ }
+
+ /**
+ * Get the Exception part of the audit
+ * @return
+ */
+ public Exception getUnderlyingException()
+ {
+ return underlyingException;
+ }
+
+ /**
+ * Set the exception on which an audit is happening
+ * @param underlyingException
+ */
+ public void setUnderlyingException(Exception underlyingException)
+ {
+ this.underlyingException = underlyingException;
+ }
+
+ public String toString()
+ {
+ StringBuilder sbu = new StringBuilder();
+ sbu.append("[").append(auditLevel).append("]");
+ sbu.append(dissectContextMap());
+ return sbu.toString();
+ }
+}
+</programlisting>
+
+ <para>The AuditEvent contains a context map and an optional enclosing
+ exception. These should be set by the process that utilizes the auditing
+ framework. The AuditLevel defines the levels of severity.</para>
+
+ <programlisting>package org.jboss.security.audit;
+
+/**
+ * Define the Audit Levels of Severity
+ */
+public interface AuditLevel
+{
+ /** Denotes situations where there has been a server exception */
+ String ERROR = "Error";
+
+ /** Denotes situations when there has been a failed attempt */
+ String FAILURE = "Failure";
+
+ String SUCCESS = "Success";
+
+ /** Just some info being passed into the audit logs */
+ String INFO = "Info";
+}</programlisting>
+
+ <para>As mentioned earlier, the AuditContext is a set of AuditProviders. The
+ AuditProvider interface looks as follows:</para>
+
+ <programlisting>package org.jboss.security.audit;
+
+/**
+ * Audit Provider that can log audit events to an external
+ * sink
+ */
+public interface AuditProvider
+{
+ /**
+ * Perform an audit of the event passed
+ * A provider can log the audit as per needs.
+ * @param ae audit event that holds information on the audit
+ * @see AuditEvent
+ */
+ public void audit(AuditEvent ae);
+}</programlisting>
+</chapter>
\ No newline at end of file
Added: projects/security/security-docs/trunk/docs/guide/en/modules/authenticationmgr.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/authenticationmgr.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/authenticationmgr.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="authenticationmgr">
+ <title>Authentication Manager</title>
+
+ <para>AuthenticationManager is an interface that provides the authentication
+ aspects to a security consious subsystem. It is obtainable from the
+ SecurityContext.</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+import java.util.Map;
+import javax.security.auth.Subject;
+
+/** The AuthenticationManager is responsible for validating credentials
+ * associated with principals.
+ */
+public interface AuthenticationManager
+{
+ /** Get the security domain from which the security manager is from. Every
+ security manager belongs to a named domain. The meaning of the security
+ domain name depends on the implementation. Examples range from as fine
+ grained as the name of EJBs to J2EE application names to DNS domain names.
+ @return the security domain name. May be null in which case the security
+ manager belongs to the logical default domain.
+ */
+ String getSecurityDomain();
+
+ /** The isValid method is invoked to see if a user identity and associated
+ credentials as known in the operational environment are valid proof of the
+ user identity. Typically this is implemented as a call to isValid with a
+ null Subject.
+
+ @see #isValid(Principal, Object, Subject)
+
+ @param principal - the user identity in the operation environment
+ @param credential - the proof of user identity as known in the
+ operation environment
+ @return true if the principal, credential pair is valid, false otherwise.
+ */
+ public boolean isValid(Principal principal, Object credential);
+
+ /** The isValid method is invoked to see if a user identity and associated
+ credentials as known in the operational environment are valid proof of the
+ user identity. This extends AuthenticationManager version to provide a
+ copy of the resulting authenticated Subject. This allows a caller to
+ authenticate a user and obtain a Subject whose state cannot be modified
+ by other threads associated with the same principal.
+ @param principal - the user identity in the operation environment
+ @param credential - the proof of user identity as known in the
+ operation environment
+ @param activeSubject - the Subject which should be populated with the
+ validated Subject contents. A JAAS based implementation would typically
+ populate the activeSubject with the LoginContext.login result.
+ @return true if the principal, credential pair is valid, false otherwise.
+ */
+ boolean isValid(Principal principal, Object credential,
+ Subject activeSubject);
+
+ /** Get the currently authenticated subject. Historically implementations of
+ AuthenticationManager isValid methods had the side-effect of setting the
+ active Subject. This caused problems with multi-threaded usecases where the
+ Subject instance was being shared by multiple threads. This is now deprecated
+ in favor of the JACC PolicyContextHandler getContext(key, data) method.
+
+ @deprecated Use the JACC PolicyContextHandler using key "javax.security.auth.Subject.container"
+ @see javax.security.jacc.PolicyContextHandler#getContext(String, Object)
+
+ @return The previously authenticated Subject if isValid succeeded, null if
+ isValid failed or has not been called for the active thread.
+ */
+ Subject getActiveSubject();
+
+ /**
+ * Trust related usecases may require translation of a principal from another domain
+ * to the current domain
+ * An implementation of this interface may need to do a backdoor contact of the external
+ * trust provider in deriving the target principal
+ * @param anotherDomainPrincipal Principal that is applicable in the other domain
+ * (Can be null - in which case the contextMap is used
+ * solely to derive the target principal)
+ * @param contextMap Any context information (including information on the other domain
+ * that may be relevant in deriving the target principal). Any SAML
+ * assertions that may be relevant can be passed here.
+ * @return principal from a target security domain
+ */
+ Principal getTargetPrincipal(Principal anotherDomainPrincipal, Map<String,Object> contextMap);
+}</programlisting>
+
+ <para>The getActiveSubject is a deprecated api to determine the
+ subject.</para>
+</chapter>
\ No newline at end of file
Added: projects/security/security-docs/trunk/docs/guide/en/modules/authorizationmgr.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/authorizationmgr.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/authorizationmgr.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="authorizationmgr">
+ <title>Authorization Manager</title>
+
+ <para>AuthorizationManager is an interface that provides fine-grained
+ authorization aspects to a security consious subsystem. It is obtainable
+ from the SecurityContext.</para>
+
+ <programlisting> package org.jboss.security;
+
+import java.security.Principal;
+import java.security.acl.Group;
+import java.util.Map;
+import java.util.Set;
+
+import org.jboss.security.authorization.AuthorizationException;
+import org.jboss.security.authorization.Resource;
+/**
+ * Generalized Authorization Manager Interface.
+ */
+public interface AuthorizationManager
+{
+ /**
+ * Authorize a resource
+ * @param resource
+ * @return
+ * @throws AuthorizationException
+ */
+ public int authorize(Resource resource) throws AuthorizationException;
+
+
+ /** Validates the application domain roles to which the operational
+ environment Principal belongs.
+ @param principal the caller principal as known in the operation environment.
+ @param roles The Set<Principal> for the application domain roles that the
+ principal is to be validated against.
+ @return true if the principal has at least one of the roles in the roles set,
+ false otherwise.
+ */
+ public boolean doesUserHaveRole(Principal principal, Set roles);
+
+
+ /** Return the set of domain roles the principal has been assigned.
+ @return The Set<Principal> for the application domain roles that the
+ principal has been assigned.
+ */
+ public Set getUserRoles(Principal principal);
+
+ /**
+ * Trust usecases may have a need to determine the roles of the target
+ * principal which has been derived via a principal from another domain
+ * by the Authentication Manager
+ * An implementation of this interface may have to contact a trust provider
+ * for additional information about the principal
+ * @param targetPrincipal Principal applicable in current domain
+ * @param contextMap Read-Only Contextual Information that may be useful for the
+ * implementation in determining the roles.
+ * @return roles from the target domain
+ */
+ public Group getTargetRoles(Principal targetPrincipal, Map contextMap);
+ }</programlisting>
+
+ <para>The Resource interface looks as follows:</para>
+
+ <programlisting>package org.jboss.security.authorization;
+
+import java.util.Map;
+
+/**
+ * Resource that is subject to Authorization Decisions
+ */
+public interface Resource
+{
+ //Get the Layer (Web/EJB etc)
+ public ResourceType getLayer();
+
+ //Return the contextual map
+ public Map getMap();
+}</programlisting>
+</chapter>
\ No newline at end of file
Deleted: projects/security/security-docs/trunk/docs/guide/en/modules/howto.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/howto.xml 2007-05-16 22:22:13 UTC (rev 63107)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/howto.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -1,89 +0,0 @@
-<chapter id="howto">
- <title>How to develop content for JBoss DocBook</title>
- <section>
- <title>Setup the directories</title>
- <para> Each top-level JBoss project (<literal>projectname/</literal>) in
- the public CVS stores its documentations in the
- <literal>projectname/docs</literal> directory. The
- <literal>projectname/docs</literal> directory can contain any number
- of subdirectories for API references, sample code, user guide etc.
- But each DocBook should be placed in its own directory directly
- under <literal>projectname/docs</literal>. For example, the user's
- guide DocBook for a project could be placed in
- <literal>projectname/docs/userguide</literal>. The easiest way to
- setup this DocBook directory is to copy the
- <literal>docbook-support/docs/guide</literal> directory to your
- target project and use it as a template. The
- <literal>userguide</literal> DocBook structure for the JBoss AOP
- project is shown in <xref linkend="aop.fig"/>. </para>
- <figure id="aop.fig">
- <title>The user guide DocBook in the AOP project </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/aop.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para> Inside the DocBook directory, there are typically several
- sub-directories, each corresponding to a specific lanuguage version
- of the document. The English version resides in the
- <literal>en/</literal> sub-directory. Inside each language
- directory, there are typically two sub-directories for contents:</para>
- <itemizedlist>
- <listitem> The <literal>images/</literal> directory stores images. </listitem>
- <listitem> The <literal>modules/</literal> directory stores DocBook
- text modules for each chapter. </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Author the content</title>
- <para> Now you can write your content in DocBook format. Make sure that
- the master file of your DocBook (i.e., the file that contains the
- <literal>book</literal> element) in the
- <literal>master.xml</literal> file directly under the language
- directory (see <xref linkend="aop.fig"/>). You can either put the
- entire content in <literal>master.xml</literal> or divide up the
- chapters and place them in the <literal>modules/</literal>
- directory. If you do the latter, you should reference the chapter
- files from the <literal>master.xml</literal> file via entity
- reference. Please see the
- <literal>docbook-support/docs/guide/en/master.xml</literal> file to
- see how it is done. </para>
- </section>
- <section>
- <title> Build the documents </title>
- <para> To build the deliverable documents, just run ANT against the
- <literal>build.xml</literal> file in the DocBook directory. The
- <literal>build.xml</literal> file is really simple and its content
- is shown below. It delegates most of the tasks to the
- <literal>support.xml</literal> file mainatined by the
- <literal>docbook-support</literal> project. </para>
- <programlisting>
-<project name="Documentation" default="all.doc" basedir=".">
-
- <property name="pdf.name" value="jboss-mybook.pdf" />
- <import file="../../../docbook-support/support.xml" />
-
- <target name="all.doc" depends="clean">
- <antcall target="lang.all">
- <param name="lang" value="en"/>
- </antcall>
- </target>
-
-</project>
- </programlisting>
- <para> After the build is finished, you have three output documents for
- each language edition in the following places:</para>
- <itemizedlist>
- <listitem> The <literal>build/en/html</literal> directory contains
- the HTML version of the document. Each chapter is broken into a
- separate HTML file and they are linked by the
- <literal>index.html</literal> file.</listitem>
- <listitem> The <literal>build/en/html_signle</literal> directory
- contains a big <literal>index.html</literal> file which holds
- the entire document. </listitem>
- <listitem> The <literal>build/en/pdf</literal> directory contains
- the PDF version of the document. </listitem>
- </itemizedlist>
- </section>
-</chapter>
Deleted: projects/security/security-docs/trunk/docs/guide/en/modules/introduction.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/introduction.xml 2007-05-16 22:22:13 UTC (rev 63107)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/introduction.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -1,25 +0,0 @@
-<chapter id="introduction">
- <title>Introduction to DocBook proceessing</title>
- <para> DocBook is an XML format to write documents. It allows the author to
- focus on the content itself during the writing process instead of
- worrying about the presentation. </para>
- <para> Using the standard DocBook tags, we can tag the content according to
- their syntax structure. The DocBook document is then processed against
- XSL style sheets. Each tagged element in the DocBook is transformed to a
- presentation element with the style (e.g., margin, font etc.) specified
- in the XSL. Using different XSL stylesheets, we can generate different
- output documents. For example, we can generate HTML and PDF outputs from
- a single DocBook source. We can also generate multiple versions of PDF
- (or HTML) files each with a different formatting style. </para>
- <para> In the JBoss DocBook system, we provide XSL stylesheets to build HTML
- and PDF outputs from the DocBook source. The build process is
- illustrated in <xref linkend="build.fig"/>. </para>
- <figure id="build.fig">
- <title>The DocBook build process </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/build.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-</chapter>
Added: projects/security/security-docs/trunk/docs/guide/en/modules/mappingmgr.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/mappingmgr.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/mappingmgr.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="mappingmgr">
+ <title>Mapping Manager</title>
+
+ <para>The Mapping Manager is an interface that is used to obtain a
+ preconfigured MappingContext for a particular mapping type. An example of a
+ Mapping Class type would be java.security.acl.Group for role mapping.
+ Implementations of the SPI are free to define their own mapping class types.
+ The MappingManager interface is:</para>
+
+ <programlisting> package org.jboss.security.mapping;
+
+/**
+ * Manager that is used for mapping various types
+ */
+public interface MappingManager
+{
+ MappingContext getMappingContext(Class mappingType);
+}</programlisting>
+
+ <para>The MappingContext is just a set of preconfigured MappingProvider
+ instances for a particular class type and a security domain. The
+ MappingContext class looks as:</para>
+
+ <programlisting>package org.jboss.security.mapping;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Generic Context used by the Mapping Framework
+ */
+public class MappingContext
+{
+ private List modules = new ArrayList();
+
+ public MappingContext(List mod)
+ {
+ this.modules = mod;
+ }
+
+ /**
+ * Get the set of mapping modules
+ * @return
+ */
+ public List getModules()
+ {
+ return this.modules;
+ }
+
+ /**
+ * Apply mapping semantics on the passed object
+ * @param obj Read-only Contextual Map
+ * @param mappedObject an object on which mapping will be applied
+ */
+ public <T> void performMapping(Map obj, T mappedObject)
+ {
+ int len = modules.size();
+
+ for(int i = 0 ; i < len; i++)
+ {
+ MappingProvider<T> mp = (MappingProvider<T>)modules.get(i);
+ mp.performMapping(obj, mappedObject);
+ }
+ }
+}
+</programlisting>
+
+ <para>The MappingProvider interface is as follows:</para>
+
+ <programlisting>package org.jboss.security.mapping;
+
+import java.util.Map;
+
+/**
+ * A provider with mapping functionality
+ */
+public interface MappingProvider<T>
+{
+ /**
+ * Initialize the provider with the configured module options
+ * @param options
+ */
+ void init(Map options);
+
+ /**
+ * Map the passed object
+ * @param map A read-only contextual map that can provide information to the provider
+ * @param mappedObject an Object on which the mapping will be applied
+ * @throws IllegalArgumentException if the mappedObject is not understood by the
+ * provider.
+ */
+ void performMapping(Map map, T mappedObject);
+}</programlisting>
+</chapter>
\ No newline at end of file
Added: projects/security/security-docs/trunk/docs/guide/en/modules/securityconfiguration.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/securityconfiguration.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/securityconfiguration.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,315 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="securitycontext">
+ <title>Security Context</title>
+
+ <para>SecurityContext is an encapsulation of the Authentication,
+ Authorization, Mapping and Auditing aspects of a security conscious system.
+ The interface looks as follows:</para>
+
+ <programlisting>package org.jboss.security;
+
+/**
+ * Encapsulation of Authentication, Authorization, Mapping and other
+ * security aspects at the level of a security domain
+ * @author <a href="mailto:Anil.Saldhana at jboss.org">Anil Saldhana</a>
+ */
+public interface SecurityContext extends Serializable,Cloneable
+{
+ /**
+ * Authentication Manager for the security domain
+ */
+ public AuthenticationManager getAuthenticationManager();
+ /**
+ * Authorization Manager for the security domain
+ */
+ public AuthorizationManager getAuthorizationManager();
+
+ /**
+ * Mapping manager configured with providers
+ */
+ public MappingManager getMappingManager();
+
+ /**
+ * AuditManager configured for the security domain
+ */
+ public AuditManager getAuditManager();
+
+ /**
+ * Context Map
+ */
+ public Map<String,Object> getData();
+
+ /**
+ * Return the Security Domain
+ */
+ public String getSecurityDomain();
+
+ /**
+ * Subject Info
+ *
+ * @see SecurityContextUtil#getSubject()
+ * @see SecurityContextUtil#createSubjectInfo(Principal, Object, Subject)
+ */
+ SubjectInfo getSubjectInfo();
+
+ /**
+ * Subject Info
+ *
+ * @see SecurityContextUtil#getSubject()
+ * @see SecurityContextUtil#createSubjectInfo(Principal, Object, Subject)
+ */
+ void setSubjectInfo(SubjectInfo si);
+
+ /**
+ * RunAs Representation
+ *
+ * @see #setRunAs(RunAs)
+ */
+ public RunAs getRunAs();
+
+ /**
+ * Set the current RunAs for the security context that will be
+ * propagated out to other security context.
+ *
+ * RunAs coming into this security context needs to be done
+ * from SecurityContextUtil.getCallerRunAs/setCallerRunAs
+ *
+ * @see SecurityContextUtil#getCallerRunAs()
+ * @see SecurityContextUtil#setCallerRunAs(RunAs)
+ *
+ * @param runAs
+ */
+ public void setRunAs(RunAs runAs);
+
+ /**
+ * Return a utility that is a facade to the internal
+ * storage mechanism of the Security Context
+ *
+ * This utility can be used to store information like
+ * roles etc in an implementation specific way
+ * @return
+ */
+ public SecurityContextUtil getUtil();
+}</programlisting>
+
+ <para>Associated with the SecurityContext is the notion of a SecurityUtil
+ that can provide some utility methods to shield from the implementation
+ details of any vendor implementation of the SecurityContext. The
+ SecurityUtil abstract class looks as follows:</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+
+import javax.security.auth.Subject;
+
+/**
+ * General Utility methods for dealing with the SecurityContext
+ */
+public abstract class SecurityContextUtil
+{
+ protected SecurityContext securityContext = null;
+
+ public void setSecurityContext(SecurityContext sc)
+ {
+ this.securityContext = sc;
+ }
+
+ /**
+ * Get the username from the security context
+ * @return username
+ */
+ public abstract String getUserName();
+
+ /**
+ * Get the user principal the security context
+ * @return user principal
+ */
+ public abstract Principal getUserPrincipal();
+
+ /**
+ * Get the credential
+ * @return
+ */
+ public abstract Object getCredential();
+
+ /**
+ * Get the subject the security context
+ * @return
+ */
+ public abstract Subject getSubject();
+
+ /**
+ * Get the RunAs that was passed into the current security context
+ * The security context RunAs is the RunAs that will be propagated out of it
+ * @return
+ */
+ public abstract RunAs getCallerRunAs();
+
+ /**
+ * Set the Caller RunAs in the security context
+ * Security Context implementations are free to store
+ * the caller runas in any manner
+ * @param runAs
+ */
+ public abstract void setCallerRunAs(RunAs runAs);
+
+ /**
+ * Get a holder of subject, runAs and caller RunAs
+ * @return
+ */
+ public abstract SecurityIdentity getSecurityIdentity();
+
+ /**
+ * Inject subject, runAs and callerRunAs into the security context
+ * Mainly used by integration code base to cache the security identity
+ * and put back to the security context
+ * @param si The SecurityIdentity Object
+ */
+ public abstract void setSecurityIdentity(SecurityIdentity si);
+
+ /**
+ * Get the Roles associated with the user for the
+ * current security context
+ * @param <T>
+ * @return
+ */
+ public abstract <T> T getRoles();
+
+ /**
+ * Set the roles for the user for the current security context
+ * @param <T>
+ * @param roles
+ */
+ public abstract <T> void setRoles(T roles);
+
+ /**
+ * Create SubjectInfo and set it in the current security context
+ * @param principal
+ * @param credential
+ * @param subject
+ */
+ public void createSubjectInfo(Principal principal, Object credential,Subject subject)
+ {
+ SubjectInfo si = new SubjectInfo(principal, credential, subject);
+ this.securityContext.setSubjectInfo(si);
+ }
+
+ /**
+ * Set an object on the Security Context
+ * The context implementation may place the object in its internal
+ * data structures (like the Data Map)
+ * @param <T> Generic Type
+ * @param sc Security Context Object
+ * @param key Key representing the object being set
+ * @param obj
+ */
+ public abstract <T> void set(String key, T obj);
+
+ /**
+ * Return an object from the Security Context
+ * @param <T>
+ * @param sc Security Context Object
+ * @param key key identifies the type of object we are requesting
+ * @return
+ */
+ public abstract <T> T get(String key);
+
+ /**
+ * Remove an object represented by the key from the security context
+ * @param <T>
+ * @param sc Security Context Object
+ * @param key key identifies the type of object we are requesting
+ * @return the removed object
+ */
+ public abstract <T> T remove(String key);
+}
+</programlisting>
+
+ <para>As seen in the abstract class, the SecurityContextUtil provides
+ methods to deal with the user principal and credential, RunAs and general
+ usage of the SecurityContext as a store of objects via key pair (Refer to
+ the set, get and remove methods).</para>
+
+ <para>The SecurityContextUtil has the usage of a SecurityIdentity aspect.
+ The SecurityIdentity reprents the identity of the agent that is interfacing
+ with the security system. It contains the subject and various run-as (RunAs
+ and CallerRunAs).</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+import javax.security.auth.Subject;
+
+//$Id$
+
+/**
+ * Represents an Identity of an agent interacting with the
+ * security service. It can be an user or a process. It
+ * consists of a subject and various run-as
+ */
+public class SecurityIdentity
+{
+ SubjectInfo theSubject = null;
+ RunAs runAs = null;
+ RunAs callerRunAs = null;
+
+ public SecurityIdentity(SubjectInfo subject, RunAs runAs, RunAs callerRunAs)
+ {
+ this.theSubject = subject;
+ this.runAs = runAs;
+ this.callerRunAs = callerRunAs;
+ }
+
+ public Principal getPrincipal()
+ {
+ return theSubject != null ? theSubject.getAuthenticationPrincipal() : null;
+ }
+
+ public Object getCredential()
+ {
+ return theSubject != null ? theSubject.getAuthenticationCredential(): null;
+ }
+
+ public Subject getSubject()
+ {
+ return theSubject != null ? theSubject.getAuthenticatedSubject() : null;
+ }
+
+ public RunAs getRunAs()
+ {
+ return runAs;
+ }
+
+ public RunAs getCallerRunAs()
+ {
+ return callerRunAs;
+ }
+}</programlisting>
+
+ <para>The difference between RunAs and CallerRunAs is: The RunAs represents
+ the RunAs that is outgoing from the current context. The caller RunAs
+ represents the RunAs that enters this security context. The RunAs interface
+ is:</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+/**
+ * Represent an entity X with a proof of identity Y
+ */
+public interface RunAs extends Principal
+{
+ /**
+ * Return the identity represented
+ * @return
+ */
+ public <T> T getIdentity();
+
+ /**
+ * Return the proof of identity
+ * @return
+ */
+ public <T> T getProof();
+}</programlisting>
+</chapter>
\ No newline at end of file
Added: projects/security/security-docs/trunk/docs/guide/en/modules/securitycontext.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/securitycontext.xml (rev 0)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/securitycontext.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -0,0 +1,315 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="securitycontext">
+ <title>Security Context</title>
+
+ <para>SecurityContext is an encapsulation of the Authentication,
+ Authorization, Mapping and Auditing aspects of a security conscious system.
+ The interface looks as follows:</para>
+
+ <programlisting>package org.jboss.security;
+
+/**
+ * Encapsulation of Authentication, Authorization, Mapping and other
+ * security aspects at the level of a security domain
+ * @author <a href="mailto:Anil.Saldhana at jboss.org">Anil Saldhana</a>
+ */
+public interface SecurityContext extends Serializable,Cloneable
+{
+ /**
+ * Authentication Manager for the security domain
+ */
+ public AuthenticationManager getAuthenticationManager();
+ /**
+ * Authorization Manager for the security domain
+ */
+ public AuthorizationManager getAuthorizationManager();
+
+ /**
+ * Mapping manager configured with providers
+ */
+ public MappingManager getMappingManager();
+
+ /**
+ * AuditManager configured for the security domain
+ */
+ public AuditManager getAuditManager();
+
+ /**
+ * Context Map
+ */
+ public Map<String,Object> getData();
+
+ /**
+ * Return the Security Domain
+ */
+ public String getSecurityDomain();
+
+ /**
+ * Subject Info
+ *
+ * @see SecurityContextUtil#getSubject()
+ * @see SecurityContextUtil#createSubjectInfo(Principal, Object, Subject)
+ */
+ SubjectInfo getSubjectInfo();
+
+ /**
+ * Subject Info
+ *
+ * @see SecurityContextUtil#getSubject()
+ * @see SecurityContextUtil#createSubjectInfo(Principal, Object, Subject)
+ */
+ void setSubjectInfo(SubjectInfo si);
+
+ /**
+ * RunAs Representation
+ *
+ * @see #setRunAs(RunAs)
+ */
+ public RunAs getRunAs();
+
+ /**
+ * Set the current RunAs for the security context that will be
+ * propagated out to other security context.
+ *
+ * RunAs coming into this security context needs to be done
+ * from SecurityContextUtil.getCallerRunAs/setCallerRunAs
+ *
+ * @see SecurityContextUtil#getCallerRunAs()
+ * @see SecurityContextUtil#setCallerRunAs(RunAs)
+ *
+ * @param runAs
+ */
+ public void setRunAs(RunAs runAs);
+
+ /**
+ * Return a utility that is a facade to the internal
+ * storage mechanism of the Security Context
+ *
+ * This utility can be used to store information like
+ * roles etc in an implementation specific way
+ * @return
+ */
+ public SecurityContextUtil getUtil();
+}</programlisting>
+
+ <para>Associated with the SecurityContext is the notion of a SecurityUtil
+ that can provide some utility methods to shield from the implementation
+ details of any vendor implementation of the SecurityContext. The
+ SecurityUtil abstract class looks as follows:</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+
+import javax.security.auth.Subject;
+
+/**
+ * General Utility methods for dealing with the SecurityContext
+ */
+public abstract class SecurityContextUtil
+{
+ protected SecurityContext securityContext = null;
+
+ public void setSecurityContext(SecurityContext sc)
+ {
+ this.securityContext = sc;
+ }
+
+ /**
+ * Get the username from the security context
+ * @return username
+ */
+ public abstract String getUserName();
+
+ /**
+ * Get the user principal the security context
+ * @return user principal
+ */
+ public abstract Principal getUserPrincipal();
+
+ /**
+ * Get the credential
+ * @return
+ */
+ public abstract Object getCredential();
+
+ /**
+ * Get the subject the security context
+ * @return
+ */
+ public abstract Subject getSubject();
+
+ /**
+ * Get the RunAs that was passed into the current security context
+ * The security context RunAs is the RunAs that will be propagated out of it
+ * @return
+ */
+ public abstract RunAs getCallerRunAs();
+
+ /**
+ * Set the Caller RunAs in the security context
+ * Security Context implementations are free to store
+ * the caller runas in any manner
+ * @param runAs
+ */
+ public abstract void setCallerRunAs(RunAs runAs);
+
+ /**
+ * Get a holder of subject, runAs and caller RunAs
+ * @return
+ */
+ public abstract SecurityIdentity getSecurityIdentity();
+
+ /**
+ * Inject subject, runAs and callerRunAs into the security context
+ * Mainly used by integration code base to cache the security identity
+ * and put back to the security context
+ * @param si The SecurityIdentity Object
+ */
+ public abstract void setSecurityIdentity(SecurityIdentity si);
+
+ /**
+ * Get the Roles associated with the user for the
+ * current security context
+ * @param <T>
+ * @return
+ */
+ public abstract <T> T getRoles();
+
+ /**
+ * Set the roles for the user for the current security context
+ * @param <T>
+ * @param roles
+ */
+ public abstract <T> void setRoles(T roles);
+
+ /**
+ * Create SubjectInfo and set it in the current security context
+ * @param principal
+ * @param credential
+ * @param subject
+ */
+ public void createSubjectInfo(Principal principal, Object credential,Subject subject)
+ {
+ SubjectInfo si = new SubjectInfo(principal, credential, subject);
+ this.securityContext.setSubjectInfo(si);
+ }
+
+ /**
+ * Set an object on the Security Context
+ * The context implementation may place the object in its internal
+ * data structures (like the Data Map)
+ * @param <T> Generic Type
+ * @param sc Security Context Object
+ * @param key Key representing the object being set
+ * @param obj
+ */
+ public abstract <T> void set(String key, T obj);
+
+ /**
+ * Return an object from the Security Context
+ * @param <T>
+ * @param sc Security Context Object
+ * @param key key identifies the type of object we are requesting
+ * @return
+ */
+ public abstract <T> T get(String key);
+
+ /**
+ * Remove an object represented by the key from the security context
+ * @param <T>
+ * @param sc Security Context Object
+ * @param key key identifies the type of object we are requesting
+ * @return the removed object
+ */
+ public abstract <T> T remove(String key);
+}
+</programlisting>
+
+ <para>As seen in the abstract class, the SecurityContextUtil provides
+ methods to deal with the user principal and credential, RunAs and general
+ usage of the SecurityContext as a store of objects via key pair (Refer to
+ the set, get and remove methods).</para>
+
+ <para>The SecurityContextUtil has the usage of a SecurityIdentity aspect.
+ The SecurityIdentity reprents the identity of the agent that is interfacing
+ with the security system. It contains the subject and various run-as (RunAs
+ and CallerRunAs).</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+import javax.security.auth.Subject;
+
+//$Id$
+
+/**
+ * Represents an Identity of an agent interacting with the
+ * security service. It can be an user or a process. It
+ * consists of a subject and various run-as
+ */
+public class SecurityIdentity
+{
+ SubjectInfo theSubject = null;
+ RunAs runAs = null;
+ RunAs callerRunAs = null;
+
+ public SecurityIdentity(SubjectInfo subject, RunAs runAs, RunAs callerRunAs)
+ {
+ this.theSubject = subject;
+ this.runAs = runAs;
+ this.callerRunAs = callerRunAs;
+ }
+
+ public Principal getPrincipal()
+ {
+ return theSubject != null ? theSubject.getAuthenticationPrincipal() : null;
+ }
+
+ public Object getCredential()
+ {
+ return theSubject != null ? theSubject.getAuthenticationCredential(): null;
+ }
+
+ public Subject getSubject()
+ {
+ return theSubject != null ? theSubject.getAuthenticatedSubject() : null;
+ }
+
+ public RunAs getRunAs()
+ {
+ return runAs;
+ }
+
+ public RunAs getCallerRunAs()
+ {
+ return callerRunAs;
+ }
+}</programlisting>
+
+ <para>The difference between RunAs and CallerRunAs is: The RunAs represents
+ the RunAs that is outgoing from the current context. The caller RunAs
+ represents the RunAs that enters this security context. The RunAs interface
+ is:</para>
+
+ <programlisting>package org.jboss.security;
+
+import java.security.Principal;
+/**
+ * Represent an entity X with a proof of identity Y
+ */
+public interface RunAs extends Principal
+{
+ /**
+ * Return the identity represented
+ * @return
+ */
+ public <T> T getIdentity();
+
+ /**
+ * Return the proof of identity
+ * @return
+ */
+ public <T> T getProof();
+}</programlisting>
+</chapter>
\ No newline at end of file
Deleted: projects/security/security-docs/trunk/docs/guide/en/modules/styles.xml
===================================================================
--- projects/security/security-docs/trunk/docs/guide/en/modules/styles.xml 2007-05-16 22:22:13 UTC (rev 63107)
+++ projects/security/security-docs/trunk/docs/guide/en/modules/styles.xml 2007-05-17 03:04:57 UTC (rev 63108)
@@ -1,27 +0,0 @@
-<chapter id="styles">
- <title>Maintain the JBoss DocBook system</title>
- <para> The structure of the <literal>docbook-support</literal> module is
- illustrated in <xref linkend="docbook.fig"/>. The contents are as follows. </para>
- <figure id="docbook.fig">
- <title>The docbook-support module </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/docbook.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <itemizedlist>
- <listitem> The <literal>support</literal> directory contains Java
- libraries and executables for XML processors. It also contains
- standard DocBook XSL stylesheets. This is the place for "system" software.</listitem>
- <listitem> The <literal>styles</literal> directory contains DocBook
- styles we developed in-house for JBoss. Each language would have a
- separate set of styles.</listitem>
- <listitem> The <literal>docs</literal> directory contains this guide to
- serve as a template for other projects. </listitem>
- <listitem> The <literal>support.xml</literal> file contains all the
- necessary ANT tasks to build DocBooks. It is referenced from the
- <literal>build.xml</literal> file for each individual DocBook
- project. </listitem>
- </itemizedlist>
-</chapter>
More information about the jboss-cvs-commits
mailing list