7.3 ADConnection Abstract Data Model

  • Article

This section describes a conceptual model of a possible data organization that an implementation maintains. The described organization is provided to facilitate the explanation of how the client behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.

The data model defines a set of structures that a client operates on, and also an element which lists all active ADConnection objects. The primary structure is ADConnection, with two supporting structures LDAPRequest and ConnectionInfo. These structures and others are described below.

ComputerRole: An abstract variable of type DSROLE_MACHINE_ROLE ([MS-DSSP] section 2.2.2) that indicates the current domain membership role of the machine on which the LDAP client is executing, as described in [MS-DSSP] section 3.2.1, Abstract Data Model.

ADCList: A list of ADConnection objects. It is initialized to the empty list.

ADConnection: A structure that tracks a connection to an Active Directory server. Sub-elements with names of the form LDAP_OPT_<rest of name> are ADM elements that can be set by the Setting an LDAP Option on an ADConnection (section 7.6.1.2) task. It has the following elements:

LDAP_OPT_REFERRAL_HOP_LIMIT: An unsigned integer indicating the limit on the number of referrals or continuation references that the client will follow for a single LDAP request. The default value is 32. A value of zero indicates no limit.

LDAP_OPT_REFERRALS: An enumeration indicating whether the client is to automatically follow referrals and continuation references. Valid values are:

  • ON: The default value. The client automatically follows both referrals and continuation references.

  • OFF: The client does not follow either referrals or continuation references automatically.

  • LDAP_CHASE_CONTINUATION_REFERENCES: The client follows only continuation references automatically.

  • LDAP_CHASE_REFERRALS: The client follows only referrals automatically.

LDAP_OPT_TIMELIMIT: An unsigned integer indicating the maximum time in seconds the client will wait for a response to an LDAP request. A value of 0 indicates a limit of 120 seconds for LDAP bind requests and no time limit for all other requests. The default value is 0. This ADM element can be overridden if a value for the time limit is specified in the parameters of the Performing an LDAP Operation on an ADConnection (section 7.6.1.6) task.

LDAP_OPT_SIZELIMIT: An unsigned integer indicating the maximum number of results the client will request the directory server to send for a given search request. The valid range is from 0 to 2^32 -1. A value of 0 indicates that there is no limit. The default value is 0. This ADM element can be overridden if a value for the size limit is specified in the parameters of the Performing an LDAP Operation on an ADConnection (section 7.6.1.6) task.

LDAP_OPT_AREC_EXCLUSIVE: A Boolean flag indicating whether the client is to skip the DC Location processing (described in section 7.6.2.2) during host resolution. A value of TRUE indicates that DC Location will be skipped. The default value is FALSE.

LDAP_OPT_DNSDOMAIN_NAME: A null-terminated string used in constructing a service principal name (SPN) (2) when performing an LDAP bind.

LDAP_OPT_GETDSNAME_FLAGS: An unsigned integer indicating the flags to be passed when invoking DsrGetDcNameEx2 to perform DC location. For more information, see [MS-NRPC] section 3.5.4.3.1, DsrGetDcNameEx2 (Opnum 34). By default, the value is 0.

LDAP_OPT_AUTO_RECONNECT: A Boolean flag indicating whether the client will attempt to automatically reconnect to a server when an existing connection is lost. The default value is TRUE.

LDAP_OPT_PING_KEEP_ALIVE: An unsigned integer indicating the maximum time in seconds the client will allow a connection to be idle (that is, receiving no responses) while waiting on outstanding requests on the connection before sending the directory server a sequence of PING requests. The valid range is 5 seconds to 2^32-1 seconds. The default value is 120 seconds.

LDAP_OPT_PING_WAIT_TIME: An unsigned integer indicating the time in milliseconds (ms) the client will wait for a response to a PING request. The valid range is 10 ms to 60000 ms. The default value is 2000 ms.

LDAP_OPT_PING_LIMIT: An unsigned integer indicating the maximum number of consecutive PINGs the client will send without getting an ICMP echo response ([RFC792]) before triggering the Processing Network Errors (section 7.6.3.1) event. Valid range is 0 to 2^32-1. A value of 0 indicates that the client never PINGs the server for an idle connection. The default value is 4.

LDAP_OPT_ENCRYPT: A Boolean flag indicating whether SASL layer encryption (section 5.1.2.1, Using SASL) is enabled on the connection. If a non-default value is desired, this MUST be set prior to performing an LDAP bind on the connection. The default value is FALSE.

