Skip to content

LDAP function reference

KxSystems/ldap

.ldap LDAP interface

bind Synchronous bind to authenticate client err2string String description of an LDAP error code getGlobalOption Get global LDAP option getOption Get session LDAP option init Initialize session with LDAP server connection details search Synchronous search for partial or complete copies of entries setOption Set session LDAP option setGlobalOption Set global LDAP option unbind Synchronous unbind from the directory

.ldap.bind

Synchronous bind to authenticate client

.ldap.bind[sess;opts]

Where

  • sess is an int or long that represents the session previously created via .ldap.init
  • opts is a generic null or a dictionary of non-default options for the bind operation

binds to the session and returns a result code and server credentials as a dictionary.

Synchronous bind operations are used to authenticate clients (and the users or applications behind them) to the directory server, to establish an authorization identity that will be used for subsequent operations processed on that connection, and to specify the LDAP protocol version that the client will use.

The LDAP bind operation

Valid opts entries:

name type content default
dn string or symbol user to authenticate Anonymous simple authentication. (Typical for SASL authentication as most SASL mechanisms identify the target account within the encoded credentials.)
cred char/byte list or symbol LDAP credentials, e.g. password Assume no password required.
mech string or symbol SASL mechanism for authentication LDAP_SASL_SIMPLE

Query the attribute supportedSASLMechanisms from the server’s rootDSE for the list of SASL mechanisms the server supports.

Result dictionary:

key type content
ReturnCode integer result code
Credentials byte array credentials returned by the server

Empty for LDAP_SASL_SIMPLE; for other SASL mechanisms, the credentials may need to be used with other security-related functions, which may be external to LDAP.

Security mechanisms

// Complete a default bind to the server
q).ldap.bind[0i;::]
ReturnCode | 0i
Credentials| `byte$()

// Complete a bind to the server with non default parameters
q).ldap.bind[0i;enlist[`dn]!enlist `Tom]
ReturnCode | 0i
Credentials| `byte$()

.ldap.err2string

String description of an LDAP result code

.ldap.err2string[err]

Where err is an integer LDAP result code, returns its string representation.

Result codes are negative for an API error, 0 for success, and positive for a LDAP error.

Result codes

q).ldap.err2string[0]
"Success"
q).ldap.err2string[-9]
"Bad parameter to an ldap routine"
q).ldap.err2string[5]
"Compare False"

.ldap.getGlobalOption

Get global LDAP option

.ldap.getGlobalOption[option]

Where option (symbol) is the option to get, returns its value.

q).ldap.getGlobalOption[`LDAP_OPT_PROTOCOL_VERSION]
,3
q).ldap.getGlobalOption[`LDAP_OPT_X_TLS_REQUIRE_CERT]
,3

.ldap.getOption

Get session LDAP option

.ldap.getOption[sess;option]

Where

  • sess (int or long) is the session previously created with .ldap.init
  • option (symbol) is the option to get

returns the value for option.

q).ldap.getOption[0i;`LDAP_OPT_PROTOCOL_VERSION]
,3
q).ldap.getOption[0i;`LDAP_OPT_NETWORK_TIMEOUT]
30000

ldap_set_option

.ldap.init

Initialize the session with LDAP server connection details

.ldap.init[sess;uris]

Where

  • sess (int or long) is the session ID: unique for each session you initialize
  • uris (symbol list) URIs in the format schema://host:port

returns 0i if successful, otherwise an LDAP error code.

Values for schema: ldap, ldaps, ldapi or cldap.

Connection occurs on first operation: init does not create a connection.

Use unbind to free the session, after which the session ID can be reused.

ldap_initialize

// successfully execute initialization
q).ldap.init[0i;enlist `$"ldap://0.0.0.0:389"]
0i

// attempt to initialize with an incorrect 'schema'
q).ldap.init[1i;enlist `$"noldap://0.0.0.0:389"]
-9i

