IBM Security Directory Suite Directory Services Markup Language (DSML)

Content

Introduction

In today's e-business environment, effective and efficient data management is crucial. As such, two technologies prove vital to proper data management: directory services and XML. Directory services allow you to store and manage data, and are thus a necessary prerequisite for conducting online business. XML provides an effective way to present and transfer data. With that in mind, there's a clear need to bridge the two technologies. The solution may be the new Directory Service Markup Language (DSML) standard, designed to make directory services more dynamic by employing XML.

The IBM^(R)Security Directory Suite DSML is Directory Server Markup Language v2.0 implementation. It makes Lightweight Directory Access Protocol (LDAP) directory services available to XML-based applications, cell phones, and PDAs.

The Directory Services Markup Language v1.0 (DSMLv1) provides a means for representing directory structural information as an XML document.

DSMLv2 goes further, providing a method for expressing directory queries and updates (and the results of these operations) as XML documents. DSMLv2 documents can be used in a variety of ways. For instance, they can be written to files in order to be consumed and produced by programs, or they can be transported over HTTP to and from a server that interprets and generates them.

DSMLv2 functionality is motivated by scenarios including:

• A smart cell phone or PDA needs to access directory information but does not contain an LDAP client.
• A program needs to access a directory through a firewall, but the firewall is not allowed to pass LDAP protocol traffic because it isn't capable of auditing such traffic.
• A programmer is writing an application using XML programming tools and techniques, and the application needs to access a directory.

In short, DSMLv2 is needed to extend the reach of directories.

DSMLv2 is not required to be a strict superset of DSMLv1, which was not designed for upward-compatible extension to meet new requirements. However it is desirable for DSMLv2 to follow the design of DSMLv1 where possible.

To download and DSML, complete the following steps:

1. Log on to the IBM Security Directory Suite virtual appliance console. See Logging on to the virtual appliance console.
2. Use the Custom File Management page to download the DSML.zip file, which is under the idstools folder. See Managing custom files.

For a description of the contents of the DSML.zip file and installation instructions, see the file, DSMLReadme.txt file that is attached at the end of this technical note.

---

Design Approach

DSMLv2 focuses on extending the reach of LDAP directories. Therefore, as in DSMLv1, the design approach is not to abstract the capabilities of LDAP directories as they exist today, but instead to faithfully represent LDAP directories in XML. The difference is that DSMLv1 represented the state of a directory while DSMLv2 represents the operations that an LDAP directory can perform and the results of such operations.

Therefore the design approach for DSMLv2 is to express LDAP requests and responses as XML document fragments. For the most part DSMLv2 is a systematic translation of LDAP's ASN.1 grammar (defined by RFC 2251) into XML-Schema. Thus, when a DSMLv2 element name matches an identifier in LDAP's ASN.1 grammar, the named element means the same thing in DSMLv2 and in LDAP. Except where noted otherwise, the DSMLv2 grammar follows the same rules as the LDAP grammar, even if those rules are not explicitly expressed in the DSMLv2 schema - for example, a DSMLv2 AttributeDescription can contain only those characters allowed by LDAP.

DSMLv2 is defined in terms of a set of XML fragments that are used as payloads in a binding. A binding defines how the DSMLv2 XML fragments are sent as requests and responses in the context of a specific transport such as SOAP, SMTP, or a simple data file.

DSMLv2 defines two normative bindings: 1) a SOAP request/response binding is defined in section E.1; and 2) a file binding that serves as the DSMLv2 analog of LDIF is defined in section E.2.

The simple correspondence between LDAP and DSMLv2 has compelling advantages. However there are a few places where it makes sense for DSMLv2 to diverge from LDAP:

