LKLdap Class Reference

Inherits from	NSObject
Declared in	LKLdap.h LKLdap.m

Overview

LKLdap manges connections to remote directory servers and initiates LDAP requests.

Warning: The methods ldapDeleteDN:, ldapDeleteEntry:, ldapModifyDN:modification:, ldapModifyDN:modifications:, and ldapRenameDN:newRDN:newSuperior:deleteOldRDN: are presumed to be functional, but have not yet been tested.

Tasks

Object Management Methods

– init
Initialize a new object with default values and a private operation queue.
– initWithQueue:
Initialize a new object with default values and a shared operation queue.
– initWithQueue:andURL:
Initialize a new object with values from a LKUrl object and a shared operation queue.
– initWithURL:
Initialize a new object with values from a LKUrl object.

Server State

operationQueue
Returns the NSOperationQueue used to execute LDAP tasks.
property
isConnected
Returns a Boolean value indicating whether the object is connected to an LDAP server.
property

Server Information

ldapURI
The URL string used to initialize an LDAP connection.
property
ldapProtocolScheme
The protocol scheme used to initialize an LDAP connection.
property
ldapHost
The host name used to initialize an LDAP connection.
property
ldapPort
The port number used to initialize an LDAP connection.
property
ldapProtocolVersion
The protocol version used to initiate an LDAP connection.
property

Encryption Settings

ldapEncryptionScheme
The encryption method used to communicate with the LDAP server.
property
ldapCACertificateFile
The file name containing certificates of authorized certificate authorities.
property

Timeouts & Limits

ldapSearchSizeLimit
The maximum number of entries to be returned by a search operation.
property
ldapSearchTimeLimit
The time limit (in seconds) after which a search operation should be terminated by the server.
property
ldapNetworkTimeout
The network timeout value after which a connection fails due to no activity.
property

Authentication Credentials

ldapBindMethod
The method used to bind to a directory server.
property
ldapBindWho
The SASL user or distinguished name used when performing an authenticated bind.
property
ldapBindCredentials
The binary credentials used when performing an authenticated bind.
property
ldapBindCredentialsString
The credentials used when performing an authenticated bind.
property
ldapBindSaslMechanism
The SASL mechanism used when performing a SASL bind.
property
ldapBindSaslRealm
The SASL realm used when performing a SASL bind.
property

LDAP Tasks

– ldapBind
Initiates a bind request to the remote server.
– ldapDeleteDN:
Initiates a delete request for an LDAP DN.
– ldapDeleteEntry:
Initiates a delete request for an LDAP entry.
– ldapModifyDN:modification:
Initiats a modify request for an LDAP entry
– ldapModifyDN:modifications:
Initiats a modify request for an LDAP entry
– ldapSearchBaseDN:scope:filter:attributes:attributesOnly:
Performs an LDAP search operation on a single base DN.
– ldapSearchBaseDNList:scope:filter:attributes:attributesOnly:
Performs LDAP search operations on multiple base DNs.
– ldapRenameDN:newRDN:newSuperior:deleteOldRDN:
Initiates a renaming of an LDAP DN
– ldapSearchUrl:attributesOnly:
Performs an LDAP search operation using parameters from an LKUrl object.
– ldapRebind
Initiates a rebind request to the remote server.
– ldapUnbind
Initiates an unbind request to the remote server.

Properties

isConnected

Returns a Boolean value indicating whether the object is connected to an LDAP server.

@property (nonatomic, readonly) BOOL isConnected

Declared In

LKLdap.h

ldapBindCredentials

The binary credentials used when performing an authenticated bind.

@property (atomic, copy) NSData *ldapBindCredentials

Declared In

LKLdap.h

ldapBindCredentialsString

The credentials used when performing an authenticated bind.

@property (atomic, copy) NSString *ldapBindCredentialsString

Declared In

LKLdap.h

ldapBindMethod

The method used to bind to a directory server.

@property (atomic, assign) LKLdapBindMethod ldapBindMethod

Discussion

The default value is LKLdapBindMethodAnonymous. The following table describes the valid values for ldapBindMethod:

LKLdapBindMethod	Description
`LKLdapBindMethodAnonymous`	Perform an anonymous bind.
`LKLdapBindMethodSimple`	Perform a simple bind.
`LKLdapBindMethodSASL`	Perform a SASL bind.

Note: The value of ldapBindMethod is recalculated when the value of ldapBindWho, ldapBindSaslMechanism, or ldapBindSaslRealm is changed. The following is the matrix used to determine the calculated value of ldapBindMethod based upon the values of ldapBindWho, ldapBindSaslMechanism, and ldapBindSaslRealm.