// retrieve error message for above error code
q).ldap.err2string[-9i]
"Bad parameter to an ldap routine"

.ldap.search

Synchronous search for partial or complete copies of entries

.ldap.search[sess;scope;filter;opts]

Where

  • sess (int or long) is a session ID previously created with .ldap.init
  • scope (int long) is the scope of the search
  • filter (string or symbol) is the filter to be applied
  • opts is the generic null or a dictionary of non-default options for the search

returns results as a dictionary.

Search options (opts):

name type content default
baseDn string or symbol base of the subtree to search from search from the root (or when a DN is not known)
attr symbol list attributes to include in the result * (all user attributes)
attrsOnly int or long return both attribute descriptions and values unless +ve, when return only descriptions both
timeLimit int or long number of microseconds to wait for a result 0 (no limit)

The server may impose its own limit.
sizeLimit int or long max number of entries to return 0 (no limit)

The server may impose its own limit.

Special attr values: include in results

*     all user attributes
+     all operational attributes
1.1   no attributes

Some servers may also support the ability to use the @ symbol followed by an object class name (e.g. @inetOrgPerson) to request all attributes associated with that object class.

Result dictionary:

key type explanation
ReturnCode integer result code
Entries table DNs and attribute dictionaries
Referrals list list of strings providing the referrals that can be searched to gain access to the required info (if server supports referrals) 
// Run a blind/default search at base level
q)session:0i
q)scope  :.ldap.LDAP_SCOPE_BASE
q)filter :"(objectClass=*)"
q).ldap.search[session;scope;filter;::]
ReturnCode| 0i
Entries   | +`DN`Attributes!(,"";,(,`objectClass)!,("top";"OpenLDAProotDSE"))
Referrals | ()

// Run a non default search
q)session:0i
q)scope  :.ldap.LDAP_SCOPE_SUBTREE
q)filter :"(cn=Amy Wong)"
q)options:`baseDN`attr!(`$"ou=people,dc=planetexpress,dc=com";`mail`givenName)
q).ldap.search[session;scope;filter;options]
ReturnCode| 0i
Entries   | +`DN`Attributes!(,"cn=Amy Wong+sn=Kroker,ou=people,dc=planetexpress,dc=com";,`givenName`mail!(,"Amy";,"amy@planetexpress.com"))
Referrals | ()

.ldap.setGlobalOption

Set global LDAP option

.ldap.setGlobalOption[option;value]

Where

  • option (symbol) is the option to set
  • value is the value to set for it

returns 0i if successful, otherwise an LDAP error code.

q).ldap.setGlobalOption[0i;`LDAP_OPT_X_TLS_REQUIRE_CERT;3]
0i
q).ldap.setGlobalOption[0i;`LDAP_OPT_NETWORK_TIMEOUT ;30000]
0i

LDAP handles inherit their default settings from the global options in effect at the time the handle is created, i.e. if a global setting is made, all sessions initialized after that will inherit those settings but not any sessions created prior.

.ldap.setOption

Set session LDSAP option

.ldap.setOption[sess;option;value]

Where

  • sess (int or long) is the session ID created with .ldap.init
  • option (symbol) is the option to set
  • value is the value to set for that option

returns 0i if successful, otherwise an LDAP error code.

ldap_set_option

q).ldap.setOption[0i;`LDAP_OPT_PROTOCOL_VERSION;3]
0i
q).ldap.setOption[0i;`LDAP_OPT_NETWORK_TIMEOUT ;30000]
0i

.ldap.unbind

Synchronous unbind from the directory, terminate the current association, and free resources

.ldap.unbind[sess]

Where sess (int or long) is the session ID created with .ldap.init, returns 0i if successful, otherwise a LDAP error code.

Invoke even if a session did not bind (or failed to bind), but had been initialized.

The session ID can be re-used when subsequently creating a new session with .ldap.init.

q).ldap.unbind[0i]
0i

Scope