1. An LDAP application associates a security principal with an LDAP connection by issuing a Bind request - or, in the SASL Bind case, by issuing as many successive Bind requests as needed to complete the authentication. A DSMLv2 document can be transported via a variety of mechanisms, so the document itself is not used to authenticate the requestor. DSMLv2 includes an Auth request that MAY be used to associate a security principal with a collection of DSMLv2 operations.
2. LDAP does not include a method of grouping operations to be expressed in a single request. DSMLv2 allows multiple LDAP operations to be expressed in one request document, and by specifying a simple positional correspondence between individual requests within a request document and individual responses within a response document. This change is explained in Section 4 below.
3. In LDAP, a single search request typically generates multiple responses, closed by a searchResultDone response. To enable the positional correspondence between requests and responses mentioned above, DSMLv2 provides for a binding to wrap the complete set of related search responses into a single searchResponse element containing the individual LDAP responses to a search request.
4. The systematic translation of RFC 2251 results in a redundant level of nested element, the LDAPMessage. DSMLv2 eliminates this extra level.
5. Defaulting works more naturally in XML documents than in ASN.1 structures, so DSMLv2 uses defaulting in a few places where LDAP doesn't. In DSMLv2 the string-valued elements matchedDN and errorMessage (from LDAPResult in LDAP) and attributes (from SearchRequest in LDAP) are optional, and when absent are treated as the empty string. The sizeLimit, timeLimit, and typesOnly elements (from SearchRequest in LDAP) default to 0, 0, and FALSE respectively.

In the following the term provider is used to refer to that element of the client that implements a binding on behalf of the client. Certain error conditions MAY be detected by the provider without any necessary interaction with a server.

Also note that the term server is used loosely -- clients and programs (not servers) might also perform DSMLv2-based interactions, e.g. in which the client provides a file holding a document as input and the program produces a file containing a document as output. It is clumsy to say "program or server" throughout the document, so we say "server".

---

Architectural Relationship Between DSML server and LDAP Server

---

SOAP binding

With SOAP binding, the DSMLv2 "server" is a servlet in Servlet/JSP engine in the application server. The client (a user application) generates the DSML request and send the request to the DSMLv2 server (the servlet) through HTTP/HTTPS. The DSML server is responsible to parse the HTTP request to retrieve the DSML request, transform the DSML request to JNDI request and send the request to LDAP server using JNDI. After the DSML server receives the response from the LDAP server, the DSML server transform the JNDI response to DSML response and send back the response to the client who generated the DSML request.

---

File binding

With the file binding, the DSMLv2 "server" is a command-line program, as is typical for LDIF. The client that invokes the "server" program runs on the same computer as the server, and the input and output of the server are files consisting of DSMLv2 documents. The DSMLv2 server uses LDAP to communicate with the LDAP server.

---

DSMLv2 URN

The base URN for DSMLv2 is:

urn:oasis:names:tc:DSML:2:0:core

The above URN is used to construct the URN for the core namespace consisting of the individual operations and responses, a request envelope, a response envelope and an envelope grouping the entries, references and result of a search operation.

Example of using the DSMLv2 URN:

<dsml:batchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">

---

Top-Level Structure

There are two types of DSMLv2 document: the request document and the response document. In a DSMLv2-based interaction between a client and a server there is a pairing of requests and responses: For each request document submitted by the client there is one response document produced by the server. The structure of the request and response documents depends on the specification of a binding of DSMLv2 to some underlying protocol.

In the two bindings defined in this specification, the top-level element of a request fragment is a BatchRequest and the top-level element of a response fragment is a BatchResponse.

A BatchRequest contains zero, one, or many individual request elements, while a BatchResponse consists of zero, one or many individual response elements. A BatchRequest containing zero request elements is a valid request; the valid response is a BatchResponse containing zero response elements. Such a batch request-response pair can be used to verify that a server is capable of processing DSMLv2 documents.

---

Request and Response Association

The client and server associate an individual response in a BatchResponse with the corresponding individual request in a BatchRequest using one (or both) of the following methods: positional correspondence or RequestID.

In a positional correspondence, the n^th response element corresponds to the n^th request element. For instance, if the third response element is a delete response, then it corresponds to the third request element, a delete request.

When using positional correspondence, a valid batch request-response pair can have fewer responses in the response document than requests in the request document. This can happen due to a syntax error in the request document or due to a failure while processing a request (more on these conditions below). The correspondence stated above still holds: The n^th response element corresponds to the n^th request element.

Here is an example of a valid batch request-response pair using positional correspondence:

DSMLv2 Request Document:

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>

<delRequest>...</delRequest>
<addRequest>...</addRequest>

</batchRequest>

DSMLv2 Response Document:

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">

<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>

