| Sun Java System LDAP SDK for C Programming Guide |
Chapter 13
Working with LDAP ControlsThis chapter explains how Lightweight Directory Access Protocol (LDAP) controls work and how to use those controls that are supported by Sun™ Java System LDAP SDK for C. It includes the following sections:
How LDAP Controls WorkThe LDAPv3, as documented in RFC 2251 - Lightweight Directory Access Protocol (v3) (http://www.faqs.org/rfcs/rfc2251.html), allows clients and servers to use controls as a mechanism for extending an LDAP operation. A control is a way to specify additional information as part of a request and a response. For example, a client can send a control to a server as part of a search request to indicate that the server should sort the search results before sending the results back to the client.
A control specifies the following information:
- A unique object identifier (OID) as defined by the creator of the control. The OID identifies the control. Table 13-1 lists some common OIDs.
- An indication of whether or not the control is critical to the operation.
- Optional data related to the control. For example, the server-side sorting control needs the attributes that would be used for sorting search results.
When your client includes a control in a request for an LDAP operation, the server may respond in one of the following ways:
- If the server supports the control and if the control is appropriate to the operation, the server should make use of the control when performing the operation.
- If the server does not support the control type or if the control is not appropriate, the server should do one of the following:
- If the control is marked as critical to the operation, the server should not perform the operation and should instead return the result code LDAP_UNAVAILABLE_CRITICAL_EXTENSION.
- If the control is marked as not critical to the operation, the server should ignore the control and perform the operation.
Note
If you plan to use a control, you need to make sure that the server supports the control. See "Determining Supported Controls" for details.
Using Controls in the LDAP APIThe LDAP SDK for C supports two types of controls:
In the SDK, a control is represented by an LDAPControl structure.
The fields in this structure represent the data in a control:
- ldctl_oid specifies the OID of the control.
- ldctl_value contains a berval structure containing data associated with the control.
- ldctl_iscritical specifies whether or not the control is critical to the operation LDAP_OPT_ON indicates that the control is critical, and LDAP_OPT_OFF indicates that the control is not critical.
Code Example 13-1 is the LDAPControl structure definition. For more information on the LDAPControl structure, see Chapter 16, "Data Type Reference."
Code Example 13-1 Example of LDAPControl Structure
typedef struct ldapcontrol {
char *ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
} LDAPControl;
You can either allocate and create the control yourself, or you can call a function to create the control. For example, you can call the ldap_create_sort_control() function to create a server-sorting control. To include a control in a request, call one of the LDAPv3 API functions (functions with names ending with _ext and _ext_s). These functions allow you to pass in an array of server controls and an array of client controls.
To retrieve any controls included in a server’s response, call the ldap_parse_result() function. You can then retrieve data from the returned controls yourself (by checking the fields of the LDAPControl structure) or by calling additional functions (such as ldap_parse_sort_control()).
When you are done working with a control or with an array of controls, you should free them from memory by calling the ldap_control_free() function or the ldap_controls_free() function.
Determining Supported ControlsAccording to the LDAPv3, servers should list any controls that they support in the supportedControl attribute in the root DSE.
Note
See Chapter 10, "Retrieving Server Information" for information on the DSE.
Table 13-1 lists some of the OIDs for server controls that might be referenced in the supportedControl attribute.
Code Example 13-2 is a simple command-line program that searches for the root DSE and prints the values of the supportedControl attribute.
Using the Server-Side Sorting ControlThe control with the OID 1.2.840.113556.1.4.473 (or LDAP_CONTROL_SORTREQUEST, as defined in the ldap.h header file) is a server-side sorting control. When you send a search request with this control to the server, the server should sort the results before sending them back to you.
Note
The server-side sorting control is described in the Internet-Drafts file, RFC 2891 - LDAP Control Extension for Server Side Sorting of Search Results located at http://www.faqs.org/rfcs/rfc2891.html
Specifying the Sort Order
To specify the sort order of the results, call the ldap_create_sort_keylist() function to create a sort key list from a string in the following format:
[-]attrname[:matching_rule_oid] ...
Where:
- attrname is the name of the attribute that you want to sort by. You can specify a space-delimited list of attribute names.
- matching_rule_oid is the optional OID of a matching rule that you want to use for sorting. The minus sign indicates that the results should be sorted in reverse order for that attribute. For example, the following string specifies that results should be sorted by last name (sn) first in ascending order. If multiple entries have the same last name, these entries are sorted by first name (givenname) in descending order:
"sn -givenname"
Passing this string to ldap_create_sort_keylist() creates a sort key list, which is an array of LDAPsortkey structures. You can use this to create the server-side sorting control.
Creating the Control
Next, to create the server-side sorting control, you pass the sort key list (the array of LDAPsortkey structures) to the ldap_create_sort_control() function. The function passes back a newly created sort control, an LDAPControl structure, which you can include in a search request.
Note
You can specify whether or not the control is critical to the search operation. If the control is marked as critical and the server cannot sort the results, the server should not send back any entries. See "Interpreting the Results" for more information on the ramifications of marking the control as critical.
After you call the ldap_create_sort_control() function and create the control, you should free the array of LDAPsortkey structures by calling ldap_free_sort_keylist(). When you are done receiving sorted results from the server, you should free the LDAPControl structure by calling ldap_control_free().
Performing the Search
To specify that you want the server to sort the results, add the newly created server-sorting control to a NULL-terminated array of LDAPControl structures and pass this array to the ldap_search_ext() function or the ldap_search_ext_s() function. The server returns a result for the search operation and a response control. The response control indicates the success or failure of the sorting. To determine if sorting was successful:
- Call ldap_parse_result() to parse the result of the search operation and retrieve any response controls sent back from the server.
Response controls are passed back in a NULL-terminated array of LDAPControl structures.
- Pass this array of structures as an argument to ldap_parse_sort_control() to retrieve the LDAP result code for the sorting operation.
If the sorting operation fails, the server may also return the name of the attribute that caused the failure. The ldap_parse_sort_control() function also retrieves this name, if available.
- Free the array by calling the ldap_controls_free() function when you are done parsing the array of response controls.
The server can return the result codes detailed in Table 13-2.
Table 13-2 Server-side Sorting Result Codes
Result Code
Description
The results were sorted successfully.
An internal server error occurred.
The maximum time allowed for a search was exceeded before the server finished sorting the results.
The server refused to send back the sorted search results because it requires you to use a stronger authentication method.
There are too many entries for the server to sort.
The sort key list specifies an attribute that does not exist.
The sort key list specifies a matching rule that is not recognized or appropriate.
The server did not send the sorted results because the client has insufficient access rights.
The server is too busy to sort the results.
The server is unable to sort the results.
This general result code indicates that the server failed to sort the results for a reason other than the ones listed above.
Interpreting the Results
Table 13-3 lists the kinds of results to expect from the LDAP server under different situations.
Table 13-3 Server Responses to Sorting Controls
Does the Server Support the Sort Control?
Is the Sort Control Marked As Critical?
Other Conditions
Results from LDAP Server
No
Yes
N/A
The server does not send back any entries.
No
The server ignores the sorting control and returns the entries unsorted.
Yes
Yes
The server cannot sort the results using the specified sort key list.
The server does not send back any entries. It sends back the sorting response control, which specifies the result code of the sort attempt and (optionally) the attribute type that caused the error.
No
The server returns the entries unsorted. It sends back the sorting response control, which specifies the result code of the sort attempt and (optionally) the attribute type that caused the error.
N/A (may or may not be marked as critical)
The server successfully sorted the entries.
The server sends back the sorted entries. It sends back the sorting response control, which specifies the result code of the sort attempt (LDAP_SUCCESS).
The search itself failed (for any reason).
The server sends back a result code for the search operation. It does not send back the sorting response control.
Server-Sorting Control Sample Program
Code Example 13-3 uses the server-sorting control to get a list of all users in the directory, sorted in ascending order by last name, then in descending order by first name.
Code Example 13-3 Sample Program to Apply Server-sorting Control
#include <stdio.h>
#include "ldap.h"
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER 3890
int
main( int argc, char **argv )
{
LDAP *ld;
LDAPMessage *result, *e;
char *attrfail, *matched = NULL, *errmsg = NULL;
char **vals, **referrals;
int rc, parse_rc, version;
unsigned long rcode;
LDAPControl *sortctrl = NULL;
LDAPControl *requestctrls[ 2 ];
LDAPControl **resultctrls = NULL;
LDAPsortkey **sortkeylist;
/* Get a handle to an LDAP connection */
if ( (ld = ldap_init( HOSTNAME, PORTNUMBER ) ) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
/* Create a sort key list that specifies the sort order of the results.
Sort the results by last name first, then by first name. */
ldap_create_sort_keylist( &sortkeylist, "sn -givenname" );
/* Create the sort control. */
rc = ldap_create_sort_control( ld, sortkeylist, 1, &sortctrl );
if ( rc != LDAP_SUCCESS ) {
fprintf( stderr, "ldap_create_sort_control: %s\n", ldap_err2string( rc ) );
ldap_unbind( ld );
return( 1 );
}
requestctrls[ 0 ] = sortctrl;
requestctrls[ 1 ] = NULL;
/* Search for all entries in Sunnyvale */
rc = ldap_search_ext_s( ld, "dc=example,dc=com", LDAP_SCOPE_SUBTREE,
"(mail=*example.com*)", NULL, 0, requestctrls, NULL, NULL, 0, &result );
if ( rc != LDAP_SUCCESS ) {
fprintf( stderr, "ldap_search_ext_s: %s\n", ldap_err2string( rc ) );
ldap_unbind( ld );
return( 1 );
}
parse_rc = ldap_parse_result( ld, result, &rc, &matched, &errmsg, &referrals, &resultctrls, 0 );
if ( parse_rc != LDAP_SUCCESS ) {
fprintf( stderr, "ldap_parse_result: %s\n", ldap_err2string( parse_rc ) );
ldap_unbind( ld );
return( 1 );
}
if ( rc != LDAP_SUCCESS ) {
fprintf( stderr, "ldap_search_ext_s: %s\n", ldap_err2string( rc ) );
if ( errmsg != NULL && *errmsg != '\0' ) {
fprintf( stderr, "%s\n", errmsg );
}
ldap_unbind( ld );
return( 1 );
}
parse_rc = ldap_parse_sort_control( ld, resultctrls, &rcode, &attrfail );
if ( parse_rc != LDAP_SUCCESS ) {
fprintf( stderr, "ldap_parse_sort_control: %s\n", ldap_err2string( parse_rc ) );
ldap_unbind( ld );
return( 1 );
}
if ( rcode != LDAP_SUCCESS ) {
fprintf( stderr, "Sort error: %s\n", ldap_err2string( rcode ) );
if ( attrfail != NULL && *attrfail != '\0' ) {
fprintf( stderr, "Bad attribute: %s\n", attrfail );
}
ldap_unbind( ld );
return( 1 );
}
/* for each entry print out name + all attrs and values */
for ( e = ldap_first_entry( ld, result ); e != NULL;
e = ldap_next_entry( ld, e ) ) {
if ((vals = ldap_get_values( ld, e, "sn")) != NULL ) {
if ( vals[0] != NULL ) {
printf( "%s", vals[0] );
}
ldap_value_free( vals );
}
if ((vals = ldap_get_values( ld, e, "givenname")) != NULL ) {
if ( vals[0] != NULL ) {
printf( "\t%s", vals[0] );
}
ldap_value_free( vals );
}
printf( "\n" );
}
ldap_msgfree( result );
ldap_free_sort_keylist( sortkeylist );
ldap_control_free( sortctrl );
ldap_controls_free( resultctrls );
ldap_unbind( ld );
return( 0 );
}
Using the Persistent Search ControlThe control with the OID 2.16.840.1.113730.3.4.3 (or LDAP_CONTROL_PERSISTENTSEARCH as defined in the ldap.h header file) is the persistent search control. A persistent search is an ongoing search operation that allows your LDAP client to get notification of changes to the directory.
Note
The persistent search control is described in the Internet-Drafts file, Persistent Search: A Simple LDAP Change Notification Mechanism located at http://www.ietf.org/proceedings/01mar/I-D/ldapext-psearch-03.txt.
To use persistent searching for change notification, you create a persistent search control that specifies the types of changes that you want to track. You include the control in a search request. If an entry in the directory is changed, the server determines if the entry matches the search criteria in your request and if the change is the type of change that you are tracking. If both of these are true, the server sends the entry to your client.
To create a persistent search control, call ldap_create_persistentsearch_control() as illustrated in Code Example 13-4.
Code Example 13-4 Calling ldap_create_persistentsearch_control()
int ldap_create_persistentsearch_control( LDAP *ld,
int changetypes, int changesonly, int return_echg_ctls,
char ctl_iscritical, LDAPControl **ctrlp );
You can specify the following information:
- changetypes specifies the type of change you want to track. You can specify any of the following (or any combination of the following using a bitwise OR operator):
- LDAP_CHANGETYPE_ADD indicates that you want to track added entries.
- LDAP_CHANGETYPE_DELETE indicates that you want to track deleted entries.
- LDAP_CHANGETYPE_MODIFY indicates that you want to track modified entries.
- LDAP_CHANGETYPE_MODDN indicates that you want to track renamed entries.
- LDAP_CHANGETYPE_ANY indicates that you want to track all changes to entries.
- changesonly indicates whether or not you want the server to return all entries that initially matched the search criteria (0 to return all entries, or non-zero to return only the entries that change).
- return_echg_ctls indicates whether or not you want entry change notification controls included with every modified entry returned by the server (non-zero to return entry change notification controls).
Note
You can use this control in conjunction with an "entry change notification" control. See "Using the Entry Change Notification Control" for details.
The function passes back an LDAPControl structure representing the control in the ctrlp parameter. You can add the newly created control to a NULL-terminated array of LDAPControl structures and pass this array to the ldap_search_ext() function.
To end the persistent search, you can either call the ldap_abandon_ext() function to abandon the search operation, or you can call the ldap_unbind() function to disconnect from the server.
Note
For an example detailing how to perform a persistent search, refer to the example provided with the LDAP SDK for C in DSRK_base/lib/ldapcsdk/examples called psearch.c.
Using the Entry Change Notification ControlThe control with the OID 2.16.840.1.113730.3.4.7 (or LDAP_CONTROL_ENTRYCHANGE, as defined in the ldap.h header file) is the "entry change notification" control. This control contains additional information about the change made to the entry, including the type of change made, the change number (which corresponds to an item in the server’s change log, if the server supports a change log), and, if the entry was renamed, the old DN of the entry.
You use this control in conjunction with a persistent search control. If you have specified the preference for returning entry change notification controls, the server includes an entry change notification control with each entry found by the search. To retrieve and parse an entry change notification control included with an entry:
- Pass the LDAPMessage structure that represents an entry to the ldap_get_entry_controls() function.
- Pass the entry change notification control to the ldap_parse_entrychange_control() function.
For more information, see "Using the Persistent Search Control".
Using the Virtual List View ControlThe control with the OID 2.16.840.1.113730.3.4.9 (or LDAP_CONTROL_VLVREQUEST, as defined in the ldap.h header file) is a virtual list view control. When you send a search request with this control and a server-side sorting control to the server, the server should sort the results and return the specified subset of entries back to your client.
Note
The virtual list view control is described in the Internet-Drafts file, LDAP Extensions for Scrolling View Browsing of Search Results located at http://www.ietf.org/proceedings/01mar/I-D/ldapext-ldapv3-vlv-04.txt.
Using the Manage DSA IT ControlThe control with the OID 2.16.840.1.113730.3.4.2 (or LDAP_CONTROL_MANAGEDSAIT, as defined in the ldap.h header file) is the manage DSA IT control. You can use this control to manage search references in the directory. To create this control, create an LDAPControl structure and set the ldctl_oid field to 2.16.840.1.113730.3.4.2.
When you add this control to the array of LDAPControl structures that you pass to a function (for example, ldap_search_ext() or ldap_modify_ext(), the server treats search references as ordinary entries. Rather than returning a reference to you, the server returns the entry containing the reference. This allows your client application to manage search references in the directory.
Note
The manage DSA IT control is described in the Internet-Drafts file, RFC 2891 - LDAP Control Extension for Server Side Sorting of Search Results located at http://www.faqs.org/rfcs/rfc2891.html
Using Password Policy ControlsSun Java System Directory Server uses two server response controls to send information back to a client after an LDAP bind operation:
- The control with the OID 2.16.840.1.113730.3.4.4 (or LDAP_CONTROL_PWEXPIRED, as defined in the ldap.h header file) is the expired password control. It is used if the server is configured to require users to change their passwords when first logging in and whenever their password has been reset. If the user is logging in for the first time or their password has been reset, the server sends this control to indicate that the client needs to change the password immediately. At this point, the only operation that the client can perform is to change the user’s password. If the client requests any other operation, the server sends back an LDAP_UNWILLING_TO_PERFORM result code with an expired password control.
- The control with the OID 2.16.840.1.113730.3.4.5 (or LDAP_CONTROL_PWEXPIRING, as defined in the ldap.h header file) is the password expiration warning control. This control is used if the server is configured to expire user passwords after a certain amount of time. The server sends this control back to the client if the client binds using a password that will soon expire. The ldctl_value field of the LDAPControl structure specifies the number of seconds before the password will expire.
To get these server response controls when binding, you can:
- Call ldap_simple_bind() to send a request for an asynchronous bind operation.
- Call ldap_result() to get the results of the operation.
- Call ldap_parse_result() to parse the result and retrieve the server response controls from the result as an array of LDAPControl structures.
You can then check the ldctl_oid field to determine the OID of the control and the ldctl_value field for any data included in the control.
Using the Proxied Authorization ControlProxied authorization is an extension to the LDAPv3 that allows a bound client to assume the identity of another directory entity without rebinding. This allows the client to perform operations as if it were bound as the proxied directory entity. All directory access (read, write, search, compare, delete, and add) is supported by proxied authorization. For example, suppose a client is bound as uid=bjensen,ou=Engineering,dc=example,dc=com. bjensen does not have the right to search the ou=Marketing,dc=example,dc=com tree. However, uid=lboyd,ou=Marketing,dc=example,dc=com does have rights to search the Marketing tree and, lboyd grants proxy rights to bjensen. In this case, bjensen may bind as herself, assume the identity of lboyd, and then search the Marketing tree.
This feature is intended as a performance and administrative benefit for certain types of directory usage. Specifically, applications that want to allow many clients to access or modify specific directory data without rebinding as another directory entity may want to use this feature.
Caution
Be aware that other directory servers might not support this feature. Sun Java System Directory Server access control (including the proxy right) is fully described in the Sun ONE Directory Server Administration Guide located at http://docs.sun.com/doc/816-6698-10.
The Proxy Right
Proxied authorization adds an additional access right: proxy. If an entry grants the proxy right, then the entity to which that right is granted may assume the identity of the granting entity. For example, if you wanted to allow uid=bjensen the right to proxy as uid=lboyd, add the Proxy Right access control instruction (ACI) illustrated in Code Example 13-5 to your directory. This ACI allows bjensen to assume the identity of lboyd for all directory operations giving bjensen the permission to do to the directory whatever lboyd has permission to do.
Code Example 13-5 Proxy Right ACI
aci: (target = "ldap:///uid=lboyd,ou=Marketing,dc=example,dc=com")
(targetattr=*)
(version 3.0; aci "grant bjensen the right to proxy as lboyd";
allow(proxy) userdn="ldap:///uid=bjensen,ou=Engineering,dc=example,dc=com";)
The Proxied Authorization Control
To support proxied authorization (an extension to the LDAPv3), the proxy authorization control has been added to the LDAP SDK for C in the form of the ldap_create_proxyauth_control() function. You use this function to create the control that allows a bound entity to assume the identity of another directory entry.
Proxy authorization is an optional LDAP server feature; it may not be supported on all LDAP servers. You should call the proxy authorization control function only when interacting with LDAP servers that support this LDAPv3 extension. You can check on the support of this control by looking at the rootDSE supportedControl attrubute. For example, the following command uses the ldapsearch utility to display the rootDSE:
ldapsearch -v -h hostname -p 389 -b ““ -s base ““
In order for the control to work, the LDAP server that you are connecting to must support the server control for proxied authorization (OID 2.16.840.1.113730.3.4.12, or LDAP_CONTROL_PROXYAUTH as defined in the ldap.h header file).
Proxy Authorization Sample Program
Code Example 13-6 creates an LDAP connection, sets the proxied authorization control, binds to the directory, and then performs a search operation using the proxied authorization control. A more complete example is also available with the SDK example files located in DSRK_base/lib/ldapcsdk/examples.
Code Example 13-6 Proxied Authorization Control Example
#include <ldap.h>
int version;
LDAP *ld;
LDAPControl *requestctrls[ 2 ];
LDAPControl *pactrl = NULL;
/* Customize the following host and bind information for your site. */
int port=389;
char *host="directory.example.com";
char *baseDN="dc=example,dc=com";
/* Proxied auth specific information.
proxyDN is the entity that will be proxied.
bindDN and bindpw is for the bind entity that will use the proxyDN. */
char *proxyDN = "uid=lboyd,ou=marketing,dc=example,dc=com";
char *bindDN = "uid=bjensen,ou=engineering,dc=example,dc=com";
char *bindpw = "password";
/* Do general LDAP init stuff */
/* Get a handle to an LDAP connection */
if ( (ld = ldap_init( host, port ) ) == NULL ) {
printf("ldap_init did not return a conn handle.\n");
return;
}
/* set version to ldap version 3 */
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
/* authenticate to the directory */
if ( ldap_simple_bind_s( ld, bindDN, bindpw ) != LDAP_SUCCESS ) {
printf("ldap_simple_bind_s failed");
return (-1);
}
/* create the proxied authorization control */
if ( ldap_create_proxyauth_control( ld, proxyDN, 1, &pactrl ) ) {
printf("ldap_create_proxyauth_control failed.\n");
if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {
printf("ldap_unbind failed\n");
}
return(-1);
}
requestctrls[ 0 ] = pactrl;
requestctrls[ 1 ] = NULL;
/* Perform the search using the control */
printf("Searching for %s with the proxy auth control.\n", proxyDN);
if ( ldap_search_ext_s( ld, proxyDN, LDAP_SCOPE_SUBTREE, "(objectclass=*)",
NULL, 0, requestctrls, NULL, NULL, LDAP_NO_LIMIT, &results ) !=
LDAP_SUCCESS ) {
printf("ldap_search_ext failed.\n");
printf("Something is wrong with proxied auth.\n");
} else {
print_search_results(ld, results);
}
