Many applications need to access a directory in order to perform authentication and to obtain configuration information. Isode's Directory Client API provides a simple API to enable applications to do this. This API is designed so that it is easy for applications to access generic directory functionality, and also provides additional function for specific applications and markets.

Isode's Directory Client API uses X.500 Directory Access Protocol (DAP) and/or LDAP (Lightweight Directory Access Protocol) to access a Directory. X.500 DAP support is important for applications that require use of DAP, or need to make use of schema definitions that are only defined for used with X.500 (e.g., directory syntaxes defined in X.402 to support X.400 use of directory). LDAP is supported using the same API.

The Isode Directory Client API is of particular interest where there is (or may be) a requirement to use DAP. Its simple design and cross platform multi-language support will also make it useful for LDAP only applications. Strong authentication is supported, which is important for some secure environments.

The Directory Client API is intended for both standalone client applications and for Web applications. A 'C' language binding and a Java binding are provided.

Deployment Targets

The Directory Client API provides a core set of functionality, which is useful to any directory enabled application. Functionality appropriate for specific markets is offered in addition to the core API, which is a mix of layered functionality and additional supporting routines. The first market specific API, which includes the core Directory Client API, is the ATN (Air Traffic Network) Directory API for the Air Traffic industry.

Key Benefits

The Isode Directory Client API offers the following benefits:

  • For developers of directory enabled applications, it provides a very simple abstraction.
  • The API is cross platform.
  • The API supports X.500 DAP.
  • LDAP and DAP can be used from the same application, without code changes.

Architecture and Functionality

The Directory Client API is used as illustrated below. The application uses the library to connect the application to M-Vault using X.500 DAP or LDAP.

Directory Client API

This design means that any application making use of the Directory Client API need have no knowledge of which protocol is being used to communicate with the directory

The Directory Client API is designed to be easy to use for applications that access data in the directory. It is also suitable for applications that administer directory data. The following directory operations are supported:

  • Read
  • Search
  • Add
  • Delete
  • Modify
  • ModifyDN (Rename)

This API may be used in a synchronous manner for all operations, which allows for straightforward implementation. Read and search operations may also be used asynchronously. Paged results are supported to help with large result sets. The API may be used with a multithreaded application. Note that each distinct DAP or LDAP connection is intended to be accessed by a single thread. If you need to have multiple threads accessing a single association, then contact Isode to review the suitability of this API.

Selecting DAP and/or LDAP

The API is designed so that a single application can create DAP and LDAP connections using exactly the same API and use a mix of DAP and LDAP calls. The choice of underlying protocol is as simple as choosing the connection address - for DAP connections an RFC 1278-format address such as '"X500"/Internet=dsa.example.com', and for LDAP connections an RFC 2255-format address such as 'ldap://ldap.example.com' is used instead.

API Layering

The Directory Client API provides a core set of functionality which is useful to any directory enabled application. Functionality appropriate for specific markets is offered in addition to the core API, which is a mix of layered functionality and additional supporting routines. The first market specific API, which include the core Directory Client API is the ATN (Air Traffic Network) Directory API for the Air Traffic industry.

Security

Simple authentication is supported for DAP and LDAP. Strong authentication based on X.509 is supported for DAP, using Isode's strong authentication infrastructure. SASL support is provided for LDAP. Password policy controls are available for LDAP.

The ATN Directory API

The aviation industry is adopting AMHS (Aeronautical Message Handling Systems) for provision of ground to ground communication. Isode provides a set of ICAO (International Civil Aviation Organization) SARPS (Standard and Recommended Practices) conformant server products (M-Switch X.400, X.400 Message Store, and M-Vault), to provide an AMHS infrastructure and an ATN (Air Traffic Network) Directory. These standards require use of DAP to communicate with the directory.

ATN Directory API

The ATN Directory API provides additional functionality to:

  • Handle ATN Directory structured attributes such as MTCU (Message Transfer and Conversion Unit) capabilities.
  • To provide ATN Directory based conversion between eight digit AFTN (Aeronautical Fixed Telecommunications Network) addresses and X.400 O/R Addresses.
  • To provide ATN Directory based conversion between eight digit AFTN (Aeronautical Fixed Telecommunications Network) addresses and Directory Names.

The mapping functionality is broadly specified in Doc 9880 - First Edition 2010, with details from other industry documents. The O/R Address/AFTN mapping provides a mapping functionality which is conformant to the ICAO specification for MTCU operation.

Isode distributes data suitable to populate a directory with mapping information. This is explained here.

Isode also provides a tool for use in conjunction with this API to convert from the centrally managed AMC tables into this LDIF format, so that mapping data can be easily loaded into the directory.

Interoperability

The ATN Directory API has been primarily developed to integrate applications with the Isode server products. Because of its use of the X.500 DAP and LDAP protocols, applications developed with this library should also work with other conformant servers. For ATN Directory applications and some other X.400 applications, use of the API over LDAP relies on Isode proprietary attribute syntaxes.

Conformance

X.500 Directory Access Protocol

ITU X.500 The Directory: Overview of concepts, models and services, ISO/IEC 9594-1, 2005
ITU X.501 The Directory: Models, ISO/IEC 9594-2, 2008
ITU X.509 The Directory: Authentication framework, ISO/IEC 9594-8, 2008
ITU X.511 The Directory: Abstract service definition, ISO/IEC 9594-3, 2008 
ITU X.519 The Directory: Protocol specifications, ISO/IEC 9594-5, 2008

LDAP

LDAP Version 3 (RFC 4510-4519).

ATN Directory (ICAO SARPs)

ICAO SARPS Doc 9880. Manual of Detailed Technical Specifications for the Aeronautical Telecommunications Network (ATN) using ISO/OSI Standards and Protocols. Part IV – Directory Services, Security and Systems Management. First Edition 2010.

AFTN Address Mappings

Chapter 6 (ATS Message Handling) of the Comprehensive Aeronautical Telecommunication Network (ATN) Manual (Part III. Applications guidance material), section 6.2.1.5.10-17.

API Definition

The Isode manual describing the Directory Client API and ATN Directory Client API is available.

The core 'C' language Isode Directory Client API definitions are available with sample applications available. The 'C' language ATN Directory Client API comprises the core API plus the 'C' language ATN Directory Client API extensions to the core API. Thedefinitions of these extensions are available with an example program.

Java version of the API documentation is also available.