<delResponse>...</delResponse>
<addResponse>...</addResponse>

<addResponse>...</addResponse>

</batchResponse>

The alternative to positional correspondence is the use of the optional requestID attribute. When the client specifies a value for requestID in a request (for example, in an addRequest), the server MUST return the same value in the corresponding response (for example, in an addResponse). The client need not specify a requestID when positional correspondence is also used, although in some cases it may find this useful. For example, when using the file binding for a large file, some clients may find it more convenient to associate failed responses with requests using requestID rather than position.

In bindings (such as those described in this document) where the server generates a SearchResponse for a SearchRequest, the server MUST associate the requestID with the SearchResponse, not with its child elements.

Future bindings MAY also use the requestID attribute to identify unsolicited notifications. A client MUST NOT send a request with requestID="0", as this value is reserved for unsolicited notifications.

A BatchRequest element may contain the optional XML-attribute responseOrder, which influences how the server orders individual responses within the BatchResponse. The valid values are ordered and unordered. If this attribute is omitted, the default value is ordered.

In a BatchRequest with responseOrder="ordered", the server MUST return a BatchResponse in which the individual responses maintain a positional correspondence with the individual requests.

The behavior when responseOrder="unordered" is described below in the Parallel Processing section.

---

Syntax Errors

A client may produce a request document that is syntactically incorrect, i.e. does not conform to the XML-Schema for a top-level XML fragment as defined above. In this case the DSMLv2 provider produces a response document to aid in debugging the client. If the server detects the syntax error before performing any directory operations on behalf of the client, the response has the form:

DSMLv2 Response - Syntax error in request:

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<errorResponse type="malformedRequest">
 <message>Unknown element 'bogusRequest'  line 87 column 4</message>
</errorResponse>
</batchResponse>

The errorResponse element contains details about the error.

If the server performs one or more directory operations on behalf of the client before detecting the syntax error, the server's response contains the response element for each operation that it performed, followed by an errorResponse element. For instance:

DSMLv2 Request containing syntax error:

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<bogusRequest>...</bogusRequest>
<addRequest>...</addRequest>
...
</batchRequest>

DSMLv2 Response Document - Syntax error in request:

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>
<errorResponse type="malformedRequest">
 <message>Unknown element 'bogusRequest'  line 87 column 4</message>
</errorResponse>
</batchResponse>

---

Failures

A client may produce a request document that is syntactically correct but that contains a request that fails when the provider executes it. Failure is defined as follows:

• The DSMLv2 provider was unable to connect to a server (represented as an errorResponse with type="couldNotConnect").
• The DSMLv2 provider connected to a server, but the server closed the connection without responding to the request (represented as an errorResponse with type="connectionClosed").
• The server returned an LDAPResultCode other than 0 ("success"), 6 ("compareTrue"), 5 ("compareFalse"), or 10 ("referral").

When a request execution fails, the server does not attempt to execute later requests within the document. The server produces a response element for each request element that was attempted, including the one that failed.

DSMLv2 Request containing a request that fails

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<delRequest>...</delRequest>
<addRequest>...</addRequest>
</batchRequest>

DSMLv2 Response - One request not attempted

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>
<errorResponse type="connectionClosed"/>
</batchResponse>

---

Parallel Processing

A BatchRequest element MAY contain the optional XML-attribute processing, which influences how the server can process the request elements. The valid values are: sequential and parallel. If this attribute is omitted, the default value is sequential.

Example:

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core"
                      processing="parallel" >
...
</batchRequest>

In a BatchRequest with processing="sequential", the server MUST preserve sequential semantics, i.e. it behaves as already described regardless of the value of the responseOrder attribute. The effect of processing the BatchRequest MUST be as if the request elements were executed in the order they occur within the envelope.

In a BatchRequest with processing="parallel", the server MAY execute the request elements in any order. This form of processing is useful when a request contains multiple updates and the client knows that the updates are independent, as might be the case when DSMLv2 is used to bulk-load a directory. It is also useful when a request contains multiple queries and no updates.

In a BatchRequest with processing="parallel" and responseOrder="unordered", the client MUST specify a unique requestID for each individual request in the envelope. In this case, the server MAY return the responses in any order within the BatchResponse envelope - for example, in the order in which the operations complete, to improve server efficiency. If the client fails to specify a requestID for each request, the server MUST return an errorResponse with type="malformedRequest".