LKLdapBindMethod	ldapBindWho	ldapBindSaslMechanism	ldapBindSaslRealm
`LKLdapBindMethodAnonymous`	`nil`	`nil`	`nil`
`LKLdapBindMethodSimple`	not `nil`	`nil`	`nil`
`LKLdapBindMethodSASL`	not `nil`	not `nil`	`nil` or not `nil`
`LKLdapBindMethodSASL`	not `nil`	`nil` or not `nil`	not `nil`

Declared In

LKLdap.h

ldapBindSaslMechanism

The SASL mechanism used when performing a SASL bind.

@property (atomic, copy) NSString *ldapBindSaslMechanism

Discussion

Note: Changing the value of ldapBindWho will cause the value of ldapBindMethod to be updated. The logic used to calculate the new value is documented with ldapBindMethod.

Warning: Currently only DIGEST-MD5 and CRAM-MD5 are supported on iOS.

Declared In

LKLdap.h

ldapBindSaslRealm

The SASL realm used when performing a SASL bind.

@property (atomic, copy) NSString *ldapBindSaslRealm

Discussion

Note: Changing the value of ldapBindWho will cause the value of ldapBindMethod to be updated. The logic used to calculate the new value is documented with ldapBindMethod.

Declared In

LKLdap.h

ldapBindWho

The SASL user or distinguished name used when performing an authenticated bind.

@property (atomic, copy) NSString *ldapBindWho

Discussion

Note: Changing the value of ldapBindWho will cause the value of ldapBindMethod to be updated. The logic used to calculate the new value is documented with ldapBindMethod.

Declared In

LKLdap.h

ldapCACertificateFile

The file name containing certificates of authorized certificate authorities.

@property (atomic, copy) NSString *ldapCACertificateFile

Discussion

The data contained within this file must be in PEM format. This value is only used when establishing a new TLS or SSL connection. The default for Mac OS X is to use the system’s list of authorized certificate authorities.

Warning: iOS does not have a default value for ldapCACertificateFile. In order to use TLS or SSL on iOS, this property must be set to a file name which contains valid certificates.

Declared In

LKLdap.h

ldapEncryptionScheme

The encryption method used to communicate with the LDAP server.

@property (atomic, assign) LKLdapEncryptionScheme ldapEncryptionScheme

Discussion

LKLdap supports TLS and SSL connections. The default value is LKLdapEncryptionSchemeAttemptTLS. The following table describes the valid values for ldapEncryptionScheme:

LKLdapEncryptionScheme	Description
LKLdapEncryptionSchemeNone	Do not use encryption.
LKLdapEncryptionSchemeAttemptTLS	Attempt to use TLS, but allow unencrypted connections if TLS is unavailable.
LKLdapEncryptionSchemeTLS	Require TLS when establishing a connection.
LKLdapEncryptionSchemeSSL	Require SSL when establishing a connection.

Warning: Changes to this property do not affect active LDAP connections. The -rebind method must be called before changes will take affect.

Declared In

LKLdap.h

ldapHost

The host name used to initialize an LDAP connection.

@property (atomic, copy) NSString *ldapHost

Discussion

The default value is @"localhost".

Warning: Changes to this property do not affect active LDAP connections. The -rebind method must be called before changes will take affect.

Declared In

LKLdap.h

ldapNetworkTimeout

The network timeout value after which a connection fails due to no activity.

@property (atomic, assign) NSInteger ldapNetworkTimeout

Discussion

Setting the value to -1 results in an infinite timeout, which is the default.

Declared In

LKLdap.h

ldapPort

The port number used to initialize an LDAP connection.

@property (atomic, assign) NSInteger ldapPort

Discussion

The default value is 389.

Warning: Changes to this property do not affect active LDAP connections. The -rebind method must be called before changes will take affect.

Declared In

LKLdap.h

ldapProtocolScheme

The protocol scheme used to initialize an LDAP connection.

@property (atomic, assign) LKLdapProtocolScheme ldapProtocolScheme

Discussion

LKLdap can be used to initate connections using LDAP, LDAPS, and LDAPI. The default value is LKLdapProtocolSchemeLDAP.

LKLdapProtocolScheme	Description
`LKLdapProtocolSchemeLDAP`	Use either no validation or TLS when connecting to the directory server.
`LKLdapProtocolSchemeLDAPS`	Use SSL when connecting to the directory server.
`LKLdapProtocolSchemeLDAPI`	Use a UNIX domain socket when connecting to the directory server.