LDAP_SCOPE_BASE      0  the specified entry and no subordinates
LDAP_SCOPE_ONELEVEL  1  immediate children of the specified entry;
                        not the entry itself, nor further subordinates
LDAP_SCOPE_SUBTREE   2  the specified entry and all subordinates
LDAP_SCOPE_CHILDREN  3  all of the subordinates

Get options

Options are listed by protocol.

ldap_get_option

LDAP

LDAP_OPT_API_FEATURE_INFO     dictionary
LDAP_OPT_API_INFO             dictionary
LDAP_OPT_CONNECT_ASYNC        integer
LDAP_OPT_DEBUG_LEVEL          integer
LDAP_OPT_DEREF                integer
LDAP_OPT_DESC                 integer
LDAP_OPT_DIAGNOSTIC_MESSAGE   string
LDAP_OPT_MATCHED_DN           string
LDAP_OPT_NETWORK_TIMEOUT      integer        timeout in microseconds
LDAP_OPT_PROTOCOL_VERSION     integer
LDAP_OPT_REFERRALS            integer
LDAP_OPT_RESULT_CODE          integer
LDAP_OPT_SIZELIMIT            integer
LDAP_OPT_TIMELIMIT            integer
LDAP_OPT_TIMEOUT              integer        timeout in microseconds

SASL

LDAP_OPT_X_SASL_AUTHCID      string
LDAP_OPT_X_SASL_AUTHZID      string
LDAP_OPT_X_SASL_MAXBUFSIZE   long
LDAP_OPT_X_SASL_MECH         string
LDAP_OPT_X_SASL_MECHLIST     string
LDAP_OPT_X_SASL_NOCANON      integer
LDAP_OPT_X_SASL_REALM        string
LDAP_OPT_X_SASL_SSF          long
LDAP_OPT_X_SASL_SSF_MAX      long
LDAP_OPT_X_SASL_SSF_MIN      long
LDAP_OPT_X_SASL_USERNAME     string

TCP

LDAP_OPT_X_KEEPALIVE_IDLE      integer
LDAP_OPT_X_KEEPALIVE_PROBES    integer
LDAP_OPT_X_KEEPALIVE_INTERVAL  integer

TLS

LDAP_OPT_X_TLS_CACERTDIR      string
LDAP_OPT_X_TLS_CACERTFILE     string
LDAP_OPT_X_TLS_CERTFILE       string
LDAP_OPT_X_TLS_CIPHER_SUITE   string
LDAP_OPT_X_TLS_CRLCHECK       integer
LDAP_OPT_X_TLS_CRLFILE        string
LDAP_OPT_X_TLS_DHFILE         string
LDAP_OPT_X_TLS_KEYFILE        string
LDAP_OPT_X_TLS_PROTOCOL_MIN   integer
LDAP_OPT_X_TLS_RANDOM_FILE    string
LDAP_OPT_X_TLS_REQUIRE_CERT   integer

Set options

The options are listed by protocol.

ldap_set_option

LDAP

LDAP_OPT_CONNECT_ASYNC       integer/long
LDAP_OPT_DEBUG_LEVEL         integer/long
LDAP_OPT_DEREF               integer/long    one of: .ldap.LDAP_DEREF_NEVER
                                                     .ldap.LDAP_DEREF_SEARCHING
                                                     .ldap.LDAP_DEREF_FINDING
                                                     .ldap.LDAP_DEREF_ALWAYS
LDAP_OPT_DIAGNOSTIC_MESSAGE  string/symbol
LDAP_OPT_NETWORK_TIMEOUT     integer/long    number of microseconds for timeout
LDAP_OPT_MATCHED_DN          string/symbol
LDAP_OPT_PROTOCOL_VERSION    integer/long
LDAP_OPT_REFERRALS           integer/long    .ldap.LDAP_OPT_ON or .ldap.LDAP_OPT_OFF
LDAP_OPT_RESULT_CODE         integer/long
LDAP_OPT_SIZELIMIT           integer/long
LDAP_OPT_TIMELIMIT           integer/long
LDAP_OPT_TIMEOUT             integer/long    number of microseconds for timeout

