ldap3 0.4.4

Pure-Rust LDAPv3 Client
Documentation

LDAP client library

A pure-Rust LDAP library using the Tokio stack.

The library can be used either synchronously or asynchronously. The aim is to offer essentially the same call interface for both flavors, with the necessary differences in interaction and return values according to the nature of I/O.

Documentation

Usage

First, add this to your Cargo.toml:

[dependencies.ldap3]
version = "0.4"

Next, add this to your crate root (src/lib.rs or src/main.rs):

extern crate ldap3;

Synchronous example

extern crate ldap3;

use ldap3::{LdapConn, Scope, SearchEntry};

fn main() {
    let ldap = LdapConn::new("ldap://ldap.example.org").expect("ldap conn");

    let (result_set, result, _controls) = ldap.search(
        "ou=People,dc=example,dc=org",
        Scope::Subtree,
        "objectClass=inetOrgPerson",
        vec!["uid"]
    ).expect("all results");

    println!("{:?}", result);
    for entry in result_set {
        println!("{:?}", SearchEntry::construct(entry));
    }
}

Asynchronous example

extern crate futures;
extern crate ldap3;
extern crate tokio_core;

use std::io;

use futures::{Future, Stream};
use ldap3::{LdapConnAsync, Scope, SearchEntry};
use tokio_core::reactor::Core;

fn main() {
    let mut core = Core::new().expect("core");
    let handle = core.handle();

    let ldap = LdapConnAsync::new("ldaps://ldap.example.org", &handle).expect("ldap conn");
    let srch = ldap
        .and_then(|ldap| {
            ldap.search(
                "ou=People,dc=example,dc=org",
                Scope::Subtree,
                "objectClass=inetOrgPerson",
                vec!["uid"])
        })
        .and_then(|(strm, rx)| {
            rx.map_err(|_e| io::Error::from(io::ErrorKind::Other))
                .join(strm.for_each(move |tag| {
                    println!("{:?}", SearchEntry::construct(tag));
                    Ok(())
                }))
        });

    let ((result, _controls), _) = core.run(srch).expect("op result");
    println!("{:?}", result);
}

Status

All LDAP protocol operations are implemented, as well as the support for request and response controls. The driver still lacks automated handling of several common scenarios, such as referral chasing and paged results.

TLS support exists for the case of immediate negotiation (aka ldaps://). StartTLS will probably be supported in the medium term. On Unix-like systems, connecting through a Unix domain socket with the ldapi:// scheme is supported.

Caveats:

  • Certificate and hostname checking can't be turned off for TLS connections.

  • Hostname resolution is synchronous. The library doesn't initiate any connections by itself, so this should be manageable in most scenarios.

  • Unbind doesn't close our side of the connection, since the underlying TCP stream is inaccessible in the present implementation.

  • Abandon accepts only request ids of active searches.

  • Only version 3 of LDAP is supported.

  • CLDAP (LDAP over UDP) is not supported.

Upcoming changes

Version 0.4.3 will be the last one in the 0.4 series, barring significant bugs.

Version 0.5 of the library will have a number of breaking changes.

  • Response control vector will be incorporated into LdapResult.

  • Control and exop construction and parsing will expose all traits and structs necessary to enable third-party implementations with the same interface as the in-library ones. Notably, parsing will be moved from free functions to methods on control/exop structs.

  • The Abandon operation won't be directly accessible anymore; it will only be possible to invoke it on a streaming Search.

Tentative plans for version 0.6 include internal parsing and error handling overhaul, and the introduction of timeouts for all operations, if specified.

License

Licensed under either of:

at your option.