---

Resuming on Error

A BatchRequest element MAY contain the optional XML-attribute onError, which influences how the server responds to failures while processing request elements. The valid values are: exit and resume. If this attribute is omitted, the default value is exit.

Example:

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core"
                     onError="resume">
...
</batchRequest>

In a BatchRequest with onError="exit", the server stops executing request elements as soon as one request element fails, and the response that is sent implicitly includes a notAttempted response for all requests that do not otherwise have a response.

If processing="parallel" and onError="exit", the server stops initiating execution of new request elements as soon as one request element fails. Because of the parallelism, several executions might fail, and a request that the server did not attempt might precede a request that the server executed (with success or failure). When using positional correspondence between requests and responses, the provider/server MAY need to return responses for requests that it did not attempt. If the provider does not attempt to execute a request element, but needs to provide a response in order to maintain positional correspondence, it generates an errorResponse with type="notAttempted".

DSMLv2 Request with parallel execution containing a request that fails:

<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core"
                      processing="parallel" onError="resume">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<delRequest>...</delRequest>
<addRequest>...</addRequest>
</batchRequest>

DSMLv2 Response - two requests not successful

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<errorResponse type="notAttempted"/>
<delResponse>
 <resultCode code="32" descr="noSuchObject"/>
</delResponse>
</batchResponse>

In a BatchRequest with onError="resume", the server executes the remaining request elements even though one or more requests have failed. This form of processing is most useful when processing="parallel".

Even when processing="parallel", the syntax checking of a request document is performed sequentially. The provider does not attempt any requests that follow the first syntax error in the document.

---

LDAP Operations

With the exception of extendedRequest, each individual request element contains:

• A dn attribute (as in DSMLv1) containing a distinguished name.
• Zero or more control elements representing LDAP Controls.

Here are few examples of LDAP request elements:
<batchRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest dn="CN=Joe Smith, OU=Dev, DC=Example, DC=Com">
 ...
</modifyRequest>
<addRequest dn="OU=Sales,DC=Example, DC=Com">
...
</addRequest>
<delRequest dn="CN=Alice,OU=HR,DC=Example,DC=Com">
 <control>...</control>
 <control>...</control>
</delRequest>
<searchRequest>
 <control>...</control>
  ...
</searchRequest>
</batchRequest>

Here is an example of an LDAP Control:

<control type="1.2.840.113556.1.4.619" criticality="true">
<controlValue xsi:type="xsd:base64Binary">RFNNTHYyLjAgcm9ja3MhIQ==</controlValue>
</control>

Here are few examples of LDAP response elements:

<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
 ...
<modifyResponse>
 <resultCode code="53" descr="unwillingToPerform"/>
 <errorMessage>System Attribute may not be modified</errorMessage>
</modifyResponse>

<addResponse>
 <resultCode code="0" descr="success"/>
</addResponse>

<addResponse>
 <control>...</control>
 <control>...</control>
 <resultCode code="0" descr="success"/>
</addResponse>

  ...
</batchResponse>

The matchedDN and errorMessage elements are optional and default to the empty string.

The resultCode element has an optional descr attribute. If the server supplies this attribute, its value is the RFC 2251 text representation of the result code ("success", "operationsError", etc.), supplied for debugging convenience.

Like LDAP Request elements, LDAP response elements MAY contain zero or more controls.

The remainder of this section describes the encoding of each LDAP operation. Refer to RFC 2251 for the semantics of LDAP operations.

---

Values

The definition of DsmlValue permits the following types: UTF-8, base64Binary, and any URI. The URI type is used to indicate that the contents of the value are to be found at a location defined by the URI. For example, rather than sending a certificate as a base64Binary attribute value, a URI could be supplied that serves to locate the certificate on a certificate server. The ultimate value stored in the directory is the result of resolving the URI to establish that value. If it is intended to actually store a URI then it is appropriate to encode the URI with the UTF-8 value type.

Each binding MUST indicate how URIs are to be processed. For example, a binding MAY indicate that only 'http', 'ftp', 'file' or 'ldap' URIs are accepted and that they are processed only by the client provider. Another binding might specify that a DSMLv2 server for that binding will resolve the URI.

