Crate ldap3

Source
Expand description

A pure-Rust LDAP client library using the Tokio stack.

§Usage

In Cargo.toml:

[dependencies.ldap3]
version = "0.11.5"

§Summary

The library provides both synchronous and asynchronous interfaces. The LdapConn structure is the starting point for all synchronous operations. LdapConnAsync is its asynchronous analogue, and Ldap is the low-level asynchronous handle used internally by LdapConn, and explicitly by the users of the asynchronous interface.

In the struct list, async-related structs have an asterisk (*) after the short description.

The documentation is written for readers familiar with LDAP concepts and terminology, which it won’t attempt to explain. If you need an introductory text, you can try the primer included in this library.

§Compile-time features

The following features are available at compile time:

  • sync (enabled by default): Synchronous API support.

  • gssapi (disabled by default): Kerberos/GSSAPI support. On Windows, system support crates and SDK libraries are used. Elsewhere, the feature needs Clang and its development libraries (for bindgen), as well as the Kerberos development libraries. On Debian/Ubuntu, that means clang-N, libclang-N-dev and libkrb5-dev. It should be clear from these requirements that GSSAPI support uses FFI to C libraries; you should consider the security implications of this fact.

    For usage notes and caveats, see the documentation for Ldap::sasl_gssapi_bind().

  • tls (enabled by default): TLS support, backed by the native-tls crate, which uses a platform-specific TLS backend. This is an alias for tls-native.

  • tls-rustls (disabled by default): TLS support, backed by the Rustls library.

Without any features, only plain TCP connections (and Unix domain sockets on Unix-like platforms) are available. For TLS support, tls and tls-rustls are mutually exclusive: choosing both will produce a compile-time error.

§Examples

The following two examples perform exactly the same operation and should produce identical results. They should be run against the example server in the data subdirectory of the crate source. Other sample programs expecting the same server setup can be found in the examples subdirectory.

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

fn main() -> Result<()> {
    let mut ldap = LdapConn::new("ldap://localhost:2389")?;
    let (rs, _res) = ldap.search(
        "ou=Places,dc=example,dc=org",
        Scope::Subtree,
        "(&(objectClass=locality)(l=ma*))",
        vec!["l"]
    )?.success()?;
    for entry in rs {
        println!("{:?}", SearchEntry::construct(entry));
    }
    Ok(ldap.unbind()?)
}
use ldap3::{LdapConnAsync, Scope, SearchEntry};
use ldap3::result::Result;

#[tokio::main]
async fn main() -> Result<()> {
    let (conn, mut ldap) = LdapConnAsync::new("ldap://localhost:2389").await?;
    ldap3::drive!(conn);
    let (rs, _res) = ldap.search(
        "ou=Places,dc=example,dc=org",
        Scope::Subtree,
        "(&(objectClass=locality)(l=ma*))",
        vec!["l"]
    ).await?.success()?;
    for entry in rs {
        println!("{:?}", SearchEntry::construct(entry));
    }
    Ok(ldap.unbind().await?)
}

Re-exports§

pub use filter::parse as parse_filter;
pub use result::LdapError;
pub use result::LdapResult;
pub use result::SearchResult;

Modules§

adapters
Search operation adapters.
asn1
ASN.1 structure construction and parsing.
controls
Control construction and parsing.
exop
Extended operation construction and parsing.
result
Operation result structures and helpers.

Macros§

drive
Drive the connection until its completion. *

Structs§

EntryStream
Handle for obtaining a stream of search results.
Ldap
Asynchronous handle for LDAP operations. *
LdapConn
Synchronous connection to an LDAP server.
LdapConnAsync
Asynchronous connection to an LDAP server. *
LdapConnSettings
Additional settings for an LDAP connection.
LdapUrlParams
Parameters of an LDAP URL.
ResultEntry
Wrapper for the internal structure of a result entry.
SearchEntry
Parsed search result entry.
SearchOptions
Additional parameters for the Search operation.
SearchStream
Asynchronous handle for obtaining a stream of search results. *

Enums§

DerefAliases
Possible values for alias dereferencing during search.
LdapUrlExt
LDAP URL extensions.
Mod
Possible sub-operations for the Modify operation.
Scope
Possible values for search scope.
StreamState
Possible states of a SearchStream.

Functions§

dn_escape
Escape an attribute value in a relative distinguished name (RDN).
get_url_params
Extract parameters from an LDAP URL.
ldap_escape
Escape a filter literal.
ldap_str_unescapeDeprecated
ldap_unescape
Unescape a string using LDAP filter escapes.
parse_refs
Parse the referrals from the supplied BER-encoded sequence.

Type Aliases§

RequestId
Type alias for the LDAP message ID.