Struct ldap3::Ldap

pub struct Ldap {
    pub timeout: Option<Duration>,
    pub controls: Option<Vec<RawControl>>,
    pub search_opts: Option<SearchOptions>,
    /* private fields */
}

Asynchronous handle for LDAP operations. *

All LDAP operations allow attaching a series of request controls, which augment or modify the operation. Controls are attached by calling with_controls() on the handle, and using the result to call another modifier or the operation itself. A timeout can be imposed on an operation by calling with_timeout() on the handle before invoking the operation.

The Search operation has many parameters, most of which are infrequently used. Those parameters can be specified by constructing a SearchOptions structure and passing it to with_search_options() called on the handle. This method can be combined with with_controls() and with_timeout(), described above.

There are two ways to invoke a search. The first, using search(), returns all result entries in a single vector, which works best if it’s known that the result set will be limited. The other way uses streaming_search(), which accepts the same parameters, but returns a handle which must be used to obtain result entries one by one.

As a rule, operations return LdapResult, a structure of result components. The most important element of LdapResult is the result code, a numeric value indicating the outcome of the operation. This structure also contains the possibly empty vector of response controls, which are not directly usable, but must be additionally parsed by the driver- or user-supplied code.

The handle can be freely cloned. Each clone will multiplex the invoked LDAP operations on the same underlying connection. Dropping the last handle will automatically close the connection.

Fields

timeout: Option<Duration>

controls: Option<Vec<RawControl>>

search_opts: Option<SearchOptions>

Implementations

impl Ldap

pub fn with_search_options(&mut self, opts: SearchOptions) -> &mut Self

Use the provided SearchOptions with the next Search operation, which can be invoked directly on the result of this method. If this method is used in combination with a non-Search operation, the provided options will be silently discarded when the operation is invoked.

The Search operation can be invoked on the result of this method.

pub fn with_controls<V: IntoRawControlVec>(&mut self, ctrls: V) -> &mut Self

Pass the provided request control(s) to the next LDAP operation. Controls can be constructed by instantiating structs in the controls module, and converted to the form needed by this method by calling into() on the instances. Alternatively, a control struct may offer a constructor which will produce a RawControl instance itself. See the module-level documentation for the list of directly supported controls and procedures for defining custom controls.

This method accepts either a control vector or a single RawControl. The latter is intended to make the call site less noisy, since it’s expected that passing a single control will comprise the majority of uses.

The desired operation can be invoked on the result of this method.

pub fn with_timeout(&mut self, duration: Duration) -> &mut Self

Perform the next operation with the timeout specified in duration. The LDAP Search operation consists of an indeterminate number of Entry/Referral replies; the timer is reset for each reply.

If the timeout occurs, the operation will return an error. The connection remains usable for subsequent operations.

The desired operation can be invoked on the result of this method.

pub async fn simple_bind( &mut self, bind_dn: &str, bind_pw: &str ) -> Result<LdapResult>

Do a simple Bind with the provided DN (bind_dn) and password (bind_pw).

pub async fn sasl_external_bind(&mut self) -> Result<LdapResult>

Do an SASL EXTERNAL bind on the connection. The identity of the client must have already been established by connection-specific methods, as is the case for Unix domain sockets or TLS client certificates. The bind is made with the hardcoded empty authzId value.

pub async fn sasl_gssapi_bind( &mut self, server_fqdn: &str ) -> Result<LdapResult>

Available on crate feature gssapi only.

Do an SASL GSSAPI bind on the connection, using the default Kerberos credentials for the current user and server_fqdn for the LDAP server SPN. If the connection is in the clear, request and install the Kerberos confidentiality protection (i.e., encryption) security layer. If the connection is already encrypted with TLS, use Kerberos just for authentication and proceed with no security layer.

On TLS connections, the tls-server-end-point channel binding token will be supplied to the server if possible. This enables binding to Active Directory servers with the strictest LDAP channel binding enforcement policy.

The underlying GSSAPI libraries issue blocking filesystem and network calls when querying the ticket cache or the Kerberos servers. Therefore, the method should not be used in heavily concurrent contexts with frequent Bind operations.

pub async fn search<'a, S: AsRef<str> + Send + Sync + 'a, A: AsRef<[S]> + Send + Sync + 'a>( &mut self, base: &str, scope: Scope, filter: &str, attrs: A ) -> Result<SearchResult>

