<?xml version="1.0"?>
<!--<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">-->

<book xmlns:ci="http://apache.org/cocoon/include/1.0">

	<bookinfo>
		<graphic fileref="logo.jpg"/>
		<productname>Open Source Native XML Database</productname>
		<title>XACML Access Control in eXist: Capabilities</title>
		<author>
			<firstname>Mark</firstname>
			<surname>Harrah</surname>
			<affiliation>
				<address format="linespecific">
					<email>harrah@umd.edu</email>
				</address>
			</affiliation>
		</author>
	</bookinfo>

	<ci:include src="sidebar.xml"/>

	<chapter>
		<title>Access Control in eXist: Capabilities</title>
		<para>
			In XACML, access to resources (such as an XQuery or a Java method) can be
			controlled by characteristics of the subject(s) accessing the resource (a common
			subject is a user executing a query), the resource being accessed, the action
			being taken on the resource (such as 'execute query'), or the environment in
			which the access is being made (such as the time of the access).  This part of
			the documentation provides an overview of what subjects, resources, and
			actions are available and what characteristics of those entities may
			be use to control access.
		</para>

		<section>
			<title>Subjects</title>
			<section>
				<title>User</title>
				<para>
					All types of access may be restricted by the user initiating access to a
					resource, currently XQueries.  The user's name and the names of the groups
					of which the user is a member may be used to control access to any of the
					supported resources mentioned in the Resources section.
				</para>
			</section>
			<section>
				<title>Intermediaries</title>
				<para>
					There is no support yet for access control based on the route taken to the
					resource.  This type of control would allow, for example, a user to use a
					library module library.xqm by running query.xql but not through a query
					passed directly in the HTTP request.
				</para>
			</section>
		</section>
		<section>
			<title>Resources</title>
			<para>
				All XQuery modules may be controlled by their source.  A
				source has a type (Cocoon, URL, Class, File, Database, String, or
				ClassLoader resource) and a key.  The key is specific to the source.  For
				URLs, ClassLoader resources, and Cocoon, the key is the URI or URL of the
				source.
			</para>
			<para>
				Access may also be controlled based on the method of access.  The following
				are direct access contexts: REST, XML:DB (local), XML-RPC, WebDAV, and SOAP.
				Additionally, some contexts are indirectly used: eXist internally executes
				queries for validation, triggers may execute queries, and XInclude expansion
				requries evaluation of a query.  There is also a context for unit tests
				when they directly access the query classes without going through one
				of the above interfaces.
			</para>
			<itemizedlist>
				<listitem>
					<para>
						A String source comes from directly passed queries.  This may occur
						externally through the REST-style interface or XML:DB or eXist may
						internally execute queries directly. The key is "String" for every
						String source.  This source is only used for main modules.
					</para>
				</listitem>
				<listitem>
					<para>
						A source of type File comes directly from the filesystem.  The key is the
						absolute path to the file.  External library modules or main modules may
						have this source type.
					</para>
				</listitem>
				<listitem>
					<para>
						A source of type Database is stored in the database.  The key is the absolute
						path to the resource (such as /db/test/test.xqm).  External library modules or
						main modules may have this source type.
					</para>
				</listitem>
				<listitem>
					<para>
						Cocoon sources are sources requested from a Cocoon context.  The key is the
						URI to the resource.  Main modules may have this source type.
					</para>
				</listitem>
				<listitem>
					<para>
						Class sources are sources that are Java classes.  The key is the fully
						qualified name of the class.  These will always be the type of internal
						library modules and reflective access to Java methods.
					</para>
				</listitem>
				<listitem>
					<para>
						URL sources have as the key the URL.  External library modules or main modules
						may have this source type.
					</para>
				</listitem>
				<listitem>
					<para>
						Class loader sources are those resources found by the class loader.  The key is
						the path to the resource.  External library modules or main modules may have this
						source type.
					</para>
				</listitem>
			</itemizedlist>
			<section>
				<title>Java Reflection</title>
				<para>
					Invocation of Java methods by reflection may be restricted by class and
					method name.
				</para>
			</section>
			<section>
				<title>Internal XQuery Library Modules</title>
				<para>
					Calls to XQuery functions in modules written in Java may be restricted
					by the name of the implementing module's class, the module's namespace URI,
					and the name of the function.
				</para>
			</section>
			<section>
				<title>External XQuery Library Modules</title>
				<para>
					Calls to XQuery functions in library modules stored in the
					database or the file system may be restricted by namespace URI, function name,
					and module source.
				</para>
			</section>
			<section>
				<title>XQuery Main Modules</title>
				<para>
					Query execution may be controlled by the source of the query.
				</para>
			</section>
			<note>
				<para>Overloaded Java methods and XQuery functions share the same access
				control settings.
				</para>
			</note>
		</section>
		<section>
			<title>Actions</title>
			<para>
				There is currently one action for each type of resource.  The 'execute query'
				action corresponds to the XQuery main module resource, the 'call function' action
				corresponds to the XQuery library module resource (both internal and external),
				and the 'invoke method' action corresponds to the Java method resource.
			</para>
		</section>
		<section>
			<title>Environment</title>
			<para>
				The characteristics of the environment that are present are the current date
				and time.
			</para>
		</section>
		<section>
			<title>What is not controlled</title>
			<para>
				You cannot control access to documents, HTTP put or get requests, which
				XML-RPC methods may be invoked, or anything else not explicitly mentioned
				above.  Additionally, there is currently no supported method of using eXist's
				XACML-related classes for access control in your own application.
			</para>
		</section>
	</chapter>
</book>