LDAP_OPT_SIGN: A Boolean flag indicating whether SASL layer signing (section 5.1.2.1, Using SASL) is enabled on the connection. If a non-default value is desired, this MUST be set prior to performing an LDAP bind on the connection. The default value is TRUE.

LDAP_OPT_TCP_KEEPALIVE: A Boolean flag indicating whether TCP Keep-alives ([RFC1122] section 4.2.3.6, TCP Keep-Alives) are enabled on primaryConnection. The default value is FALSE.

LDAP_OPT_AUTH_INFO: An instance of an AuthInfo structure representing the bind method and credentials to use when authenticating to the directory server. By default, the bindMethod is SASL using the GSS-SPNEGO mechanism, and the name and password are those of the identity of the protocol or system using the LDAP client. When attempting to use the server in fast bind mode, the bindMethod is set to simple bind prior to performing an LDAP bind on the connection. Subsequently, only simple binds can be performed to the server as long as the connection is in fast bind mode. See section 5.1.1.1, (Supported Authentication Methods) for a list of supported bind methods.

LDAP_OPT_PROTOCOL_VERSION: An unsigned integer indicating which version of the LDAP protocol the connection uses. Valid values are 2 and 3. The default value is 2. If a non-default value is desired, this MUST be set prior to performing an LDAP bind on the connection.

primaryConnection: A ConnectionInfo structure representing the TCP connection for the target directory server. The target directory server is the directory server specified as a parameter to the Initializing an ADConnection (section 7.6.1.1) task.

referralConnections: A list of ConnectionInfo structures representing the TCP connections to directory servers used for following referrals or continuation references. It is initialized to an empty list.

LDAPRequest: A structure that tracks an LDAP request ([RFC1777] section 2, Protocol Model, for LDAP version 2 and [RFC2251] section 3.1, Protocol Model, for LDAP version 3). It has the following elements:

requestMessage: An LDAPMessage (as defined in [RFC1777] section 4, Elements of Protocol, for LDAP version 2 and [RFC2251] section 4.1.1, Message Envelope, for LDAP version 3) representing a request that the client sends to the server.

resultMessages: A sequence of LDAPMessage (as defined in [RFC1777] section 4, Elements of Protocol, for LDAP version 2 and [RFC2251] section 4.1.1, Message Envelope, for LDAP version 3) representing the results that the client receives in response to requestMessage.

numReferrals: An unsigned integer indicating the number of consecutive referrals or continuation references the client has received when processing a given LDAP response ([RFC1777] section 2, Message Envelope, for LDAP version 2 and [RFC2251] section 4.1.11, Referral, for LDAP version 3). It is initialized to zero.

requestTimer: A timer with second granularity used to track how long the client has waited for a response to requestMessage.

numResends: An unsigned integer indicating the number of times this request has been resent by the Autoreconnecting to a Directory Server (section 7.6.2.7) task. It is initialized to 0.

ConnectionInfo: A structure that tracks a TCP connection to a directory server. It has the following elements:

networkConnection: An abstract element representing a TCP connection ([RFC793] section 1.5, Operation) to the directory server. It is initialized to NULL.

portNumber: An unsigned integer indicating the TCP port number ([RFC793] section 1.5, Operation) to use when connecting to the directory server.

targetName: A null-terminated string used to locate a directory server. It can be NULL, indicating that the directory server for the joined domain SHOULD be located, a domain name (DNS/NetBIOS), a host name, or an IP address.

bindHasHappened: A Boolean flag indicating whether an LDAP bind has been successfully performed on this connection. The default value is FALSE.

pingRetries: An unsigned integer indicating the number of consecutive ICMP echo requests or "pings" ([RFC792]) the client has sent to the directory server but for which it has not received a response. It is initialized to 0.

pingKeepaliveTimer: A timer with second granularity used to track how long it has been since the client last received a response to any request on this connection.

pendingRequestList: A list of LDAPRequest elements representing all outstanding requests on this connection. It is initialized to NULL.

AuthInfo: A structure that is used to authenticate to the directory server. It has the following elements:

bindMethod: The bind method that will be used to authenticate to the directory server. See section 5.1.1.1 (Supported Authentication Methods) for a list of supported bind methods.

name: A string containing the user name of the credentials that will be used to authenticate to the directory server. When this string is set to NULL or is not set, use the identity of the protocol or system that is using the LDAP client.

password: A string containing the password of the credentials that will be used to authenticate to the directory server. When this string is set to NULL or is not set, use the identity of the protocol or system that is using the LDAP client.