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
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
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
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
, orLKLdapSearchScopeChildren
.
- 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 toNO
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
, orLKLdapSearchScopeChildren
.
- 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 toNO
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 toNO
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