Warning: Changes to this property do not affect active LDAP connections. The -rebind method must be called before changes will take affect.

Declared In

LKLdap.h

ldapProtocolVersion

The protocol version used to initiate an LDAP connection.

@property (atomic, assign) LKLdapProtocolVersion ldapProtocolVersion

Discussion

LKLdap supports LDAPv2 and LDAPv3. The default value is LKLdapProtocolVersion3.

LKLdapProtocolVersion	Description
LKLdapProtocolVersion2	Use LDAPv2 (RFC 1777).
LKLdapProtocolVersion3	Use LDAPv3 (RFC 4510).

Warning: Changes to this property do not affect active LDAP connections. The -rebind method must be called before changes will take affect.

Declared In

LKLdap.h

ldapSearchSizeLimit

The maximum number of entries to be returned by a search operation.

@property (atomic, assign) NSInteger ldapSearchSizeLimit

Declared In

LKLdap.h

ldapSearchTimeLimit

The time limit (in seconds) after which a search operation should be terminated by the server.

@property (atomic, assign) NSInteger ldapSearchTimeLimit

Declared In

LKLdap.h

ldapURI

The URL string used to initialize an LDAP connection.

@property (atomic, copy) NSString *ldapURI

Discussion

The default value is @"ldap://localhost/".

Note: Updating ldapURI will update the values of ldapProtocolScheme, ldapHost, ldapPort, and ldapEncryptionScheme.

The following table shows the values which will be assigned to ldapProtocolScheme and ldapEncryptionScheme for a given URI scheme.

URI Scheme	Protocol Scheme	Encryption Scheme
ldap://	`LKLdapProtocolSchemeLDAP`	`LKLdapEncryptionSchemeAttemptTLS`
ldaps://	`LKLdapProtocolSchemeLDAPS`	`LKLdapEncryptionSchemeSSL`
ldapi://	`LKLdapProtocolSchemeLDAPI`	`LKLdapEncryptionSchemeNone`

Warning: Changes to this property do not affect active LDAP connections. The ldapRebind method must be called before changes will take affect.

Declared In

LKLdap.h

operationQueue

Returns the NSOperationQueue used to execute LDAP tasks.

@property (nonatomic, readonly) NSOperationQueue *operationQueue

Declared In

LKLdap.h

Instance Methods

init

Initialize a new object with default values and a private operation queue.

- (id)init

Declared In

LKLdap.h

initWithQueue:

Initialize a new object with default values and a shared operation queue.

- (id)initWithQueue:(NSOperationQueue *)queue

Parameters

queue: The queue to use when executing LDAP tasks.

Declared In

LKLdap.h

initWithQueue:andURL:

Initialize a new object with values from a LKUrl object and a shared operation queue.

- (id)initWithQueue:(NSOperationQueue *)queue andURL:(LKUrl *)url

Parameters

queue: The queue to use when executing LDAP tasks.

url: The LKUrl object used to initialize the new LKLdap object.

Declared In

LKLdap.h

initWithURL:

Initialize a new object with values from a LKUrl object.

- (id)initWithURL:(LKUrl *)url

Parameters

url: The LKUrl object used to initialize the new LKLdap object.

Declared In

LKLdap.h

ldapBind

Initiates a bind request to the remote server.

- (LKMessage *)ldapBind

Return Value

Returns the LKMessage object executing the bind request.

Discussion

If not already connected to the remote server, this will cause a connection to be established prior to submitting the bind request.

Declared In

LKLdap.h

ldapDeleteDN:

Initiates a delete request for an LDAP DN.

- (LKMessage *)ldapDeleteDN:(NSString *)dn

Parameters

dn: The DN to be deleted.

Return Value

Returns the LKMessage object executing the delete request.

Discussion

Warning: This method has not been verified to function properly.

Declared In

LKLdap.h

ldapDeleteEntry:

Initiates a delete request for an LDAP entry.

- (LKMessage *)ldapDeleteEntry:(LKEntry *)entry

Parameters

entry: An LKEntry object of the DN to be deleted.

Return Value

Returns the LKMessage object executing the delete request.

Discussion

Warning: This method has not been verified to function properly.

Declared In

LKLdap.h

ldapModifyDN:modification:

Initiats a modify request for an LDAP entry

- (LKMessage *)ldapModifyDN:(NSString *)dn modification:(LKMod *)mod

Parameters

dn: The DN to be modified.

mod: An array of LKMod objects

Return Value

Returns the LKMessage object executing the modify request.

Discussion

Warning: This method has not been verified to function properly.

Declared In

LKLdap.h

ldapModifyDN:modifications:

Initiats a modify request for an LDAP entry

- (LKMessage *)ldapModifyDN:(NSString *)dn modifications:(NSArray *)mods

Parameters

dn: The DN to be modified.

mods: An array of LKMod objects

Return Value

Returns the LKMessage object executing the modify request.

Discussion

Warning: This method has not been verified to function properly.

Declared In

LKLdap.h

ldapRebind

Initiates a rebind request to the remote server.

- (LKMessage *)ldapRebind

Return Value

Returns the LKMessage object executing the rebind request.

Discussion

This will cause the current connection (if one exists) to be terminated and a new connection to be established.

Declared In

LKLdap.h

ldapRenameDN:newRDN:newSuperior:deleteOldRDN:

Initiates a renaming of an LDAP DN

- (LKMessage *)ldapRenameDN:(NSString *)dn newRDN:(NSString *)newrdn newSuperior:(NSString *)newSuperior deleteOldRDN:(NSInteger)deleteOldRDN

Parameters

dn: The DN to be renamed.

newrdn: The new relative DN of the entry.

newSuperior: The new superior DN of the entry. If this value is NULL, then only the relative DN is modified. The root DN is specified by passing a string with a length of zero @""

deleteOldRDN: If non-zero, delete the old relative DN attribute from the entry.

Return Value

Returns the LKMessage object executing the search request.

Discussion

Warning: This method has not been verified to function properly.

Declared In

LKLdap.h

ldapSearchBaseDN:scope:filter:attributes:attributesOnly:

Performs an LDAP search operation on a single base DN.

- (LKMessage *)ldapSearchBaseDN:(NSString *)base scope:(LKLdapSearchScope)scope filter:(NSString *)filter attributes:(NSArray *)attributes attributesOnly:(BOOL)attributesOnly

Parameters

base: The DN of the entry at which to start the search.

scope: The scope of the search and should be one of LKLdapSearchScopeBase, LKLdapSearchScopeOneLevel, LKLdapSearchScopeSubTree, or LKLdapSearchScopeChildren.

filter: The string representation of the filter to apply in the search.

attributes: An array of attribute descriptions to return from matching entries. The default is to return all attribute descriptions.

attributesOnly: The attrsonly parameter should be set to YES value if only attribute descriptions are wanted. It should be set to NO if both attributes descriptions and attribute values are wanted.

Return Value

Returns the LKMessage object executing the search request.

Declared In

LKLdap.h

ldapSearchBaseDNList:scope:filter:attributes:attributesOnly:

Performs LDAP search operations on multiple base DNs.

- (LKMessage *)ldapSearchBaseDNList:(NSArray *)bases scope:(LKLdapSearchScope)scope filter:(NSString *)filter attributes:(NSArray *)attributes attributesOnly:(BOOL)attributesOnly

Parameters

bases: An array of DNs of the entries at which to start the search.

scope: The scope of the search and should be one of LKLdapSearchScopeBase, LKLdapSearchScopeOneLevel, LKLdapSearchScopeSubTree, or LKLdapSearchScopeChildren.

filter: The string representation of the filter to apply in the search.

attributes: An array of attribute descriptions to return from matching entries. The default is to return all attribute descriptions.

attributesOnly

The attrsonly parameter should be set to YES value if only attribute descriptions are wanted. It should be set to NO if both attributes descriptions and attribute values are wanted.

If any one of the search operations generates an error, an error is reported for the entire request.

Return Value

Returns the LKMessage object executing the search request.

Declared In

LKLdap.h

ldapSearchUrl:attributesOnly:

Performs an LDAP search operation using parameters from an LKUrl object.

- (LKMessage *)ldapSearchUrl:(LKUrl *)url attributesOnly:(BOOL)attributesOnly

Parameters

url: The URL used to specify the search parameters.

attributesOnly: The attrsonly parameter should be set to YES value if only attribute descriptions are wanted. It should be set to NO if both attributes descriptions and attribute values are wanted.

Return Value

Returns the LKMessage object executing the search request.

Declared In

LKLdap.h

ldapUnbind

Initiates an unbind request to the remote server.

- (LKMessage *)ldapUnbind

Return Value

Returns the LKMessage object executing the unbind request.

Discussion

This will terminate the current connection (if one exists).

Declared In

LKLdap.h