Auth

The authRequest provides a means for a client to indicate that access control for the following requests is to be interpreted as though the requests are performed by the security principal identified by the principal attribute. The value of the principal attribute is an authzId, as defined by [RFC 2829]. This can be useful if the DSMLv2 server (or an LDAP server to which the DSMLv2 server connects) is capable of supporting proxy authorization [ID-ProxyAuth].

At most one authRequest MAY occur within a BatchRequest and if it does occur, it MUST be the first request. If authRequest operations are not supported by the server to which the BatchRequest is sent, then the server MUST NOT process the following requests and MUST return a BatchResponse with an authResponse containing an LDAPResultCode of 'authMethodNotSupported'. If authRequest operations are supported, then if there are access rights errors, processing proceeds as for a BatchRequest without an authRequest - i.e., an appropriate errorResponse is generated, etc.

Example of authRequest:

<authRequest principal="dn:CN=Bob Rush,OU=Dev,DC=Example,DC=COM"/>

Example of authResponse:

<authResponse>
<resultCode code="0"/>
</authResponse>

Modify

DSMLv2 specifies each attribute modification by attaching an operation attribute to an attr element. As in LDAP, an operation can be add, delete, or replace.

Example of modifyRequest:

<modifyRequest dn="CN=Bob Rush,OU=Dev,DC=Example,DC=COM">
<modification name="telephoneNumber" operation="replace">
 <value>536 354 2343</value>
 <value>234 212 4534</value>
</modification>
<modification name="sn" operation="replace">
 <value>Rush</value>
</modification>
<modification name="directReport" operation="add">
 <value>CN=John Smith, DC=microsoft, DC=com</value>
</modification>
</modifyRequest>

Example of modifyResponse:

<modifyResponse>
<resultCode code="53" descr="unwillingToPerform"/>
<errorMessage>System Attribute may not be modified</errorMessage>
</modifyResponse>

Search

The DSMLv2 search encoding is based on the LDAP search encoding, but with some changes as described in Section A. In the searchRequest encoding:

• baseObject. Following DSMLv1 conventions, the distinguished name of the search base is expressed as the XML attribute dn.

Example:
<searchRequest dn="OU=Marketing,DC=Example,DC=COM" />

• sizeLimit, timeLimit, typesOnly. These elements default to 0, 0, and FALSE respectively.
• attributes. In RFC 2251, attributes is a sequence of attribute names, which is translated into a sequence of elements containing attribute names.

Example:
<attributes>
<attribute name="sn"/ >
<attribute name="givenName"/>
<attribute name="title"/>
</attributes>

SearchRequest example:

<searchRequest dn="ou=Marketing,dc=microsoft,dc=com"
                       scope="singleLevel"
                       derefAliases="neverDerefAliases"
                       sizeLimit="1000">
<control type="1.2.840.113556.1.4.612" criticality="true">
 <controlValue xsi:type="xsd:base64Binary">
   U2VhcmNoIFJlcXVlc3QgRXhhbXBsZQ==
 </controlValue>  
</control>
<control type="1.2.840.113556.1.4.643" criticality="true">
 <controlValue xsi:type="xsd:base64Binary">
   TWljcm9zb2Z0IEFjdGl2ZSBEaXJlY3Rvcnk=
</controlValue>
</control>
<filter><substrings  name="sn"><final>john</final></substrings></filter>
</searchRequest>

The response to a searchRequest is logically called a searchResponse. According to RFC 2251, a search response contains

• zero to many searchResultEntry
• zero to many searchResultReference
• one searchResultDone

DSMLv2 permits wrapping all of these related elements into one searchResponse envelope.

Each searchResultEntry, searchResultReference, and searchResultDone MAY have zero or more LDAP controls, consistent with RFC 2251.

searchResultEntry (with terminating searchResultDone) example:

<searchResponse>
<searchResultEntry dn="OU=Development,DC=Example,DC=COM">
 <attr name="allowedAttributeEffective">
  <value>description</value>
  <value>ntSecurityDescriptor</value>
  <value>wwwHomepage</value>
 </attr>
