**Security Descriptor Framework**

1.  **Overview**

Security descriptors in the toolkit have schemas defined for them and
each of them (container, service, resource and client) has an
independent namespace. If a security descriptor file is configured at
the container or service level, they are initialized at container start
up and service initialization respectively.

The descriptors are validated against the schema and then parsed using
Apache Commons Digester. A Java object representation of the descriptor
is created.

A single ContainerSecurityDescriptor object is created per JVM and
contains all security properties for the container. This poses issues
when multiple notification consumers are started up in same JVM with
different security properties.

If a service is configured with security descriptor file, a
ServiceSecurityDescriptor object is created for it and stored using
JNDI. It is keyed on the service name (just the name of service without
wsrf/services.) and ServiceSecurityHelper API can be used to set and
retrieve security properties for a particular service.

To set up security in a resource, ResourceSecurityDescriptor is used and
the security properties can also be read from a descriptor file. The
resource security descriptor is stored in the resource itself.

2.  **Configuring descriptors**

    1.  Container Security Descriptor

        1.  In global security descriptor section

> \<parameter name="containerSecDesc"
> value="path/container/descriptor"/\>

2.  Command line argument at container start up

> -containerSecDesc "path/container/descriptor"

2.  Service Security Descriptor

    1.  In service security descriptor section

> \<parameter name="securityDescriptor"
> value="path/service/descriptor"/\>

2.  Programmatically, using get/set methods.

> ServiceSecurityDescriptor descriptor = new
> ServiceSecurityDescriptor();
>
> // use set methods to set properties
>
> ServiceSecurityHelper.setSecurityDescriptor("servicePath",
> descriptor);

3.  Programmatically, but from file

> ServiceSecurityDescriptor descriptor =
>
> new ServiceSecurityDescriptor("servicePath",
>
> "path/service/descriptor");

3.  Resource Security Descriptor

    1.  Programmatically, from file

> ResourceSecurityDescriptor desc =
>
> new ResourceSecurityDescriptor("/path/resource/descriptor");

2.  Programatically, using get/set methods.

> ResourceSecurityDescriptor desc =
>
> new ResourceSecurityDescriptor();
>
> // use set methods to set properties

3.  **Security Descriptor Namespaces**

> Since validation is done, each security descriptor is defined with its
> own namespace

-   Container security descriptor:
    <http://www.globus.org/security/descriptor/container>

-   Service security descriptor:
    <http://www.globus.org/security/descriptor/service>

-   Resource security descriptor:
    http://www.globus.org/security/descriptor/service

4.  **Configuration Common to Container, Service and Resource
    descriptor**

    1.  Reject Limited Proxy: This property determines if limited
        proxies are accepted by the server. By default limited proxies
        are accepted.

> \<reject-limited-proxy value="true"/\>

2.  Credentials: This property can be used to configure a proxy or
    certificate/key file to use.

> To set proxy file:
>
> \<credential\>
>
> \<proxy-file value="/tmp/proxyFile"/\>
>
> \</credential\>
>
> To set certificate and key file:
>
> \<credential\>
>
> \<cert-key-files\>
>
> \<key-file value="/home/user1/keyFile"/\>
>
> \<cert-file value="/home/user1/certFile"/\>
>
> \</cert-key-files\>
>
> \</credential\>

3.  Replay Attack Filter: Property determines whether a reply attack
    filter should be used when Secure Message security is used. By
    default the value is true.

> \<replay-attack-filter value="false"/\>

4.  Replay Attack Window: Value of the replay window in minutes. If
    configured value is x minutes, the window is --x to +x and only
    unique messages with in that window is accepted. By default the
    window is set to 5 minutes.

> \<replay-attack-window value="10"/\>

5.  Authorization: Specifies the authorization chain configuration to
    use. Each chain can contain an optional list of Bootstrap PIPs, an
    optional list of PIPs and a list of PDPs (with atleast one PDP).

> The Bootstrap PIP configuration allows for setting a boolean attribute
> called 'overwrite". If this is set to true, then the X509BootstrapPIP
> is not invoked by the framework. If the "overwrite" attribute is not
> set or set to false, the X509BootstrapPIP is invoked prior to invoking
> the configured Bootstrap PIPs.
>
> \<authzChain combiningAlg="org.globus.sample.SampleAlg\>
>
> \<bootstrapPips overwrite="true"\>
>
> \<interceptor name="scope1:org.globus.sample.BootstrapPIP1"/\>
>
> \</bootstrapPips\>
>
> \<pips\>
>
> \<interceptor name="scope2:org.globus.sample.PIP1"/\>
>
> \</pips\>
>
> \<pdps\>
>
> \<interceptor name="scope3:org.globus.sample.PDP1"/\>
>
> \<interceptor name="scope4:org.globus.sample.PDP2"/\>
>
> \</pdps\>
>
> \</authzChain\>

Each interceptor can specify a parameter value and the schema defines it
as xsd:any to allow for any user defined parameters. The parser extracts
the elements in \<parameter\> element and returns them as DOM Element.
It is left up to the Interceptor to parse the Element. The DOM object
created is placed in the ChainConfig object passed to the authorization
engine as a parameter called "parameterObject". The prefix will be the
scope specified in the interceptor name.

> Since schema validation is done, a schema must be supplied for the
> user defined parameters. The schema location is loaded as a resource
> and hence can be included in some jar placed in GLOBUS_LOCATION lib
> directory.
>
> For example, the toolkit provides for a schema that allows a list of
> name value pairs as parameter.
>
> \<?xml version=\"1.0\" encoding=\"UTF-8\"?\>
>
> \<containerSecurityConfig
> xmlns=\"http://www.globus.org/security/descriptor/container\"
> xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
> xsi:schemaLocation=[http://www.globus.org/security/descriptor
> name_value_type.xsd](http://www.globus.org/security/descriptor name_value_type.xsd)
>
> xmlns:param=\"http://www.globus.org/security/descriptor\" \>
>
> \<authzChain\>
>
> \<pdps\>
>
> \<interceptor
> name=\"gridmapAuthz:org.globus.wsrf.impl.security.GridMapAuthorization\"\>
>
> \<parameter\>
>
> \<param:nameValueParam\>
>
> \<param:parameter name=\"gridmap-file\"
>
> value="/home/user1/grid-mapfile\"/\>
>
> \</param:nameValueParam\>
>
> \</parameter\>
>
> \</interceptor\>
>
> \</pdps\>
>
> \</containerSecurityConfig\>
>
> When the above is parsed, a DOM Element is constructed with element
> \<param:nameValuParam\> and stored in the ChainConfig object as
> parameter with name "gridmapAuthz:parameterObject". The
> GridMapAuthorization PDP, uses ObjectDeserializer to retrieve the
> name/value pairs.

6.  Context Lifetime: Sets the lifetime of the context created when GSI
    Secure Conversation is used. By default the lifetime of the
    credential used to create the context is used.

> \<context-lifetime value="1000"/\>

5.  **Container Descriptor Specific Configuration**

    1.  Trusted Certificates: This is used to set up location of trusted
        certificates to be used. The value should be a comma separated
        list of locations.

> \<trusted-certificates
>
> value="/home/user1/trustedCerts /home/user1/newCerts"/\>

2.  Admin Authorization Chain: This configured the administrator
    authorization chain and is configured just like the authorization
    chain described in 8.3.5. But the element is \<adminAuthzChain\>

3.  Default Authorization Parameters: This element is used to configure
    default properties for any interceptor configured in authorization
    chains. The schema for this is similar to the authorization chain
    specification and allows for xsd:any as interceptor parameter.

> \<defaultAuthzParam\>
>
> \<interceptor name="scope1:org.globus.sample.SamplePDP"/\>
>
> \<parameter\>
>
> \<param:nameValueParam\>
>
> \<param:parameter name=\"policy-file\"
>
> value="/home/user1/samplePDPConfig\"/\>
>
> \</param:nameValueParam\>
>
> \</parameter\>
>
> \</interceptor\>
>
> \</defaultAuthzParam\>

4.  Replay Timer Interval: Sets the interval on the timer thread that
    collects expired message digest ids, stored to prevent replay
    attack. The value is set in seconds and the default value is 1
    minute.

> \<replay-timer-interval value="1000"/\>

5.  Context Timer Interval: Sets the interval on the timer thread that
    collects expired contexts established when GSI Secure Conversation
    is used. The value is the number of seconds between each run and
    defaults to 10minutes.

> \<context-timer-interval value="1000"/\>

6.  **Service/Resource Descriptor Specific Configuration**

    1.  Method Authentication: This element allows for per method
        configuration of required security mechanism

> \<methodAuthenticaiton\>
>
> \<method name="add"\>
>
> \<GSISecureMessage\>
>
> \<protection-level\>
>
> \<privacy/\>
>
> \<integrity/\>
>
> \</protection\>
>
> \</GSISecureMessage\>
>
> \<GSISecureTransport/\>
>
> \</method\>
>
> \<method name="create"\>
>
> \<GSISecureConversation/\>
>
> \</method\>

2.  Default Authentication: This element specifies the default security
    mechanism required by methods in this service. A per method
    configuration override this.

> \<auth-method\>
>
> \<GSISecureTransport/\>
>
> \</auth-method\>

3.  Method Run As: This element determines the credentials to associate
    with the thread in which the actual operation is invoked. By default
    resource credentials are used.

> \<methodAuthentication\>
>
> \<method name="add"\>
>
> \<run-as value="service"/\>
>
> \</method\>
>
> \</methodAuthentication\>

4.  Default Run As: This element determines the credentials to use when
    a run-as configuration is not done for a method.

> \<run-as value="system"\>

7.  **Descriptor Processing Details.**

    1.  Container Descriptor: If container security descriptor is
        configured at start up on command line or in server-config.wsdd,
        it is initialized when container is started. If not, the first
        call to ContainerSecurityDescriptor.getInstance() creates an
        object and a single instance of ContainerSecurityDescriptor
        object is maintained per JVM.

        1.  Loading descriptor files: The configured file is loaded in
            the following order:

-   If path specified is absolute, it is loaded as a file

-   If not, it is loaded as resource

-   If load as resource is null, it is loaded relative to config
    directory (retrieved using MC_CONFIGPATH)

> The initialization step sets up the following if container security
> configuration file is configured: credentials, container-levl
> authorization and default authorization, and trusted certificates. The
> rest of the parameters in the file are also parsed and stored.
> Credentials are loaded per configuration file and if not specified, an
> attempt is made to load default credentials. If it is a secure
> container, then default credentials must be present if none is
> specified in the configuration file, otherwise an error is thrown.
>
> Notification consumers can be configured with a
> ContainerSecurityDescriptor object to set up properties for the
> container it starts up. If the consumer is started up with in the same
> JVM as the container, the descriptor object is overwritten.

1.  Service Descriptor: Each service can be configured with a descriptor
    in its service descriptor section in sever-config.wsdd. At container
    startup, when the service is initialized, the service security
    descriptor is also initialized using
    ServiceSecurityHelper.initialize(). Initialization steps include the
    following:

-   Load descriptor from configured file. It is loaded as described in
    Section 7.1.1

-   Validate and parse it to create a ServiceSecurityDescriptor object.

-   Load credential, if configured

-   Create AuthorizationEngine instance, if configured. Initialize all
    component PDPs and PIPs.

-   Store ServiceSecurityDescriptor object in JNDI, with service name as
    path. (just the service name without wsrf/services)

-   Set initialized property for this service to true in JNDI, so that
    the descriptor is not initialized each time service is access.

> The ServiceSecurityHelper provides API to get and set security
> properties for various services. The setSecurityDescriptor method
> allows to set a completely different security descriptor object, while
> the other methods manipulate the existing descriptor. Note that, if
> setSubject is used to set a new subject and credential paths are also
> configured, a refresh overwrites the subject with one that is
> configured as credential paths.

1.  Resource Descriptor: Each resource, that implements the
    SecureResource, interface can be configured with a resource security
    descriptor. The descriptor can either be created programmatically or
    loaded from a file. This descriptor is identical to the service
    security descriptor and the ResourceSecurityDescriptor class defines
    it.

> If the descriptor is setup from a file, then the constructed in
> ResourceSecurityDescriptor loads it from the file and initializes it
> like described in previous section. The descriptors are not stored in
> JNDI though and are stored in the resource itself.
>
> SecureResourcePropertiesHelper provides API to get and set security
> properties for various resources.