## org.exist.security.xacml
Class RequestHelper

    java.lang.Object
      org.exist.security.xacml.RequestHelper

public class RequestHelper
extends java.lang.Object

This class provides methods for creating an XACML request. The main methods are those that return a `RequestCtx`. Links are provided to the relevant constants in `XACMLConstants` to facilitate policy writing.

See Also:
  `XACMLConstants`

Method Summary
`static void` `addSourceAttributes(java.util.Set attributes, XACMLSource source)` Adds new attributes to the specified `Set` of attributes that represent the specified source.
`static void` `addStringAttribute(java.util.Set attributes, java.net.URI attrID, java.lang.String attrValue)` Adds a new attribute of type string to the specified `Set` of attributes.
`static void` `addURIAttribute(java.util.Set attributes, java.net.URI attrID, java.lang.String uriString)` Adds a new attribute of type anyURI to the specified `Set` of attributes.
`java.util.Set` `createBasicAction(java.lang.String action)` Creates the basic attributes needed to describe a simple action in a request.
`java.util.Set` `createEnvironment(AccessContext accessCtx)` Creates the environment section of a request for the given `AccessContext`.
`com.sun.xacml.ctx.RequestCtx` `createFunctionRequest(XQueryContext context, Module contextModule, QName functionName)` Creates a `RequestCtx` for a request concerning access to a function in an XQuery library module.
`com.sun.xacml.ctx.Subject` `createModuleSubject(Module module)` Creates a `Subject` for a `Module`.
`com.sun.xacml.ctx.RequestCtx` `createQueryRequest(XQueryContext context, XACMLSource source)` Creates an XACML request for permission to execute an XQuery main module.
`java.util.Set` `createQueryResource(XACMLSource source)` Creates the Resource section of a request for a main module.
`java.util.Set` `createQuerySubjects(User user, Module contextModule)` Creates `Subject`s for the specified user and module.
`com.sun.xacml.ctx.RequestCtx` `createReflectionRequest(XQueryContext context, Module contextModule, java.lang.String className, java.lang.String methodName)` Creates a `RequestCtx` for a request concerning reflective access to Java code from an XQuery.
`java.util.Set` `createReflectionResource(java.lang.String className, java.lang.String methodName)` Creates a `Set` of `Attribute`s for a resource representing Java reflection in an XQuery.
`com.sun.xacml.ctx.Subject` `createUserSubject(User user)` Creates a `Subject` for a `User`.
`static XACMLSource` `generateModuleSource(Module module)` Generates an `XACMLSource` for a `Module` based on its implementing class name (if it is an `InternalModule`) or its `Source` (if it is an `ExternalModule`).
`static java.lang.String` `getModuleCategory(Module module)` Returns the module type for the given XQuery library module.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### createQueryRequest

    public com.sun.xacml.ctx.RequestCtx createQueryRequest(XQueryContext context,
                                                           XACMLSource source)

  Creates an XACML request for permission to execute an XQuery main module. The subjects section will contain a subject for the user obtained from the specified context. The resource section will be created by the createQueryResource method. The action-id will be `execute query`. The environment section will be created by createEnvironment, using the access context of the query context.

  Parameters:
    `context` - The context for this query
    `source` - The source of this query
  Returns:
    A `RequestCtx` that may be evaluated by the PDP to determine whether the specified user may execute the query represented by `source`.

### createReflectionRequest

    public com.sun.xacml.ctx.RequestCtx createReflectionRequest(XQueryContext context,
                                                                Module contextModule,
                                                                java.lang.String className,
                                                                java.lang.String methodName)

  Creates a `RequestCtx` for a request concerning reflective access to Java code from an XQuery. This handles occurs when a method is being invoked on the class in question. This method creates a request with the following content:
  - Subjects for the contextModule and user are created with the createQuerySubjects method.
  - Resource attributes are created with the `createReflectionResource` method.
  - Action attributes are created with the `createBasicAction` method. The action-id is `invoke method`.
  - The `XACMLConstants.ACCESS_CONTEXT_ATTRIBUTE` access context attribute is generated for the environment section.

  Parameters:
    `context` - The `XQueryContext` for the module making the request.
    `contextModule` - The query containing the reflection.
    `className` - The name of the class that is being accessed or loaded.
    `methodName` - The name of the method that is being invoked
  Returns:
    A `RequestCtx` that represents the access in question.

### createFunctionRequest

    public com.sun.xacml.ctx.RequestCtx createFunctionRequest(XQueryContext context,
                                                              Module contextModule,
                                                              QName functionName)

  Creates a `RequestCtx` for a request concerning access to a function in an XQuery library module. If the function is from a main module, this method returns null to indicate that. The client should interpret this to mean that the request is granted because access to a main module implies access to its functions.

  This method creates a request with the following content:

  - Subjects for the contextModule and user (obtained from the XQueryContext) are created with the createQuerySubjects method.
  - The specified functionModule parameter is used to generate the `source-key`, `source-type`, and `module category` attributes. The functionName parameter is the value of the `subject-id` attribute (the local part) and of the `module namespace` attribute (the namespace URI part). The `resource-category` attribute is `function`.
  - Action attributes are created with the `createBasicAction` method. The action is `call function`.
  - The `XACMLConstants.ACCESS_CONTEXT_ATTRIBUTE` access context attribute is generated for the environment section.

  Parameters:
    `context` - The query context.
    `contextModule` - The query making the access.
    `functionName` - The `QName` of the function being called.
  Returns:
    A `RequestCtx` that represents the access in question or `null` if the function belongs to a main module and not a library module.

### createUserSubject

    public com.sun.xacml.ctx.Subject createUserSubject(User user)

  Creates a `Subject` for a `User`. The user's name is the value of the `subject-id` attribute. The subject-category is `access-subject`. The `group` attribute is a bag containing the name of each group of which the user is a member.

  Parameters:
    `user` - The user making the request
  Returns:
    A `Subject` for use in a `RequestCtx`

### createBasicAction

    public java.util.Set createBasicAction(java.lang.String action)

  Creates the basic attributes needed to describe a simple action in a request. The `action` parameter is the value of the `action-id` attribute and the `namespace` attribute for the action-id is eXist's XACML `action namespace`.

  Parameters:
    `action` - The `action-id` of the action.
  Returns:
    A `Set` that contains attributes describing the action for use in a `RequestCtx`

### createModuleSubject

    public com.sun.xacml.ctx.Subject createModuleSubject(Module module)

  Creates a `Subject` for a `Module`. If the module is external, its `Source` is the value of the `subject-id` attribute, otherwise, the name of the implementing class is used. The subject-category is `codebase`. The value of the `module namespace` attribute is the namespace URI of the module. The `module category` attribute is the type of module, either `internal` or `external`.

  Parameters:
    `module` - A query module involved in making the request
  Returns:
    A `Subject` for use in a `RequestCtx`

### createReflectionResource

    public java.util.Set createReflectionResource(java.lang.String className,
                                                  java.lang.String methodName)

  Creates a `Set` of `Attribute`s for a resource representing Java reflection in an XQuery. The `resource-category` attribute is `method`. The `source-type` attribute is `class` and the `source-key` attribute is the name of the class. The `resource-id` attribute is the method name.

  Parameters:
    `className` - The name of the Java class
    `methodName` - The name of the method being invoked
  Returns:
    A `Set` containing the `Attribute`s describing access to Java code by reflection.

### createQueryResource

    public java.util.Set createQueryResource(XACMLSource source)

  Creates the Resource section of a request for a main module.

  Parameters:
    `source` - The source of the query.
  Returns:
    A `Set` containing attributes for the specified query.

### createQuerySubjects

    public java.util.Set createQuerySubjects(User user,
                                             Module contextModule)

  Creates `Subject`s for the specified user and module. This is equivalent to putting the `Subject`s created by the `createUserSubject(User user)` and `createModuleSubject(Module contextModule)` methods. The context module may be null if there is no context module.

  Parameters:
    `user` - The user making the access
    `contextModule` - The module involved in the access, if any. It may be null to indicate the is not an intermediary XQuery module.
  Returns:
    A `Set` containing a `Subject` for each the context module if there is one and the user.

### createEnvironment

    public java.util.Set createEnvironment(AccessContext accessCtx)

  Creates the environment section of a request for the given `AccessContext`.

  Parameters:
    `accessCtx` - The context
  Returns:
    A `Set` containing one attribute, the `access context` attribute with the value of the specified access context.

### generateModuleSource

    public static XACMLSource generateModuleSource(Module module)

  Generates an `XACMLSource` for a `Module` based on its implementing class name (if it is an `InternalModule`) or its `Source` (if it is an `ExternalModule`).

  Parameters:
    `module` - the module for which the source should be generated
  Returns:
    an `XACMLSource` that uniquely defines the source of the given module

### getModuleCategory

    public static java.lang.String getModuleCategory(Module module)

  Returns the module type for the given XQuery library module. This is either `internal` or `external`

  Parameters:
    `module` - The XQuery library module. If it is null, this method returns null.
  Returns:
    null if module is null, the module's category (internal or external) otherwise

### addSourceAttributes

    public static void addSourceAttributes(java.util.Set attributes,
                                           XACMLSource source)

  Adds new attributes to the specified `Set` of attributes that represent the specified source. The added attributes are the `source's key` and the `source's type`.

  Parameters:
    `attributes` - The `Set` to which attributes will be added. If null, this method does nothing.
    `source` - The source for which attributes will be added. It cannot be null.

### addStringAttribute

    public static void addStringAttribute(java.util.Set attributes,
                                          java.net.URI attrID,
                                          java.lang.String attrValue)

  Adds a new attribute of type string to the specified `Set` of attributes. The new attribute's value is constructed from the attrValue parameter and is given the id of the attrID parameter.

  Parameters:
    `attributes` - The `Set` to which the new attribute should be added. If it is null, this method does nothing.
    `attrID` - The ID of the new attribute, cannot be null
    `attrValue` - The value of the new attribute. It cannot be null.

### addURIAttribute

    public static void addURIAttribute(java.util.Set attributes,
                                       java.net.URI attrID,
                                       java.lang.String uriString)
                                throws java.net.URISyntaxException

  Adds a new attribute of type anyURI to the specified `Set` of attributes. The new attribute's value is constructed from the uriString parameter and is given the id of the attrID parameter.

  Parameters:
    `attributes` - The `Set` to which the new attribute should be added. If it is null, this method does nothing.
    `attrID` - The ID of the new attribute, cannot be null
    `uriString` - The value of the new attribute. It must parse into a valid URI and cannot be null.
  Throws:
    `java.net.URISyntaxException` - if the specified attribute value is not a valid URI.

Copyright (C) Wolfgang Meier. All rights reserved.