SASL

LDAP_OPT_X_SASL_MAXBUFSIZE    long
LDAP_OPT_X_SASL_NOCANON       integer/long
LDAP_OPT_X_SASL_SECPROPS      string/symbol
LDAP_OPT_X_SASL_SSF_EXTERNAL  long
LDAP_OPT_X_SASL_SSF_MAX       long
LDAP_OPT_X_SASL_SSF_MIN       long

TCP

LDAP_OPT_X_KEEPALIVE_IDLE      integer/long
LDAP_OPT_X_KEEPALIVE_PROBES    integer/long
LDAP_OPT_X_KEEPALIVE_INTERVAL  integer/long

TLS

LDAP_OPT_X_TLS_CACERTDIR      string/symbol
LDAP_OPT_X_TLS_CACERTFILE     string/symbol
LDAP_OPT_X_TLS_CERTFILE       string/symbol
LDAP_OPT_X_TLS_CIPHER_SUITE   string/symbol
LDAP_OPT_X_TLS_CRLCHECK       integer/long
LDAP_OPT_X_TLS_CRLFILE        string/symbol
LDAP_OPT_X_TLS_DHFILE         string/symbol
LDAP_OPT_X_TLS_KEYFILE        string/symbol
LDAP_OPT_X_TLS_NEWCTX         integer/long
LDAP_OPT_X_TLS_PROTOCOL_MIN   integer/long
LDAP_OPT_X_TLS_RANDOM_FILE    string/symbol
LDAP_OPT_X_TLS_REQUIRE_CERT   integer/long

Result codes

Code 0i indicates success.

q).ldap.err2string 0i
"Success"

LDAP errors

LDAP error codes are positive integers.

IANA result codes

API errors

API error codes are negative integers.

-1 LDAP_SERVER_DOWN LDAP library can't contact the LDAP server -2 LDAP_LOCAL_ERROR local error (failed dynamic memory allocation?) -3 LDAP_ENCODING_ERROR error encoding parameters for LDAP server -4 LDAP_DECODING_ERROR error decoding result from the LDAP server -5 LDAP_TIMEOUT time limit exceeded waiting for a result -6 LDAP_AUTH_UNKNOWN unknown authentication method specified -7 LDAP_FILTER_ERROR invalid filter specified to ldap_search e.g. unbalanced parentheses -8 LDAP_USER_CANCELLED user cancelled the operation -9 LDAP_PARAM_ERROR LDAP routine called with a bad parameter -10 LDAP_NO_MEMORY memory allocation call failed in LDAP library e.g. malloc(3) or other dynamic memory allocator -11 LDAP_CONNECT_ERROR connection problem -12 LDAP_NOT_SUPPORTED routine not called as supported by the library -13 LDAP_CONTROL_NOT_FOUND specified control unknown to the client library -14 LDAP_NO_RESULTS_RETURNED no results returned -16 LDAP_CLIENT_LOOP processing loop detected by library -17 LDAP_REFERRAL_LIMIT_EXCEEDED referral limit exceeded -18 LDAP_X_CONNECTING an async connect attempt is ongoing

Security mechanisms

LDAP supports a range of security mechanisms as part of the bind call. Check with your LDAP server admin what is supported for your system.

Often found in the root attribute supportedSASLMechanisms

Most of these checks are performed externally, in separate code related to your security mechanism.

For example, DIGEST_MD5 is initially performed by calling bind with no credentials, mech set to "DIGEST-MD5", and capturing the returned credential values from the server. Using the returned credentials to MD5-encode the user details, a second bind call is then made with the MD5-encoded details as the cred parameter. (Requires an additional MD5 library that is outside the scope of this interface.)

Examples: