Resource Management Interface Specs Scott Jackson

Draft Initial Release v. 2.0 Brett Bode

2 MAR 2003 David Jackson

Scalable Systems Software Resource Management and Accounting Protocol
(SSSRMAP)

Status of this Memo

> This is a draft form of the initial resource management interface
> specification. Much of what is expressed is still in active discussion
> and virtually nothing within it has been definitively decided. One
> purpose of this document at this stage is to propose a set of protocol
> characteristics that can then be tested in prototypes and compared
> against alternative approaches.

Abstract

> This document is a draft specification describing a
> connection-oriented XML-based application layer client-server protocol
> for the interaction of resource management and accounting software
> components developed as part of the Scalable Systems Software Center.
> The SSSRMAP protocol defines a request-response syntax supporting the
> query and update of extensible objects. The protocol is specified in
> XML Schema Definition and rides on the HTTP protocol.

Conventions Used In This Document

> The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL
> NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and
> \"OPTIONAL\" in this document are to be interpreted as described in
> \[KEYWORDS\].

Table of Contents

[1 Introduction 3](#introduction)

[2 Conventions Used in this Document
3](#conventions-used-in-this-document)

[2.1 Keywords 3](#keywords)

[2.2 XML Case Conventions 3](#xml-case-conventions)

[3 Encoding 4](#encoding)

[3.1 SSSRMAP Message Types 4](#sssrmap-message-types)

[3.1.1 Schema Header and Namespaces 4](#schema-header-and-namespaces)

[3.1.2 The *Trans* Element 5](#the-trans-element)

[3.1.3 The *Request* Element 6](#the-request-element)

[3.1.4 The *Get* Element 6](#the-get-element)

[3.1.5 The *Set* Element 7](#the-set-element)

[3.1.6 The *Where* Element 8](#the-where-element)

[3.1.7 The *Option* Element 9](#the-option-element)

[3.1.8 The *Data* Element 9](#the-data-element)

[3.1.9 The *Count* Element 10](#the-count-element)

[3.1.10 The *Reply* Element 10](#the-reply-element)

[3.1.11 The *Response* Element 11](#the-response-element)

[3.1.12 The *Status* Element 12](#the-status-element)

[3.1.13 The *Code* Element 12](#the-code-element)

[3.1.14 The *Message* Element 12](#the-message-element)

[3.1.15 The *Notify* Element 13](#the-notify-element)

[3.1.16 The *Ack* Element 13](#the-ack-element)

[3.2 Examples 14](#examples)

[3.2.1 Sample Requests 14](#sample-requests)

[3.2.2 Sample Responses 15](#sample-responses)

[3.2.3 Sample Notification 16](#sample-notification)

[3.2.4 Sample Acknowledgement 16](#sample-acknowledgement)

[4 Error Reporting 16](#error-reporting)

[5 Transport Layer 17](#transport-layer)

[6 Framing 17](#framing)

[6.1 Message Header Requirements 17](#message-header-requirements)

[6.2 Message Payload Format 18](#message-payload-format)

[6.3 Reply Header Requirements 18](#reply-header-requirements)

[6.4 Reply Payload Format 18](#reply-payload-format)

[6.5 Examples 18](#examples-1)

[6.5.1 Sample SSSRMAP Message Embedded in HTTP Request
18](#sample-sssrmap-message-embedded-in-http-request)

[6.5.2 Sample SSSRMAP Reply Embedded in HTTP Response
19](#sample-sssrmap-reply-embedded-in-http-response)

[7 Asynchrony 19](#asynchrony)

[8 Security 19](#security)

[8.1 Security Token 20](#security-token)

[8.1.1 Security Token Element 20](#security-token-element)

[8.1.2 Security Token Types 21](#security-token-types)

[8.1.2.1 Symmetric Key 21](#symmetric-key)

[8.1.2.2 Asymmetric Key 21](#asymmetric-key)

[8.1.2.3 Password 21](#password)

[8.1.2.4 Cleartext 22](#cleartext)

[8.1.2.5 Kerberos 22](#kerberos)

[8.1.2.6 GSI (X.509) 22](#gsi-x.509)

[8.1.3 Example 22](#example)

[8.2 Authentication 23](#authentication)

[8.2.1 The *Signature* Element 23](#the-signature-element)

[8.2.2 The *DigestValue* Element 24](#the-digestvalue-element)

[8.2.3 The *SignatureValue* Element 25](#the-signaturevalue-element)

[8.2.4 Signature Example 25](#signature-example)

[8.3 Confidentiality 26](#confidentiality)

[8.3.1 The *EncryptedData* Element 26](#the-encrypteddata-element)

[8.3.2 The *EncryptedKey* Element 27](#the-encryptedkey-element)

[8.3.3 The *CipherValue* Element 28](#the-ciphervalue-element)

[8.3.4 Encryption Example 28](#encryption-example)

[9 Acknowledgements 29](#acknowledgements)

[10 References 29](#references)

# Introduction

> A major objective of the Scalable Systems Software \[SSS\] Center is
> to create a scalable and modular infrastructure for resource
> management on terascale clusters including resource scheduling,
> meta-scheduling, node daemon support, comprehensive usage accounting
> and user interfaces emphasizing portability to terascale vendor
> operating systems. Existing resource management and accounting
> components feature disparate APIs (Application Programming Interfaces)
> requiring various forms of application coding to interact with other
> components.
>
> This document proposes a wire level protocol expressed in an XML
> request-response syntax to be considered as the foundation of a
> standard for communications between and among resource management and
> accounting software components. In this document this standard is
> expressed in two levels of generality. The features of the core
> SSSRMAP protocol common to all resource management and accounting
> components in general are described in the main body of this document.
> The aspects of the syntax specific to individual components are
> described in the Appendix.

# Conventions Used in this Document

## Keywords

The keywords "MUST", "MUST NOT", "REQUIIRED", "SHALL", "SHALL NOT",
"SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
be interpreted as described in RFC2119 \[RFC2119\].

## XML Case Conventions

> In order to enforce a consistent capitalization and naming convention
> across all SSSRMAP specifications "Upper Camel Case" (UCC) and "Lower
> Camel Case" (LCC) Capitalization styles shall be used. UCC style
> capitalizes the first character of each word and compounds the name.
> LCC style capitalizes the first character of each word except the
> first word. \[XML_CONV\]\[FED_XML\]

1.  SSSRMAP XML Schema and XML instance documents SHALL use the
    following conventions:

    -   Element names SHALL be in UCC convention (example:
        \<UpperCamelCaseElement/\>.

    -   Attribute names SHALL be in LCC convention (example:
        \<UpperCamelCaseElement lowerCamelCaseAttribute="Whatever"/\>.

2.  General rules for all names are:

-   Acronyms SHOULD be avoided, but in cases where they are used, the
    capitalization SHALL remain (example: XMLSignature).

-   Underscores (\_), periods (.) and dashes (-) MUST NOT be used
    (example: use JobId instead of JOB.ID, Job_ID or job-id).

# Encoding

> Encoding tells how a message is represented when exchanged. SSSRMAP
> data exchange messages SHALL be defined in terms of XML schema
> \[XML_SCHEMA\].

## SSSRMAP Message Types

> The SSSRMAP protocol provides four general message types: requests,
> responses, notifications and acknowledgements.
>
> When a session is established and the client authenticated, the
> protocol allows two styles of data exchange between the client and
> server. \[XRP\]

1.  request/response -- the client sends a "request" message requesting
    the server to perform the task, the server performs the task and
    returns a "response" reply. \[XRP\]

2.  notify/ack -- the server notifies clients about certain events in
    the system, and receives an "ack" reply as an acknowledgement.
    \[XRP\]

> Both styles are one-to-one synchronous exchanges wherein a single
> message is sent from the client to the server, and a corresponding
> reply is sent from the server to the client.

### Schema Header and Namespaces

> The header of the schema definition is as follows:
>
> \<?xml version=\"1.0\" encoding=\"UTF-8\"?\>
>
> \<schema

xmlns="<http://www.w3.org/2001/XMLSchema>"

xmlns:sssrmap="http://www.scidac.org/ScalableSystems/SSSRMAP"

targetNamespace="http://www.scidac.org/ScalableSystems/SSSRMAP"

elementFormDefault=\"qualified\"\>

> A message MUST consist of a single *Trans* element. A reply MUST
> consist of a single *Reply* element. These MAY contain namespace and
> other xsd-specific information necessary to validate the document
> against the schema.

### The *Trans* Element

> The *Trans* element (short for transmission) is a root element that
> delimits the set of requests or notifications sent to the server. It
> MUST contain one or more *Request* or *Notify* elements. It MAY
> contain namespace and other xsd-specific information necessary to
> validate the document against the schema. In addition, it MAY have any
> of the following attributes which may serve as processing clues to the
> parser:

-   *type* -- A message type such as "Request" or "Notification"

-   *actor* -- The authenticated user sending the message

-   *count* -- A positive integer indicating the number of items in the
    batch

-   *component* -- A component type such as "QueueManager" or
    "LocalScheduler"

-   *name* -- A component name such as "OpenPBS" or "Maui"

-   *version* -- A component version such as "2.2p12" or "3.2.2"

> Schema Definition:
>
> \<complexType name=\"TransmissionType\"\>
>
> \<choice minOccurs=\"1\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Request\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any minOccurs=\"0\" maxOccurs=\"unbounded\" namespace=\"##other\"/\>
>
> \</choice\>
>
> \<attribute name=\"type\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"actor\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"count\" type="integer" use=\"optional\"/\>
>
> \<attribute name=\"component\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"version\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Trans\" type=\"sssrmap:TransmissionType\"/\>

### The *Request* Element

> The *Request* element specifies an individual request. Depending on
> context, it MAY contain one or more *Get* elements or one or more
> *Set* elements as well as a *Count* element and any number of *Where*
> or *Data* elements.
>
> It MUST have both an *object* and *action* attribute and MAY have an
> *id* attribute.

-   *object* -- specifies the object class to be acted upon such as
    "job" or "node"

-   *action* -- specifies the action to be performed on the object such
    as "create", "query", "modify" or "delete"

-   *id* \-- uniquely maps the request to the appropriate response

> Schema Definition:
>
> \<complexType name=\"RequestType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"1\"\>
>
> \<element ref=\"sssrmap:Get\" minOccurs=\"1\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Set\" minOccurs=\"1\"
> maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<element ref=\"sssrmap:Where\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Count\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<any namespace="##other" minOccurs=\"0\" maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<attribute name=\"object\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"action\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Request\" type=\"sssrmap:RequestType\"/\>

### The *Get* Element

> The *Get* element is used to indicate the data fields to be returned
> in a query. *Get* is typically used within requests with
> *action*="query". Multiple *Get* elements cause the fields to be
> returned in the order specified. If no *Get* elements are specified,
> the query will return a default set of fields.
>
> The valid attributes are:

-   *name* -- the name of the data field to be returned

-   *op* -- the operator to be used to aggregate or perform an operation
    on the returned values.

    -   An *op* attribute of "sort" specifies an ascending sort
        operation

    -   An *op* attribute of "tros" specifies a descending sort
        operation

    -   An *op* attribute of "sum" returns the sum (only valid for
        numeric values)

    -   An *op* attribute of "max" returns the maximum value

    -   An *op* attribute of "min" returns the minimum value

    -   An *op* attribute of "count" returns the number of values

    -   An *op* attribute of "groupby" signifies that aggregates are
        grouped by this field

-   *units* -- the units in which to return the value (if applicable)

> Schema Definition:
>
> \<complexType name=\"GetType\"\>
>
> \<attribute name=\"name\" type="string" use=\"required\"/\>
>
> \<attribute name=\"units\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Get\" type=\"sssrmap:GetType\"/\>

### The *Set* Element

> The *Set* element is used to specify the object data fields to be
> assigned values. *Set* is typically used within requests with
> *action*="create" or *action*="modify". The use of *Get* or *Set*
> elements within a request are mutually exclusive.

The valid attributes are:

-   *name* -- the name of the field being assigned a value

-   *value* -- the new value for the field being changed

-   *op* -- the operator to be used in assigning a new value to the
    name. If an *op* attribute is not specified and a value is
    specified, the specified value will be assigned to the named field
    ("assign").

    -   An *op* attribute of "assign" assigns value to the named field

    -   An *op* attribute of "inc" increments the named field by the
        value

    -   An *op* attribute of "dec" decrements the named field by the
        value

-   *units* -- the units corresponding to the value being set

A *Set* element without a *value* may be used as an assertion flag.

> Schema Definition:
>
> \<complexType name=\"SetType\"\>
>
> \<attribute name=\"name\" type="string" use=\"required\"/\>
>
> \<attribute name=\"value\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"units\" type="string" use=\"optional\"/\>

\</complexType\>

> \<element name=\"Set\" type=\"sssrmap:SetType\"/\>

### The *Where* Element

> A *Request* element may contain one or more *Where* elements that
> specify the search conditions for which objects the action is to be
> performed on or supply constraints or options to the request.
>
> Only a *name* attribute is required. All other fields are optional.

-   *name* -- the name of the data field to be tested

-   *value* -- the value against which the objects data value is tested

-   *op* -- the operator to be used to test the name against the value.
    If an *op* attribute is not specified and a value is specified, the
    field will be tested whether it is equal to the value ("eq").

    -   An *op* attribute of "eq" specifies an equality comparison

    -   An *op* attribute of "lt" specifies a "less than" comparison

    -   An *op* attribute of "gt" specifies a "greater than" comparison

    -   An *op* attribute of "le" specifies a "less than or equal to"
        test

    -   An *op* attribute of "ge" specifies a "greater than or equal to"
        test

    -   An *op* attribute of "ne" specifies a "not equal to" test

    -   An *op* attribute of "like" specifies a regular expression
        matching comparison

-   *conj* \-- indicates whether this test is to be anded or ored with
    the immediately preceding where condition

    -   A *conj* attribute of "and" specifies an "and" conjunction

    -   A *conj* attribute of "or" specifies an "or" condition

    -   A *conj* attribute of "andnot" specifies an "and not"
        conjunction

    -   A *conj* attribute of "ornot" specifies an "or not" condition

-   *group --* indicates an increase or decrease of parentheses grouping
    depth

    -   A positive number indicates the number of left parentheses to
        precede the condition, i.e. *group*="2" represents
        "((condition".

    -   A negative number indicates the number of right parentheses to
        follow the condition, i.e. *group*="-2" represents
        "condition))".

-   *units* -- indicates the units to be used in the value comparison

> Schema Definition:
>
> \<complexType name=\"WhereType\"\>
>
> \<attribute name=\"name\" type="string" use="required"/\>
>
> \<attribute name=\"value\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"op\" type=\"sssrmap:OperatorType\"
> use=\"optional\"/\>
>
> \<attribute name=\"conj\" type=\"sssrmap:ConjunctionType\"
> use=\"optional\"/\>
>
> \<attribute name=\"group\" type=\"integer\" use=\"optional\"/\>
>
> \<attribute name=\"units\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Where\" type=\"sssrmap:WhereType\"/\>

### The *Option* Element

> The *Option* element is used to indicate processing options for the
> command. An option might be used to indicate that command usage or
> special formatting is desired, or that the command is to be invoked
> with particular options.

The valid attributes are:

-   *name* -- the name of the field being assigned a value

-   *value* -- the new value for the field being changed

-   *op* -- the operator to be used to disassert the option

    -   An *op* attribute of "not" specifies that the option is not
        asserted

-   *conj* \-- indicates whether this test is to be anded or ored with
    the immediately preceding where condition

    -   A *conj* attribute of "and" specifies an "and" conjunction

    -   A *conj* attribute of "or" specifies an "or" condition

    -   A *conj* attribute of "andnot" specifies an "and not"
        conjunction

    -   A *conj* attribute of "ornot" specifies an "or not" condition

An *Option* element without a *value* may be used as an assertion flag.

> Schema Definition:
>
> \<complexType name=\"OptionType\"\>

\<attribute name=\"name\" type="string" use=\"required\"/\>

> \<attribute name=\"value\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Option\" type=\"sssrmap:OptionType\"/\>

### The *Data* Element

> A *Request* or *Response* element may have one or more *Data* elements
> that allow the supplying of context-specific data. A request might
> pass in a structured object via a *Data* element to be acted upon.
> Typically a query will result in a response with the data encapsulated
> within a *Data* element.
>
> The following attributes are optional:

-   *name* -- object name describing the contents of the data

-   *type* -- describing the form in which the data is represented

    -   A *type* attribute of "xml" indicates the data has internal xml
        structure and can be recursively parsed by an XML parser

    -   A *type* attribute of "binary" indicates the data is an opaque
        dataset consisting of binary data

    -   A *type* attribute of "string" indicates the data is an ASCII
        string

    -   A *type* attribute of "int" indicates the data is an integer

    -   A type attribute of "text" indicates the data is in formatted
        human-readable text

    -   A type attribute of "html" indicates the data is represented in
        HTML

Schema Definition:

> \<complexType name=\"DataType\"\>
>
> \<sequence\>
>
> \<any namespace=\"##any\" processContents=\"lax\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \</sequence\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute ref=\"sssrmap:Type\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Data\" type=\"sssrmap:DataType\"/\>

### The *File* Element

> A *Request* or *Response* element may have one or more *File* elements
> of type String that allow the inclusion of files. The files may be
> either text or binary and may be referenced by objects inside the Data
> element. A file may be compressed using the gzip algorithm \[ZIP\]. A
> binary file or a compressed file must be base64 encoded as defined in
> XML Digital Signatures ("http://www.w3.org/2000/09/xmldsig#base64").
> Metadata describing the modes and properties of the resulting file are
> passed as parameters. The text or base64 encoded file data forms the
> string content of the *File* element.
>
> The following attributes are optional:

-   *name \--* specifies the name to give the file upon creation on the
    target system. This can be an absolute or relative pathname
    (relative to the InitialWorkingDirectory).

-   *owner* -- indicates what owner the file should be changed to. By
    default it will be changed to the UserId that the authenticated
    actor maps to on the target system. Note that this function should
    succeed only if the requestor has the privileges to do so (i.e.
    authenticated as root).

-   *group* -- indicates what group the file should be changed to. By
    default it will be set to the primary groupid of the UserId that the
    authenticated actor maps to on the target system. Note that this
    function should succeed only if the requestor has the proper
    privileges.

-   *mode* -- indicates the permissions the file should possess. By
    default it will be set according to the default umask for the UserId
    that the authenticated actor maps to on the target system. Note that
    this function should not set permissions for the file that exceed
    the privileges for the actor. These permissions can be specified
    using either an octal number or symbolic operations (as accepted by
    the GNU chmod(1) command).

-   *compressed* -- indicates whether the file has been compressed

    -   A *compressed* attribute of "true" indicates the file has been
        compressed.

    -   A *compressed* attribute of "false" indicates the file has not
        been compressed. This is the default.

-   encoded -- indicates whether the file has been base64 encoded

    -   An *encoded* attribute of "true" indicates the file has been
        compressed.

    -   An *encoded* attribute of "false" indicates the file has not
        been encoded. This is the default.

Schema Definition:

> \<complexType name=\"FileType\"\>
>
> \<sequence\>
>
> \<any namespace=\"##any\" processContents=\"lax\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \</sequence\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"owner\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"group\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"mode\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"compressed\" type="boolean" use=\"optional\"/\>
>
> \<attribute name=\"encoded\" type=\"boolean\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"File\" type=\"sssrmap:FileType\"/\>

### The *Count* Element

> A single *Count* element may be included within a *Request* or
> *Response* and is context-specific. This can be used to represent the
> number of objects acted upon.
>
> Schema Definition:
>
> \<element name=\"Count\" type=\"positiveInteger\"/\>

### The *Reply* Element

> The *Reply* element is a root element that delimits the set of
> responses or acknowledgements returned to the client. It MUST contain
> one or more *Response* or *Ack* elements. It MAY contain namespace and
> other xsd-specific information necessary to validate the document
> against the schema. In addition, it MAY have any of the following
> attributes:

-   *type* -- A reply type such as "Response" or "Acknowledgement"

-   *count* -- A positive integer indicating the number of items in the
    batch

-   *component* -- A component type such as "QueueManager" or
    "LocalScheduler"

-   *name* -- A component name such as "OpenPBS" or "Maui"

-   *version* -- A component version such as "2.2p12" or "3.2.2"

> Schema Definition:
>
> \<complexType name=\"ReplyType\"\>
>
> \<choice minOccurs=\"1\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Response\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<element ref=\"sssrmap:Ack\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any minOccurs=\"0\" maxOccurs=\"unbounded\" namespace=\"##other\"/\>
>
> \</choice\>
>
> \<attribute name=\"type\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"count\" type="integer" use=\"optional\"/\>
>
> \<attribute name=\"component\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"name\" type="string" use=\"optional\"/\>
>
> \<attribute name=\"version\" type="string" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Reply\" type=\"sssrmap:ReplyType\"/\>

### The *Response* Element

> The *Response* element specifies an individual response. It MUST
> contain *Status* and *Code* elements. It MAY also contain *Message*,
> *Count* and any number of *Data* elements.
>
> It MAY have an *object* and *action* attribute as well as an *id*
> attribute.

-   *object* -- specifies the object class to be acted upon such as
    "job" or "node"

-   *action* -- specifies the action to be performed on the object such
    as "create", "query", "modify" or "delete"

-   *id* \-- uniquely maps the response to the corresponding request

> Schema Definition:
>
> \<complexType name=\"ResponseType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Status\" minOccurs=\"1\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Code\" minOccurs=\"1\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Message\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Count\" minOccurs=\"0\" maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any minOccurs=\"0\" maxOccurs=\"unbounded\" namespace=\"##other\"/\>
>
> \</choice\>
>
> \<attribute name=\"object\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"action\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Response\" type=\"sssrmap:ResponseType\"/\>

### The *Status* Element

> A *Response* element must contain a single *Status* element that
> indicates whether the reply represents a success or a failure. The
> *Status* element must have a boolean value of "true" or "false".
>
> Schema Definition:
>
> \<element name=\"Status\" type=\"boolean\"/\>

### The *Code* Element

> A *Response* element must contain a single *Code* element that
> specifies the 3-digit status code for the response.

Schema Definition:

\<simpleType name=\"CodeType\"\>

\<restriction base=\"string\"\>

\<pattern value=\"\[0-9\]{3}\"/\>

\</restriction\>

\</simpleType\>

\<element name=\"Code\" type=\"sssrmap:CodeType\"/\>

### The *Message* Element

> A *Response* element may contain a single *Message* element that is
> context specific to the success or failure response. The message
> should be an error message if status is false. If present for a
> successful response, it may be used as a human readable message for a
> user interface.
>
> Schema Definition:
>
> \<element name=\"Message\" type=\"string\"/\>

### The *Notify* Element

> The *Notify* element may have one or more *Data* elements that carry
> the context-specific data with the event notification.
>
> It must have a name attribute while the others are optional:

-   *name* -- the name of the event that was triggered

-   *value* -- the value for the object that was changed

-   *id* -- uniquely maps the notification to its acknowledgement

> Schema Definition:
>
> \<complexType name=\"NotifyType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"unbounded\"\>
>
> \<element ref=\"sssrmap:Data\" minOccurs=\"0\"
> maxOccurs=\"unbounded\"/\>
>
> \<any namespace=\"##other\" minOccurs=\"0\" maxOccurs=\"unbounded\"/\>
>
> \</choice\>
>
> \<attribute name=\"name\" type=\"string\" use=\"required\"/\>
>
> \<attribute name=\"value\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Notify\" type=\"sssrmap:NotifyType\"/\>

### The *Ack* Element

> The Ack element may have a name attribute:

-   *name* -- the name of the event that was triggered

-   *id* -- uniquely maps the acknowledgement to the corresponding
    notification

> Schema Definition:
>
> \<complexType name=\"AckType\"\>
>
> \<attribute name=\"name\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"id\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name=\"Ack\" type=\"sssrmap:AckType\"/\>

## Examples

### Sample Requests

> Requesting a list of nodes with a certain configured memory threshold
> (batch format):
>
> \<Trans component="NodeMonitor" count="1"\>
>
> \<Request object="Node" action="Query" id="1"\>
>
> \<Get name="Name" /\>
>
> \<Get name="ConfiguredMemory" /\>
>
> \<Where name="ConfiguredMemory" op="ge" unit="MB" value="512"/\>
>
> \</Request\>
>
> \</Trans\>
>
> Activating a couple of users:
>
> \<Trans actor="root"\>
>
> \<Request object="User" action="Modify"\>
>
> \<Set name="Active" value="true"/\>
>
> \<Where name="Name" value="scott"/\>
>
> \<Where name="Name" value="brett" conj="or"/\>
>
> \</Request\>

\</Trans\>

> Submitting a simple job:

\<Trans\>

> \<Request object="Job" action="Submit"\>
>
> \<Data type="xml"\>
>
> \<Job\>
>
> \<User\>xdp\</User\>
>
> \<Account\>youraccount\</Account\>
>
> \<Command\>myprogram\</Command\>
>
> \<Cwd\>/usr/home/scl/xdp\</Cwd\>
>
> \<RequestedNodes\>4\</RequestedNodes\>
>
> \<RequestedWCTime\>100\</RequestedWCTime\>
>
> \</Job\>
>
> \</Data\>
>
> \</Request\>

\</Trans\>

### Sample Responses

> A response to the available memory nodes query (batch format)
>
> \<Reply count="1"\>
>
> \<Response object="node" action="query" id="1"\>
>
> \<Status\>true\</Status\>
>
> \<Code\>000\</Code\>
>
> \<Count\>2\</Count\>
>
> \<Data name="NodeList" type="xml"\>
>
> \<Node\>
>
> \<Name\>fr01n01\</Name\>
>
> \<ConfiguredMemory\>512\</ConfiguredMemory\>
>
> \</Node\>
>
> \<Node\>
>
> \<Name\>fr12n04\</Name\>
>
> \<ConfiguredMemory\>1024\</ConfiguredMemory\>
>
> \</Node\>
>
> \</Data\>
>
> \</Response\>

\</Reply\>

Two users successfully activated

\<Reply\>

> \<Response\>
>
> \<Status\>true\</Status\>
>
> \<Code\>000\</Code\>
>
> \<Count\>2\</Count\>
>
> \<Message\>Two users were successfully modified\</Message\>
>
> \</Response\>
>
> \</Reply\>
>
> A failed job submission:
>
> \<Reply\>
>
> \<Response\>
>
> \<Status\>false\</Status\>
>
> \<Code\>711\</Code\>

\<Message\>Invalid account specified. The job was not
submitted.\</Message\>

> \</Response\>

\</Reply\>

### Sample Notification

> A change in available memory triggers a notification:

\<Message\>

> \<Notify name="AvailableMemory" value="952" id="47327"/\>

\</Message\>

### Sample Acknowledgement

> An event subscriber acknowledges receipt of the notification
>
> \<Reply\>
>
> \<Ack id="47327"/\>

\</Reply\>

# Error Reporting

SSSRMAP requests will return a status and a 3-digit response code to
signify success or failure conditions. When a *request* is successful, a
corresponding *response* is returned with the *status* element set to
true and the *code* element set to "000". When a *request* results in an
error detected by the server, a *response* is returned with the *status*
element set to false and a 3-digit error code in the *code* element. An
optional human-readable *message* may also be include in a failure
response providing context-specific detail about the failure. The
default message language is US English. (The status flag makes it easy
to signal success or failure and allows the receiving peer some freedom
in the amount of parsing it wants to do on failure \[BXXP\]).

Category Code Response Message in US English

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Success 000 Request completed successfully

Unknown Failure 999 Request failed

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

1xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Protocol Syntax 2xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Object Management 3xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Authentication Error 4xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Connection Problem 5xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Server Side Failure 6xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Client Side Failure 7xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

Business Logic 8xx

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--+\-\-\-\-\-\--+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--

# Transport Layer

> This protocol will be built over the connection-oriented reliable
> transport layer TCP/IP. Support for other transport layers could also
> be considered, but native support for TCP/IP can be found on most
> terascale clusters and automatically handles issues such as
> reliability and connectionfullness for the application developer
> implementing the SSSRMAP protocol.

# Framing

> Framing specifies how the beginning and ending of each message is
> delimited. Given that the encoding will be expressed as one or more
> XML documents, clients and servers need to know when an XML document
> has been fully read in order to be parsed and acted upon.
>
> SSSRMAP will use the HTTP 1.1 \[HTTP\] protocol for framing. HTTP uses
> a byte-counting mechanism to delimit the message body. HTTP chunking
> can be used to delimit batched messages and for persistent
> connections.

## Message Header Requirements

> The HTTP request line (first line of the HTTP request header) begins
> with POST and is followed by a URI and the version of the HTTP
> protocol that the client understands. It is suggested for this
> protocol that the URI consist of a single slash, followed by the
> protocol name in uppercase (i.e. /SSSRMAP), though this field is not
> specified and could be empty, a single slash or any URI.
>
> The Content-Type must be specified as test/xml. Charset may be
> optionally specified and defaults to US-ASCII. It is recommended that
> charset be specified as "utf-8" for maximum interoperability.
>
> The Content-Length must be specified and must be correct for the
> payload.
>
> Other properties such as User-Agent, Host and Date are strictly
> optional.

## Message Payload Format

> The message payload is in XML and consists of a single XML document
> having a root element of *Trans*.

## Reply Header Requirements

> The HTTP response line (first line of the HTTP response header) begins
> with HTTP and a version number, followed by a numeric code and a
> message indicating what sort of response is made. These response codes
> and messages indicate the status of the entire response and are as
> defined by the HTTP standard. The most common response is 200 OK,
> indicating that the message was received and an appropriate response
> is being returned.
>
> The Content-Type must be specified as test/xml. Charset may be
> optionally specified and defaults to US-ASCII. It is recommended that
> charset be specified as "utf-8" for maximum interoperability.
>
> The Content-Length must be specified and must be correct for the
> payload.
>
> For HTTP 1.1, the Connection should be specified as close if a
> persistent connection is not required.
>
> Other properties such as Server, Host and Date are strictly optional.

## Reply Payload Format

> The reply payload is in XML and consists of a single XML document
> having a root element of *Reply*.

## Examples

### Sample SSSRMAP Message Embedded in HTTP Request

> POST /SSSRMAP HTTP/1.1
>
> Content-Type: text/xml; charset="utf-8"
>
> Content-Length: 321

\<Trans .../\>

### Sample SSSRMAP Reply Embedded in HTTP Response

> HTTP/1.1 200 OK
>
> Connection: close
>
> Content-Type: text/xml; charset="utf-8"
>
> Content-Length: 456
>
> \<Reply .../\>

# Asynchrony

> Asynchrony (or multiplexing) allows for the handling of independent
> exchanges over the same connection. A widely-implemented approach is
> to allow pipelining (or boxcarring) by aggregating requests or
> responses within the body of the message or via persistent connections
> and chunking in HTTP 1.1. Pipelining helps reduce network latency by
> allowing a client to make multiple requests of a server, but requires
> the requests to be processed serially \[RFC3117\]. Parallelism could
> be employed to further reduce server latency by allowing multiple
> requests to be processed in parallel by multi-threaded applications.
>
> Segmentation may become necessary if the messages are larger than the
> available window. With support for segmentation, the octet-counting
> requirement that you need to know the length of the whole message
> before sending it can be relaxed -- and you can start sending segments
> before the whole message is available. Segmentation is facilitated via
> "chunking" in HTTP 1.1.
>
> The current SSSRMAP strategy supports pipelining of requests and
> responses in batches contained within the *Message* and *Reply*
> elements. Later versions of the protocol could introduce parallelism
> such as that found in the BEEP protocol \[BEEP\] which allows
> independent parallel exchanges via multiple channels.

# Security

> SSSRMAP security features include capabilities for integrity,
> authentication, confidentiality, and non-repudiation. The absence or
> presence of the various security features depend upon the type of
> security token used and the protection methods you choose to specify
> in the request.
>
> For compatibility reasons, SSSRMAP specifies six supported security
> token types. Extensibility features are included allowing an
> implementation to use alternate security algorithms and security
> tokens. It is also possible for an implementation to ignore security
> features if it is deemed nonessential for the component. However, it
> is highly RECOMMENDED that an implementation support at least the
> default security token type in both authentication and encryption.

## Security Token

> A security token may be included in either the Signature block, and/or
> in the EncryptedData block (both described later) as an implicit or
> explicit cryptographic key.

### Security Token Element

> This element is of type String. If the security token conveys an
> explicit key, this element's content is the value of the key. If the
> key is natively expressed in a binary form, it must be converted to
> base64 encoding as defined in XML Digital Signatures
> ("http://www.w3.org/2000/09/xmldsig#base64"). If the type is not
> specified, it is assumed to be of type "Symmetric".
>
> It may have any of the following optional attributes:

-   *type* -- the type of security token (described subsequently)

    -   A *type* attribute of "Symmetric" specifies a shared secret key
        between the client and server. This is the default.

    -   A *type* attribute of "Asymmetric" specifies the use of public
        private key pairs between the client and server.

    -   A *type* attribute of "Password" encrypts and authenticates with
        a user password known to both the client and server.

    -   A *type* attribute of "Cleartext" allows the passing of a
        cleartext username and password and depends on the use of a
        secure transport (such as SSL or IPSec).

    -   A *type* attribute of "Kerberos5" specifies a kerberos token.

    -   A *type* attribute of "X509v3" specifies an X.509 certificate.

-   *name* -- the name of the security token which serves as an
    identifier for the actor making the request (useful when the key is
    a password, or when the key value is implicit as when a public key
    is named but not included)

> Schema Definition:
>
> \<complexType name=\"SecurityTokenType\" mixed="true"\>
>
> \<attribute name=\"type\" type=\"string\" use=\"optional\"/\>
>
> \<attribute name=\"name\" type=\"string\" use=\"optional\"/\>
>
> \</complexType\>
>
> \<element name="SecurityToken\" type=\"sssrmap:SecurityTokenType\"/\>

### Security Token Types

> SSSRMAP defines six standard security token types:

#### Symmetric Key

> The default security token specifies the use of a shared secret key.
> The secret key is up to 128-bits long and known by both client and
> server. When using a symmetric key as a security token, it is not
> necessary to specify the *type* attribute with value "Symmetric"
> because this is assumed when the attribute is absent. The *name*
> attribute should be specified indicating the actor issuing the
> request. If the user provides a password to be sent to the server for
> authentication, then the password is encrypted with the secret key
> using a default method="rsa-1_5" (XML ENCRYPTION
> <http://www.w3.org/2001/04/xmlenc#rsa-1_5>), base64 encoded and
> included as the string content of the *SecurityToken* element. If the
> client authenticated the user, then the *SecurityToken* element is
> empty .The same symmetric key is used in both authentication and
> encryption.

#### Asymmetric Key

> Public and private key pairs can be used to provide non-repudiation of
> the client (or server). The client and the server must each have their
> own asymmetric key pairs. This mode is indicated by specifying the
> *type* attribute as "Asymmetric". The *name* attribute should be
> specified indicating the actor issuing the request. If the user
> provides a password to be sent to the server for authentication, then
> the password is encrypted with the server's public key using a default
> method="rsa-1_5" (XML ENCRYPTION
> <http://www.w3.org/2001/04/xmlenc#rsa-1_5>), base64 encoded and
> included as the string content of the *SecurityToken* element. If the
> client authenticated the user, then the *SecurityToken* element is
> empty .The sender's private key is used in authentication (signing)
> while the recipient's public key is used for encryption.

#### Password

> This mode allows for a username password combination to be used under
> the assumption that the server also knows the password for the user.
> This security token type is indicated by specifying a value of
> "Password" for the *type* attribute. The password itself is used as
> the cryptographic key for authentication and encryption. The *name*
> attribute contains the user name of the actor making the request. The
> *SecurityToken* element itself is empty.

#### Cleartext

> This security mode is equivalent to passing the username and password
> in the clear and depends upon the use of a secure transport (such as
> SSL or IPSec). The purpose of including this security token type is to
> enable authentication to occur from web browsers over SSL or over
> internal LANs who use IPSec to encrypt all traffic. The password (or a
> hash of the password like in /etc/passwd) would have to be known by
> the server for authentication to occur. In this mode, neither
> encryption or signing of the hash is performed at the application
> layer. This mode is indicated by specifying a value of "Cleartext" for
> the *type* attribute. The *name* attribute contains the user name of
> the actor making the request and the string content of the
> *SecurityToken* element is the unencrypted plaintext password.

#### Kerberos

> The use of a Kerberos version 5 token is indicated by specifying
> "Kerberos5" in the *type* attribute. The *name* attribute is used to
> contain the kerberos user id of the actor making the request. The
> *SecurityToken* element contains two subelements. The *Authenticator*
> element contains the authenticator encoded in base64. A *Ticket*
> element contains the service-granting ticket, also base64 encoded.

#### GSI (X.509)

> The Grid Security Infrastructure (GSI) which is based on public key
> encryption, X.509 certificates, and the Secure Sockets Layer (SSL)
> communication protocol can be indicated by specifying a *type*
> attribute of "X509v3". The name attribute contains the userid used
> that the actor was mapped to in the local system. The string content
> of the *SecurityToken* element is the GSI authentication message
> including the X.509 identity of the sender encoded in base64.

### Example

> \<SecurityToken type="Asymmetric" name="scottmo"\>

MIIEZzCCA9CggAwIBAgIQEmtJZc0rqrKh5i\...

\</SecurityToken\>

## Authentication

> Authentication entails how the peers at each end of the connection are
> identified and verified. Authentication is optional in an SSSRMAP
> message or reply. SSSRMAP uses a digital signature scheme for
> authentication that borrows from concepts in XML Digital Signatures
> \[XML_DSIG\]. In addition to authentication, the use of digital
> signatures also ensures integrity of the message, protecting exchanges
> from third-party modification.
>
> When authentication is used, a *Signature* element is prepended as the
> first element within the *Trans* (or *Reply*) element. All of the
> security modes will create a digest of the data for integrity checking
> and store this in base64 encoding in a *DigestValue* element as a
> child of the *Signature* element. The digital signature is created by
> encrypting the hash with the appropriate security token and storing
> this value in a *SignatureValue* element as a child of the *Signature*
> element. The security token itself is included as a child of the
> *Security* element within a *SecurityToken* element.
>
> There are a number of procedural practices that must be followed in
> order to standardize this approach. The digest (or hash) is created
> over the contents of the *Trans* or *Reply* element (not including the
> Trans or Reply tags or their attributes). This might be over one or
> more *Request* or *Notify* elements (or *Response* or *Ack* elements)
> and necessarily excludes the *Signature* Element itself. (Note that
> any data encryption is performed after the creation of the digital
> signature and any decryption is performed before authenticating so the
> *EncryptedData* element will not interfere with this process. Hence,
> the signature is always based on the (hashed but) unencrypted data).
> For the purposes of generating the digest over the same value, it is
> assumed that the data is first canonicalized to remove extraneous
> whitespace, comments, etc according to the XML Digital Signature
> algorithm ("http://www.w3.org/TR/2001/REC-xml-c14n-20010315") and a
> transform is applied to remove namespace information. As a rule, any
> binary values are always transformed into their base64 encoded values
> when represented in XML.

### The *Signature* Element

> The *Signature* element MUST be included as the first child element in
> the *Trans* or *Reply* elements if SSSRMAP authentication is required.
> It MUST contain a *DigestValue* element that is used for integrity
> checking. It MUST also contain a *SecurityToken* element that is used
> to indicate the security mode and token type, and to verify the
> signature. It MUST contain a SignatureValue element that contains the
> base64 encrypted value of the signature wrought on the hash UNLESS the
> security token type indicates Cleartext mode where a signature would
> be of no value with the encryption key being sent in the clear \-- in
> this case we use the password itself for authentication).
>
> Schema Definition:
>
> \<complexType name=\"SignatureType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"1\"\>
>
> \<element ref=\"sssrmap:DigestValue\" minOccurs=\"1\"
> maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:SignatureValue\" minOccurs=\"1\"
> maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:SecurityToken\" minOccurs=\"0\"
> maxOccurs=\"1\"/\>
>
> \</choice\>
>
> \</complexType\>
>
> \<element name=\"Signature\" type=\"sssrmap:SignatureType\"/\>

### The *DigestValue* Element

> The *DigestValue* element contains the cryptographic digest of the
> transmission or reply data. As described above, the hash is generated
> over all children of the *Trans* or *Reply* element, excluding the
> *Signature* element and its children. The data to be hashed must first
> be canonicalized and appropriately transformed before generating the
> digest since typically an application will read in the XML document
> into an internal binary form, then marshal (or serialize) the data
> into a string which is passed as input to the hash algorithm.
> Different implementations marshal the data differently so it is
> necessary to convert this to a well-defined format before generating
> the digest or the clients will generate different digest values for
> the same XML. The SHA-1 \[SHA-1\] message digest algorithm
> (http://www.w3.org/2000/09/xmldsig#sha1) SHALL be used as the default
> method for generating the digest. A *method* attribute is defined as
> an extensibility option in case an implementation wants to be able to
> specify alternate message digest algorithms.
>
> It MAY have a method attribute:

-   *method* -- the message digest algorithm.

    -   A *method* attribute of "sha1" specifies the SHA-1 message
        digest algorithm. This is the default and is implied if this
        attribute is omitted.

> Schema Definition:
>
> \<complexType name=\"DigestValueType\"\>
>
> \<attribute name=\"method\" type=\"string\" use=\"optional\"/\>

\</complexType\>

> \<element name=\"DigestValue\" type=\"sssrmap:DigestValueType\"/\>

### The *SignatureValue* Element

> The SignatureValue element contains the digital signature that serves
> the authentication (and potentially non-repudiation) function. The
> string content of the SignatureValue element is a base64 encoding of
> the encrypted digest value. The HMAC algorithm \[HMAC\] based on the
> SHA1 message digest (http://www.w3.org/2000/09/xmldsig#hmac-sha1)
> SHALL be used as the default message authentication code algorithm for
> user identification and message integrity. A *method* attribute is
> defined as an extensibility option in case an implementation wants to
> be able to specify alternate digital signature algorithms.
>
> It MAY have a method attribute:

-   *method* -- the digest signature algorithm.

    -   A *method* attribute of "hmac-sha1" specifies the HMAC SHA-1
        digital signature algorithm. This is the default and is implied
        if this attribute is omitted.

> Schema Definition:
>
> \<complexType name=\"SignatureValueType\"\>
>
> \<attribute name=\"method\" type=\"string\" use=\"optional\"/\>

\</complexType\>

> \<element name=\"SignatureValue\"
> type=\"sssrmap:SignatureValueType\"/\>

### Signature Example

> Pre-authentication:
>
> \<Trans\>
>
> \<Request object="User" action="Query"\>
>
> \<Get name="EmailAddress" /\>
>
> \<Where name="scottmo" /\>
>
> \</Request\>
>
> \</Trans\>
>
> Post-authentication:
>
> \<Trans\>
>
> \<Signature\>
>
> \<DigestValue\>
>
> LyLsF0Pi4wPU\...
>
> \</DigestValue\>
>
> \<SignatureValue\>
>
> DJbchm5gK\...
>
> \</SignatureValue\>
>
> \<SecurityToken type="Asymmetric" name="kenneth"\>

MIIEZzCCA9CggAwIBAgIQEmtJZc0rqrKh5i\...

> \</SecurityToken\>
>
> \</Signature\>
>
> \<Request object="User" action="Query"\>
>
> \<Get name="EmailAddress" /\>
>
> \<Where name="scottmo" /\>
>
> \</Request\>
>
> \</Trans\>

## Confidentiality

Confidentiality involves encrypting the sensitive data in the message,
protecting exchanges against third-party interception and modification.
Confidentiality is optional in an SSSRMAP message or reply. When
confidentiality is required, SSSRMAP sessions use block cipher
encryption with concepts borrowed from the emerging XML Encryption
\[XML_ENC\] standard.

> When confidentiality is used, encryption is performed over all child
> elements of the *Trans* or *Message* elements, i.e. on the data as
> well as any signature (The encrypted data is not signed \-- rather the
> signature is encrypted). This data is replaced in-place within the
> transmission or reply with an *EncryptedData* element. The data is
> first compressed using the gzip algorithm \[ZIP\]. Instead of
> encrypting this compressed data with the security token directly, a
> 128-bit random session key is generated by the sender and used to
> perform symmetric encryption on the compressed data. This key is
> itself encrypted with the security token and included with the
> encrypted data as the value of the *EncryptedKey* element as a child
> of the *EncryptedData* element. The ciphertext resulting from the data
> being encrypted with the session key is passed as the value of a
> *CipherValue* element (also a child of the *EncryptedData* element).
> As in the case with authentication, the security token itself is
> included as a child of the *Security* element within a *SecurityToken*
> element.

### The *EncryptedData* Element

> When SSSRMAP confidentiality is required, the *EncryptedData* element
> MUST appear as the only child element in the *Trans* or *Reply*
> elements. It directly replaces the contents of these elements
> including the data and any digital signature. It MUST contain an
> *EncryptedKey* element that is used to encrypt the data. It MUST
> contain a *CipherValue* element that holds the base64 encoded
> ciphertext. It MUST also contain a *SecurityToken* element that is
> used to indicate the security mode and token type, and to verify the
> signature. Confidentiality is not used when a security token type of
> "Cleartext" is specified since it would be pointless to encrypt the
> data with the encryption key in the clear.
>
> Schema Definition:
>
> \<complexType name=\"EncryptionDataType\"\>
>
> \<choice minOccurs=\"0\" maxOccurs=\"1\"\>
>
> \<element ref=\"sssrmap:EncryptedKey\" minOccurs=\"1\"
> maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:CipherValue\" minOccurs=\"1\"
> maxOccurs=\"1\"/\>
>
> \<element ref=\"sssrmap:SecurityToken\" minOccurs=\"1\"
> maxOccurs=\"1\"/\>
>
> \</choice\>
>
> \</complexType\>
>
> \<element name=\"EncryptedData\" type=\"sssrmap:EncryptedDataType\"/\>

### The *EncryptedKey* Element

> The *EncryptedKey* element is a random session key encrypted with the
> security token. This approach is used for a couple of reasons. In the
> case where public key encryption is used, asymmetric encryption is
> much slower than symmetric encryption and it makes sense to use a
> symmetric key for encryption and pass along it along by encrypting it
> with the recipient's public key. It is also useful in that the
> security token which does not change very often (compared to the
> session key which changes for every connection) is used on a very
> small sampling of data (the session key), whereas if it was used to
> encrypt the whole message an attacker could more effectively exploit
> an attack against the ciphertext. The RSA stream cipher algorithm
> SHALL be used as the default method for encryption. This algorithm is
> specified by the XML Encryption \[XML_ENC\] URI
> "http://www.w3.org/2001/04/xmlenc#rsa-1_5". The session key is
> encrypted using the security token, base64 encoded and specified as
> the string content of the *EncryptedKey* element. A *method* attribute
> is defined as an extensibility option in case an implementation wants
> to be able to specify alternate key encryption algorithms.
>
> It is REQUIRED that an implementation use a cryptographically security
> Pseudo-Random number generator. It is RECOMMENDED that the session key
> be cryptographically generated (such as cyclic encryption, DES OFB,
> ANSI X9.17 PRNG, or ANSI X12.17 (used by PGP)).
>
> It MAY have a method attribute:

-   *method* -- the key encryption algorithm.

    -   A *method* attribute of "rsa-1_5" specifies the RSA stream
        encryption algorithm. This is the default and is implied if this
        attribute is omitted.

> Schema Definition:

\<complexType name=\"EncryptedKeyType\"\>

> \<attribute name=\"method\" type=\"string\" use=\"optional\"/\>

\</complexType\>

> \<element name=\"EncryptedKey\" type=\"sssrmap:EncryptedKeyType\"/\>

### The *CipherValue* Element

> The CipherValue element contains the message (and possibly signature)
> data encrypted with the random session key. The ciphertext is
> compressed using the gzip algorithm \[ZIP\], base64 encoded and
> included as the string content of the CipherValue element. The AES-128
> (Advanced Encryption Standard with a 128 bit shared secret symmetric
> encryption key) with cipher block chaining feedback mode SHALL be used
> as the default method for encryption. This algorithm is specified by
> the XML Encryption \[XML_ENC\] URI identifier
> "http://www.w3.org/2001/04/xmlenc#aes128-cbc". A *method* attribute is
> defined as an extensibility option in case an implementation wants to
> be able to specify alternate data encryption algorithms.
>
> It MAY have a method attribute:

-   *method* -- the data encryption algorithm.

    -   A *method* attribute of "aes128-cbc" specifies the AES
        encryption algorithm with a 128-bit key and CBC feedback mode.
        This is the default and is implied if this attribute is omitted.

> Schema Definition:
>
> \<complexType name=\"CipherValueType\"\>
>
> \<attribute name=\"method\" type=\"string\" use=\"optional\"/\>

\</complexType\>

> \<element name=\"CipherValue\" type=\"sssrmap:CipherValueType\"/\>

### Encryption Example

> In this example, a simple request is demonstrated without a digital
> signature for the sake of emphasizing the encryption plaintext
> replacement.
>
> Pre-encryption:
>
> \<Reply\>
>
> \<Response\>
>
> \<Status\>true\</Status\>
>
> \<Code\>000\</Code\>
>
> \<Count\>1\</Count\>
>
> \<Data\>
>
> \<User\>
>
> \<EmailAddress\>Scott.Jackson@pnl.gov\</EmailAddress\>
>
> \</User\>
>
> \</Data\>
>
> \</Response\>

\</Reply\>

Post-encryption:

> \<Reply\>
>
> \<EncryptedData\>
>
> \<EncryptedKey\>
>
> NAkE9iQofYhyOfiHZ29kkEFVJ30CAwEAAaMSM\...
>
> \</EncryptedKey\>
>
> \<CipherValue\>
>
> mPCadVfOMx1NzDaKMHNgFkR9upTW4kgBxyPW\...

\</CipherValue\>

> \<SecurityToken type="Asymmetric" name="kenneth"\>

MIIEZzCCA9CggAwIBAgIQEmtJZc0rqrKh5i\...

> \</SecurityToken\>
>
> \</EncryptedData\>

\</Reply\>

# Acknowledgements

# References

\[RFC2119\] S. Bradner, "Key Words for Use in RFCs to Indicate
Requirement Levels", [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt),
March 1997.

\[BEEP\] M. Rose, "The Blocks Extensible Exchange Protocol Core", [RFC
3080](http://www.ietf.org/rfc/rfc3080.txt), March 2001.

\[HMAC\] H. Krawczyk, M. Bellare, R. Canetti, "HMAC, Keyed-Hashing for
Message Authentication", [RFC
2104](http://www.ietf.org/rfc/rfc2104.txt), February 1997.

\[SHA-1\] U.S. Department of Commerce/National Institute of Standards
and Technology, "[Secure Hash
Standard](http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt)",
FIPS PUB 180-1.

\[SSS\] "Scalable Systems Software",
<http://www.scidac.org/ScalableSystems>

\[HTTP\] "Hypertext Transfer Protocol -- HTTP/1.1", [RFC
2616](http://www.w3.org/Protocols/rfc2616/rfc2616.txt), June 1999.

\[XML_CONV\] "[I-X and \<I-N-CA\> XML
Conventions](http://www.aiai.ed.uk/project/ix/inca/xml-conventions.html)".

\[FED_XML\] "[U.S. Federal XML
Guidelines](http://www.xml.com/pub/a/2002/02/06/fedguidelines.html)".

\[RFC3117\] M. Rose, "On the Design of Application Protocols",
[Informational RFC 3117](http://www.faqs.org/rfcs/rfc3117.html),
November 2001.

\[XML_DSIG\] D. Eastlake, J. Reagle Jr., D. Solo, "[XML Signature Syntax
and Processing](http://www.w3.org/TR/xmldsig-core/)", W3C
Recommendation, 12 February 2002.

\[XML_ENC\] T. Imamura, B. Dillaway, E. Smon, "[XML Encryption Syntax
and Processing](http://www.w3.org/TR/xmlenc-core/)", W3C Candidate
Recommendation, 4 March 2002.

\[XRP\] E. Brunner-Williams, A. Damaraju, N. Zhang, "[Extensible
Registry Protocol
(XRP)",](http://www.icann.org/tlds/agreements/biz/draft-brunner-xrp-00.txt)
Internet Draft, expired August 2001.

\[XML\] Bray, T., et al, "[Extensible Markup Language (XML) 1.0 (Second
Edition](http://www.w3.org/TR/2000/REC-xml-20001006))", 6 October 2000.

\[XML_SCHEMA\] D. Beech, M. Maloney, N. Mendelshohn, "[XML Schema Part
1: Structures Working
Draft",](http://www.w3.org/TR/2000/WD-xmlschema-1-20000407) April 2000.

\[ZIP\] J. Gailly, M. Adler, "The gzip home page",
<http://www.gzip.org/>