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?
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:
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:
The base Universal Resource Name (URN) for DSMLv2 is:
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:
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.
With the exception of extendedRequest , each individual request element contains:
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.1135188.8.131.529" 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:
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:
The attributes stored here are described in TABLE 10-1.
Table 10-1. DSMLv2 Attributes
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 #
By default, the DSMLv2 plug-in is turned off and no secure port is defined.
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:
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.
# 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 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.