DSMLv2 Interface

In this section, the new DSMLv2 interface for Sun ONE Directory Server 5.2 software is examined. The section addresses the following questions:

• What is DSML?

• How is it used?

• How it is implemented?

What Is DSML?

The Directory Services Markup Language (DSML) provides a means for representing directory information and performing directory operations from an XML document. This means you can search, add, delete, and modify directory data using DSML over HyperText Transport Protocol (HTTP) without the Lightweight Directory Access Protocol. This is important because some clients such as personal digital assistants (PDAs) do not contain a full-blown client.

DSMLv1 focused on how to represent directory structured data. 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 so they can be consumed or produced by programs, or they can be transported over HTTP to and from a server that interprets and generates them.

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 as it does in 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 types of bindings:

• A SOAP request/response binding

• A file binding that serves as the DSMLv2 analog of LDIF

For the most part, DSML is aligned with LDAP. However there are a few places where it makes sense for DSMLv2 to diverge from LDAP:

• 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 through a variety of mechanisms, so the document itself is not used to authenticate the requestor . DSMLv2 includes an Auth request that can be used to associate a security principal with a collection of DSMLv2 operations.

• LDAP does not include a method of grouping operations together so they can be expressed in a single request. DSMLv2 allows multiple LDAP operations to be expressed in one request document by specifying a simple positional correspondence between individual requests within a request document.

• 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.

• The systematic translation of RFC 2251 results in a redundant level of nested elements, the LDAPMessage . DSMLv2 eliminates this extra level.

• 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 , , and FALSE respectively.

The base Universal Resource Name (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, an envelope grouping the entries, and references and result of a search operation.

An example of using the DSMLv2 URN is:

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

There are two types of DSMLv2 documents:

• request document

• 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. In the two bindings defined in the DSMLv2 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.

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, it directly corresponds to the third request element, a delete request.

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 a 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> 

Here are a 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> <resultCode code="0" descr="success"/> </addResponse> 

What Can You Use It For?

DSMLv2 functionality is motivated by scenarios such as:

• A smart cell phone or PDA that needs to access directory information but does not contain an LDAP client.

• A program that needs access to 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.

DSMLv2 Sun ONE Directory Server 5.2 Software Implementation

The DSMLv2 interface is implemented as a front-end plug-in. The plug-in is configured to listen on an encrypted and a non-encrypted port. The configuration data for the service resides at the DN:

c n=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config

The attributes stored here are described in TABLE 10-1.

Table 10-1. DSMLv2 Attributes

Attribute	Description
ds-hdsml-clientauthmethod	Defines how the server identifies a client on a TLS/SSL connection. Options are: clientCertOnly the server uses credentials from the client certificate httpBasicOnly the server uses the credentials from the HTTP authorization header clientCertFirst tries using the client certificate first, then the HTTP authentication header
ds-hdsml-dsmlschemalocation	The path to the DSMLv2 schema. This should not be changed.
ds-hdsml-iobuffersize	The size of the buffer where the DSML request is stored. The default is 8192 and must be a multiple of 256.
ds-hdsml-poolmaxsize	The maximum size of the pool of parsers. The default is 10 .
ds-hdsml-poolsize	The minimum size of the pool of parsers. The default is 5 .
ds-hdsml-port	The HTTP port used for unencrypted communications. The default is 80 , but must be changed if that port is in use.
ds-hdsml-requestmaxsize	The maximum size of a DSML request allowed by the server. The default is 32768 .
ds-hdsml-responsemsgsize	The maximum size of a server response to a DSML request. The default is 65536 .
ds-hdsml-rooturl	The root URL that is specified in a DSML request. The default is /dsml .
ds-hdsml-secureport	The port number used for secure DSML communication over TLS/SSL. There is no default port number.
ds-hdsml-soapschemalocation	The path to the SOAP schema. This value should not be changed.

To view these attributes and their values, use the ldapsearch command:

 #  ldapsearch -L -D "cn=directory manager" -w mysecret -b \   cn=frontends,cn=plugins,cn=config cn=DSMLv2-SOAP-HTTP  dn: cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config objectClass: top objectClass: nsSlapdPlugin objectClass: ds-signedPlugin objectClass: extensibleObject cn: DSMLv2-SOAP-HTTP nsslapd-pluginPath: /var/mps/serverroot/lib/hdsml-plugin.so nsslapd-pluginInitfunc: hdsml_init nsslapd-pluginType: frontend nsslapd-pluginVersion: 5.2 nsslapd-pluginVendor: Sun Microsystems, Inc. nsslapd-pluginDescription: HTTP/SOAP/DSMLv2 frontend plugin nsslapd-pluginId: http-soap-dsmlv2-frontend ds-hdsml-port: 80 ds-hdsml-iobuffersize: 8192 ds-hdsml-requestmaxsize: 32768 ds-hdsml-responsemsgsize: 65536 ds-hdsml-poolsize: 5 ds-hdsml-poolmaxsize: 10 ds-hdsml-clientauthmethod: clientCertFirst ds-hdsml-rooturl: /dsml ds-hdsml-soapschemalocation: /var/mps/serverroot/lib/soap-env.xsd ds-hdsml-dsmlschemalocation: /var/mps/serverroot/lib/DSMLv2.xsd nsslapd-pluginEnabled:  off  # 

Note

By default, the DSMLv2 plug-in is turned off and no secure port is defined.

Configuring DSML

The Sun ONE Directory Server 5.2 software can be configured to listen to and process DSML requests either through the Console or from the command line. Configuration consists of:

• Enabling the plug-in

• Setting a security policy

• Changing the default values

To enable the plug-in, change the value of the nsslapd-pluginEnabled from off to on . After the attribute value is changed, the directory server must be restarted for the change to take effect.

Example:

 #  ldapmodify -D "cn=directory manager" -w mysecret   dn: cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config   changetype: modify   replace: nsslapd-pluginEnabled   nsslapd-pluginEnabled: on   ^D  #  directoryserver stop  #  directoryserver start  

There are a number of authentication options that can be deployed, such as:

• Anonymous

• Basic HTTP

• Basic HTTP over TLS/SSL

• Client TLS/SSL certificates

Anonymous access is granted if no authorization header or client certificate is submitted with the DSML request. This is the same behavior that is defined in the LDAPv3 specification for normal directory access.

An authentication header can be included with the DSML request. If it is, basic HTTP authentication is performed. A technique called identity mapping is implemented on the directory server. This associates values in the header with user entries in the directory. The values in the header are the user name and password.

Unless a secure port is configured, communication to and from the directory server is sent in clear text. To avoid sending the authorization header in clear text, a secure port must be configured. With basic HTTP authentication over TLS/SSL, the client does not need to have a certificate. Only the server certificate is required.

The following code box shows how to specify a secure DSML port:

 #  ldapmodify -D "cn=directory manager" -w mysecret   dn: cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config   changetype: modify   add: ds-hdsml-secureport   ds-hdsml-secureport:  1443  ^D  #  directoryserver stop  #  directoryserver start  

If the DSML request contains a client certificate, the authentication header is not required. Instead, a mapping of the certificate to one stored in the directory is performed. If a client certificate is found that matches the one sent in the DSML request, the request is authenticated.