Perform a Search with the given base DN (base), scope, filter, and the list of attributes to be returned (attrs). If attrs is empty, or if it contains a special name * (asterisk), return all (user) attributes. Requesting a special name + (plus sign) will return all operational attributes. Include both * and + in order to return all attributes of an entry.

The returned structure wraps the vector of result entries and the overall result of the operation. Entries are not directly usable, and must be parsed by SearchEntry::construct(). All referrals in the result stream will be collected in the refs vector of the operation result. Any intermediate messages will be discarded.

This method should be used if it’s known that the result set won’t be large. For other situations, one can use streaming_search().

pub async fn streaming_search<'a, S: AsRef<str> + Send + Sync + 'a, A: AsRef<[S]> + Send + Sync + 'a>( &mut self, base: &str, scope: Scope, filter: &str, attrs: A ) -> Result<SearchStream<'a, S, A>>

Perform a Search, but unlike search() (q.v., also for the parameters), which returns all results at once, return a handle which will be used for retrieving entries one by one. See SearchStream for the explanation of the protocol which must be adhered to in this case.

pub async fn streaming_search_with<'a, V: IntoAdapterVec<'a, S, A>, S: AsRef<str> + Send + Sync + 'a, A: AsRef<[S]> + Send + Sync + 'a>( &mut self, adapters: V, base: &str, scope: Scope, filter: &str, attrs: A ) -> Result<SearchStream<'a, S, A>>

Perform a streaming Search internally modified by a chain of adapters. The first argument can either be a struct implementing Adapter, if a single adapter is needed, or a vector of boxed Adapter trait objects.

pub async fn add<S: AsRef<[u8]> + Eq + Hash>( &mut self, dn: &str, attrs: Vec<(S, HashSet<S>)> ) -> Result<LdapResult>

Add an entry named by dn, with the list of attributes and their values given in attrs. None of the HashSets of values for an attribute may be empty.

pub async fn compare<B: AsRef<[u8]>>( &mut self, dn: &str, attr: &str, val: B ) -> Result<CompareResult>

Compare the value(s) of the attribute attr within an entry named by dn with the value val. If any of the values is identical to the provided one, return result code 5 (compareTrue), otherwise return result code 6 (compareFalse). If access control rules on the server disallow comparison, another result code will be used to indicate an error.

pub async fn delete(&mut self, dn: &str) -> Result<LdapResult>

Delete an entry named by dn.

pub async fn modify<S: AsRef<[u8]> + Eq + Hash>( &mut self, dn: &str, mods: Vec<Mod<S>> ) -> Result<LdapResult>

Modify an entry named by dn by sequentially applying the modifications given by mods. See the Mod documentation for the description of possible values.

pub async fn modifydn( &mut self, dn: &str, rdn: &str, delete_old: bool, new_sup: Option<&str> ) -> Result<LdapResult>

Rename and/or move an entry named by dn. The new name is given by rdn. If delete_old is true, delete the previous value of the naming attribute from the entry. If the entry is to be moved elsewhere in the DIT, new_sup gives the new superior entry where the moved entry will be anchored.

pub async fn extended<E>(&mut self, exop: E) -> Result<ExopResult>where E: Into<Exop>,

Perform an Extended operation given by exop. Extended operations are defined in the exop module. See the module-level documentation for the list of extended operations supported by this library and procedures for defining custom exops.

pub async fn unbind(&mut self) -> Result<()>

Terminate the connection to the server.

pub fn last_id(&mut self) -> RequestId

Return the message ID of the last active operation. When the handle is initialized, this value is set to zero. The intended use is to obtain the ID of a timed out operation for passing it to an Abandon or Cancel operation.

Using this method in the start() adapter chain of a streaming Search will return zero, since the Message ID is obtained in the inner start() method.

pub async fn abandon(&mut self, msgid: RequestId) -> Result<()>

Ask the server to abandon an operation identified by msgid.

pub fn is_closed(&mut self) -> bool

Check whether the underlying connection has been closed.

This is an indirect check: it queries the status of the channel for communicating with the connection structure, not the connection socket itself. The channel being open does not mean there is bidirecional communication with the server; to check for that, a round-trip operation (e.g., WhoAmI) would be necessary.

pub async fn get_peer_certificate(&mut self) -> Result<Option<Vec<u8>>>

Return the TLS peer certificate in DER format.

The method returns Ok(None) if no certificate was found or the connection does not use or support TLS.

Trait Implementations

impl Clone for Ldap

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ldap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.