</searchResultEntry>
<searchResultEntry dn="CN=David,OU=HR,DC=Example,DC=COM">
 <attr name="objectclass"><value>person</value></attr>
 <attr name="sn"><value>Johnson</value></attr>
 <attr name="givenName"><value>David</value></attr>
 <attr name="title"><value>Program Manager</value></attr>
</searchResultEntry>
<searchResultEntry dn="CN=JSmith, OU=Finance,DC=Example,DC=COM">
 <attr name="objectclass"><value>top</value></attr>
 <attr name="objectclass"><value>person</value></attr>
 <attr name="objectclass"><value>organizationalPerson</value></attr>
 <attr name="sn"><value>Smith</value></attr>
</searchResultEntry>
<searchResultDone>
 <control type="1.2.840.113556.1.4.621" criticality="false">
  <controlValue xsi:type="xsd:base64Binary">
   U2VhcmNoIFJlcXVlc3QgRXhhbXBsZQ==
  </controlValue>
 </control>
 <resultCode code="0"/>
</searchResultDone>
</searchResponse>

searchResultReference example:

<searchResponse>
<searchResultReference>
 <ref>ldap://srv01.example.com/OU=Marketing,DC=Example,DC=COM</ref>
 <ref>ldap://srv05.fabrikam.com/DC=Fabrikam,DC=COM</ref>
</searchResultReference>
 ...
</searchResponse>

searchResultDone is illustrated above in the searchResultEntry example.

Note that it MAY be useful to limit the size of the searchResponse via sizeLimit or the use of a virtual list view control [ID-VLV]. Further, this specification does not introduce any limitation regarding the streaming processing of requests or responses including particularly searchResponse. In other words it is not necessary that an implementation build the entire searchResponse prior to sending the initial segment of that response.

Add

A DSMLv2 addRequest uses an encoding style analogous to that of the searchResultEntry to describe the object to be added.

Example of addRequest:

<addRequest dn="CN=Alice,OU=HR,DC=Example,DC=COM">
<attr name="objectclass"><value>top</value></attr>
<attr name="objectclass"><value>person</value></attr>
<attr name="objectclass"><value>organizationalPerson</value></attr>
<attr name="sn"><value>Johnson</value></attr>
<attr name="givenName"><value>Alice</value></attr>
<attr name="title"><value>Software Design Engineer</value></attr>
</addRequest>

Example of addResponse:

<addResponse>
<resultCode code="0"/>
<errorMessage>completed</errorMessage>
</addResponse>

Delete

Examples of delRequest:

<delRequest dn="CN=Bob,OU=HR,DC=Example,DC=COM" />

<delRequest dn="OU=HR,DC=Example,DC=COM" >
<control type="1.2.840.113556.1.4.805"/>
</delRequest>

Example of delResponse:

<delResponse matchedDN="OU=HR,DC=Example,DC=COM">
<resultCode code="32" descr="noSuchObject"/>
<errorMessage>DSDEL::230234</errorMessage>
</delResponse>

ModifyDN

Example of modDNRequest.

<modDNRequest dn="CN=Alice Johnson,DC=Example,DC=COM"
                       newrdn="Alice Weiss"
                       deleteoldrdn="true"
                       newSuperior="OU=Marketing,DC=Example,DC=COM"/>

Example of modDNResponse.

<modDNResponse>
<resultCode code="0" descr="success"/>
</modDNResponse>

Compare

Example of compareRequest:

<compareRequest dn="CN=Johnson,OU=HR, DC=Example,DC=COM">
<assertion name="sn"><value>Johnson</value></assertion>
</compareRequest>

Example of compareResponse:

<compareResponse>
<resultCode code="6" descr="compareTrue"/>
</compareResponse>

Extended Operation

Example of extendedRequest:

<extendedRequest>
<requestName>1.3.563.52.424</requestName>
<requestValue xsi:type="xsd:base64Binary">TFNNTHYyLjAgcm9ja3MhIQ==</requestValue>
</extendedRequest>

Example of extendedResponse:

<extendedResponse>
<resultCode code="0"/>
<response xsi:type="xsd:base64Binary">RFNNTHYyLjAgcm9ja3MhIQ==</response>
</extendedResponse>

---

Bindings

DSMLv2 defines two normative bindings:

• A SOAP request/response binding
• A file binding that serves as the DSMLv2 analog of LDIF

---

SOAP Binding

The following describes the DSMLv2 SOAP [W3C SOAP] request/response binding, using HTTP/1.1 and HTTPS/1.1 as a transport for DSMLv2 requests and responses. The version of SOAP for this binding is SOAP 1.1.

With SOAP binding, the DSMLv2 "server" is a servlet in Servlet/JSP engine in the application server. The client generates the DSML request and send the request to the servlet through HTTP/HTTPS. The servlet is responsible to parse the HTTP request to retrieve the DSML request, transform the DSML request to JNDI request and send the request to LDAP server using JNDI. After the servlet receives the response from the LDAP server, the servlet transform the JNDI response to DSML response and send back the response to the client who generated the DSML request.

The namespace for DSMLv2 is "urn:oasis:names:tc:DSML:2:0:core". This namespace is used at the top-level element of the <body> of each SOAP request and response. Default namespace designations MAY be used.

All SOAP requests and responses in this binding MUST use the xml encoding "UTF-8".

Each SOAP request body contains a single batchRequest. A SOAP node SHOULD indicate in the 'SOAPAction' header field the element name of the top-level element in the <body> of the SOAP request.

Each SOAP response body contains a single batchResponse.

A SOAP Fault is used only when an error occurs outside the scope of DSMLv2 processing. For example, the SOAP Server is not able to find or connect to a DSMLv2 server to process a DSMLv2 document. If errors happen during DSMLv2 processing, then they are conveyed as a DSMLv2 response document in the SOAP response message.

For example:

<!--  **** DSMLv2 Request ****** -->
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:batchRequest>
  <dsml:modifyRequest>...</dsml:modifyRequest>
  <dsml:addRequest>...</dsml:addRequest>
  ...
 </dsml:batchRequest>
</se:Body>
</se:Envelope>


<!--  **** DSMLv2 Response ****** -->
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
 <dsml:batchResponse>
  <dsml:modifyResponse>...</dsml:modifyResponse>
  <dsml:addResponse>...</dsml:modifyResponse>
  ...
 </dsml:batchResponse>
</se:Body>
</se:Envelope>


<!--  **** SOAP Fault ****** -->
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body>
 <se:Fault>
  <faultcode>se:Server</faultcode>
  <faultstring>Server Error</faultstring>
  <detail>Cannot connect to a DSMLv2 server</detail>
 </se:Fault>
</se:Body>
</se:Envelope>

This binding does not specify any SOAP headers.

A minimal implementation supports DsmlValue URIs of type file, which are evaluated by the client provider using the security context associated with the client. Individual implementations MAY support additional URI types. If the client provider is unable to resolve the URI to a value that can transferred to the server, then the provider MUST return an errorResponse with type="unresolvableURI".

Authentication in this binding is the ID and password which comes in as part of HTTP authentication, and is reused to bind to LDAP.

---

File Binding

The file binding is an alternative to the LDAP Data Interchange Format (LDIF) described by [RFC 2849]. Its primary advantages over LDIF are:

• Use of XML, which is more natural for many clients to generate and to parse than LDIF. Also benefits from the comparative wealth of tools.
• Formalization of output on error conditions, such as in the event the directory server is unavailable or the directory server returns an LDAP error.

With the file binding, the DSMLv2 "server" is a command-line program, as is typical for LDIF. The client that invokes the "server" program runs on the same computer as the server, and the input and output of the server are files consisting of DSMLv2 documents. The DSMLv2 server uses LDAP, another DSMLv2 transport, or some other mechanism to communicate with the directory service, which may be running on the same computer or on a different computer.

The top-level document for the input file is an element of type BatchRequest with name batchRequest. The top-level document for the output file is

an element of type BatchResponse with name batchResponse.

A minimal implementation supports DsmlValue URIs of type file, which are evaluated by the command-line program using the security context associated with the process running the command-line program. Individual implementations MAY support additional URI types. If the client provider is unable to resolve the URI to a value that can transferred to the server, then the command-line program MUST return an errorResponse with type="unresolvableURI".

The file binding authenticates to the directory using the user identity and password with which the command-line program was invoked.