From: Kurt Zeilenga Date: Tue, 4 May 1999 04:25:18 +0000 (+0000) Subject: Relevant drafts... X-Git-Tag: OPENLDAP_SLAPD_BACK_LDAP~84 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=d00b31bbd1b712ce5d664db11b68fc15a19a46b6;p=openldap Relevant drafts... --- diff --git a/doc/drafts/draft-ietf-ldapext-acl-model-02.txt b/doc/drafts/draft-ietf-ldapext-acl-model-02.txt new file mode 100644 index 0000000000..f390148bef --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-acl-model-02.txt @@ -0,0 +1,2440 @@ + + + + + + + + Internet-Draft E. Stokes + LDAP Extensions WG D. Byrne + Intended Category: Standards Track B. Blakley + Expires: 15 October 1999 IBM + 15 April 1999 + + Access Control Model for LDAP + + + STATUS OF THIS MEMO + + This document is an Internet-Draft and is in full + conformance with all provisions of Section 10 of RFC2026. + + Internet-Drafts are working documents of the Internet + Engineering Task Force (IETF), its areas, and its working + groups. Note that other groups may also distribute + working documents as Internet-Drafts. Internet-Drafts are + draft documents valid for a maximum of six months and may + be updated, replaced, or obsoleted by other documents at + any time. It is inappropriate to use Internet- Drafts as + reference material or to cite them other than as "work in + progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be + accessed at http://www.ietf.org/shadow.html. + + Comments and suggestions on this document are encouraged. + Comments on this document should be sent to the LDAPEXT + working group discussion list: + + ietf-ldapext@netscape.com + + ABSTRACT + + This document describes the access control model for the + Lightweight Directory Application Protocol (LDAP) + directory service. It includes a description of the + model, the LDAP controls, and the extended operations to + the LDAP protocol. A separate document defines the + corresponding application programming interfaces (APIs). + RFC2219 [Bradner97] terminology is used. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 1] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 1. Introduction + + The ability to securely access (replicate and distribute) + directory information throughout the network is necessary + for successful deployment. LDAP's acceptance as an + access protocol for directory information is driving the + need to provide an access control model definition for + LDAP directory content among servers within an enterprise + and the Internet. Currently LDAP does not define an + access control model, but is needed to ensure consistent + secure access across heterogeneous LDAP implementations. + The major objective is to provide a simple, but secure, + highly efficient access control model for LDAP while also + providing the appropriate flexibility to meet the needs + of both the Internet and enterprise environments and + policies. This document defines the model and the + protocol extensions (controls and extended operations). + A separate document defines the corresponding application + programming interfaces (APIs). + + + 2. Overview + + Access Control mechanisms evaluate requests for access to + protected resources and make decisions about whether + those requests should be granted or denied. In order to + make a grant/deny decision about a request for access to + a protected resource, an access control mechanism needs + to evaluate policy data. This policy data describes + security-relevant characteristics of the requesting + subject and the rules which govern the use of the target + object. + + This proposal defines the protocol elements for + transmission of this access control policy data in an + LDAP environment and an attribute that defines the access + control mechanism in effect for a given part of the LDAP + namespace. The instantiation of an access control model + at the directory server is not defined in this document. + By defining only what flows on the wire allows existing + access control mechanisms to be used at the directory + server. + + No mechanisms are defined in this document to control + access to access control information or for storage of + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 2] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + access control information at the server; this is vendor + dependent. + + A separate requirements document for access control + exists. The access control model used the requirements + documents as a guideline for the development of this + specification and are reflected in this specification to + the extent that the working group could agree on an + access control model. + + The access control model defines + + - A wire protocol for interoperability: The existing + LDAP protocol flows for add, delete, modify, etc are + used to manipulate access control information. + There are additional LDAP controls and extended + protocol operations defined to further help + management of access control information: + getEffectiveRights, listSubjectRights, and + specifyCredentials. + + - LDAP Directory Interchange Format (LDIF) for + application portability: The LDIF is defined for + access control information (ACI). This LDIF is also + used as input to the LDAP APIs so access control + information can be addressed uniformly independent + of how that information is stored and addressed at + the server. + + - A set of attributes to identity the access control + mechanisms supported by a server. + + Encoding of access control information on the wire is per + the LDAPv3 specifications. + + + 3. Terminology + + An "access control list" contains the access control + policy information controlling access to an object or + collection of objects. An access control list consists + of a set of access control list entries. + + An "access control list entry" defines a single subject + security attribute's granted rights for the objects + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 3] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + governed by the access control list to which it belongs. + + The "access control policy information" (acpi) for an + object or a collection of objects defines which subject + security attributes entitle a subject to which granted + rights. The access control policy information for an + object is stored in an access control list. + + An "access decision" is a boolean-valued function which + answers the question: "can the subject with these subject + security attributes perform this operation on this + object?" + + An "access decision function" is an algorithm which makes + an access decision based on subject security attributes, + access control policy information, an object identifier, + and an operation name (possibly augmented by additional + contextual information). + + An "access decision function interface" is a programmatic + interface through which applications can request an + access decision. + + An "access identity" is an identity which is used by an + access decision function to make an access decision. + + An "audit identity" is an identity which does not, in the + absence of additional information, enable a party + receiving and examining it to determine which subject it + belongs to. + + A "credential" is a collection of subject security + attributes. + + "effective rights" are the complete set of rights a + subject is entitled to based on all access control lists + which apply to a specific object and based on all of the + subject's security attributes. + + "granted rights" are the complete set of rights an access + control list entitles a subject to based on a specific + subject security attribute. + + A "group" is a privilege attribute asserting a subject's + membership in the collection of subjects whose name is + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 4] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + that of the group. + + An "identity" is a subject security attribute which is + unique to a single subject. + + An "object" is the target of operations in an information + system. + + An "operation" is the result of executing the code + accessed through a named entry point in an information + system. + + An "operation name" is the name of the entry point + through which an operation is invoked in an information + system. + + A "privilege attribute" is a subject security attribute + which may be shared by several subjects. + + "required rights" are the complete set of rights needed + to authorize a requester to perform a specific operation + on an object of a specific type. + + A "right" is the basic unit of access control policy + administration. For each object type in an information + system, a security administrator defines a set of + required rights for each operation. For each object in + the system, a security administrator defines a set of + granted rights for each subject security attribute. When + an access decision is required, an access decision + function checks to make sure that the requester's subject + security attributes have been granted all required rights + needed to perform the requested operation on the + specified target object. + + A "role" is a privilege attribute asserting a subject's + organizational position and entitlement to perform the + operations appropriate to that organizational position. + + A "subject" is an entity which intiates actions in an + information system. + + A "subject security attribute" is a defined property + which is used by a security policy evaluation system to + make policy decisions. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 5] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 4. The Model + + + 4.1 Access Control Activity Lifecycle + + The access control proposal described in this draft + addresses four activities: + + - Creation of subject security attribute information + and access control policy information + + - Retrieval of subject security attribute information + at the time an access request is made + + - Evaluation of access requests against policy, + resulting in an access decision + + - Replication of access control policy information + from one server to another + + 4.2 Access Control Information Model + + This document does not define formats for storage of + access control information; it does define the + operational semantics of access control operations. + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 6] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The diagram below illustrates the componentry of an LDAP + system and the placement of the function specified in + this draft. + + +-------------+ + | Application | + +-------------+ + +--------+ + | LDAP | + | Client | + +--------+ + | + | + | <-- LDAP Extended Access Control + Controls + | or Extended Access Control + Operations + v + +-----------------------------+ + | LDAP Server (e.g. SLAPD) | + +-----------------------------+ + . | + . | + . | + . | + v v + +----------+ +-----------+ + | Access | | | + | Control |<.....| Datastore | + | Manager | | | + +----------+ +-----------+ + + LDAP clients use the controls and extended operations + specified in this document to administer access control + policy enforced by LDAP servers. Servers may store + access control information in any way they choose. In + particular, servers may use the access control mechanisms + of their datastores to store and enforce LDAP access + control, or they may implement access control managers + external to their datastores. Datastores and external + access control managers may implement any access control + rule syntax and semantics they choose, as long as the + semantics is compatible with that defined in the section + titled "Operational Semantics of Access Control + Operations" (found after the control and extended + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 7] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + operation definition). + + The access control administration mechanisms specified in + this document are neutral with respect to policy + inheritance mechanisms, explicit vs. implicit denial, + and group nesting. + + 4.3 Bind and Credentials + + A bind authenticates a principal to the directory. A + principal is represented by a DN. A principal has a set + of credentials that are used for determining whether + access to resources specified in ldap operations. These + credentials may be pushed to the server by the client or + may be pulled by the server from the directory data. + Credentials may be local with respect to the server. If + not local (owned by another server or administrative + scope), then the server may decide to define a trust + model that states how to evaluate the trust of a + credential at bind time. The definition of such a trust + model is outside the scope of this document. + + + 5. Access Control Information Schema + + + 5.1 Attributes + + + 5.1.1 Root DSE Attribute for Access Control Mechanism + + The following attribute may be included in the Root DSE. + + ( + NAME 'supportedACIMechanisms' + DESC list of access control mechanisms supported + by this directory server + SYNTAX LDAPOID + ) + + Two access control mechanisms are defined by this + document: + LDAPv3 + X500 + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 8] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Other vendor access control mechanisms can be defined (by + OID) and are the responsibility of those vendors to + provide the definition and OID. + + 5.1.2 Subschema Attribute for Access Control Mechanism + + A given naming context must provide information about + which access control mechanism is in effect for that + portion of the namespace. The following attribute must + be in each subschema entry associated with a naming + context whose access control mechanism is different from + adjacent naming contexts supported by that directory + server. + + - aCIMechanism lists the value (an OID) that defines + the access control mechanism in effect for the scope + of that subschema entry + + 5.2 Other Defined Parameters/OIDs + + + 5.2.1 Rights Families and Rights + + The following rights families are defined: + LDAPv3 + X500 + + Other parties can (and will) define other rights + families. It is the responsibility of those parties to + provide the definition and OID. + + 5.2.1.1 LDAPv3 Rights Family + + Access rights can apply to an entire object or to + attributes of the object. Each of the LDAP access rights + are discrete. One permission does not imply another + permission. The rights may be ORed together to provide + the desired rights list. + + Rights which apply to attributes are: + + 1 Read Read attribute values + 2 Write Write attribute values + 4 Search Search entries with specified attributes + 8 Compare Compare attributes + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 9] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Rights that apply to an entire object are: + + 16 Add Add an object below this object + 32 Delete Delete this object + + Rights that apply to the object to which the directory + object points are: + + 64 Manage Perform a privileged operation; used to + restrict access to operations which + read or write especially sensitive data + 128 Use Execute; useful in controlling access to + the objects referred to by directory + entries than in controlling access to + the directory entries themselves + 256 Get Get retrieves the attribute values + 512 Set Set writes the attribute values + + 5.2.1.2 The X.500 Rights Family + + + + 5.2.2 DN Types + + The following DN Types are defined: + + - access-id, OID= + + - group, OID= + + - role, OID= + + access-id, group, and role MUST be supported. An acess- + id is a non-collection (non-group and non-role objects) + DN that can be authenticated. + + Other parties can (and will) define other DN Types. It + is the responsibility of those parties to provide the + definition and OID. + + + 6. Access Control Parameters for LDAP Controls & Extended + Operations + + This section defines the parameters used in the access + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 10] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + control LDAP controls and extended operations in this + document. + + targetDN specifies the initial directory entry in DN + syntax on which the control or extended operation is + performed. + + whichObject specifies whether the access control + information which is get/set is for the target directory + entry (ENTRY) or the target directory entry and its + subtree (SUBTREE). + + rightsFamily specifies the family of rights that will be + get/set for the control or extended operation performed. + A rights family has a defined set of rights. + + rightsList in the SearchResultEntry is of the form + specified in the LDIF BNF for . + + dnType speficies the type of subject security attribute. + Defined types are access-id, group, and role. + + subjectDN is a LDAP string that defines the subject or + value of the dnType. The subjectDN may be a DN or + another string such as IPAddress (dotted-decimal string + representation) on which access control is get/set. If + the subject is an entry in the directory, then the syntax + of the LDAP string is DN. We define two well-known + subjectDNs, the strings + + - public - meaning public access for all users + + - this - meaning the user whose name matches the entry + being accessed + + Four operations are defined: + + - ACI_GRANT grants the rights specified in the + rightsList for the given subject. If an access + control list does not exist for the specified + entry/attribute, then the access control list is + created with the granted rights for the given + subject. If the access control list already exists + for the specified entry/attribute, then the access + control list is modified to grant the rights for the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 11] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + given subject. + + - ACI_DENY denies the rights specified in the + rightsList for the given subject. No implementation + is implied for this operation. For example, denial + of rights may be implemented as explicit denial + (negative rights) on the access control list or + removal of rights from the access control list. + + - ACI_REPLACE replaces the entire access control list + for the specified entry/attribute. If an access + control list does not exist for the specified + entry/attribute, then the access control list is + created with the granted rights for the given + subject. + + - ACI_DELETE deletes the entire access control list + for the specified entry/attribute. + + attrs specifies the list of attributes against which the + operation is performed. attrs can be defined using a + LDAP filter expression. + + + 7. Access Control Information (ACI) Controls + + The access control information controls provide a way to + manipulate access control information in conjunction with + an LDAP operation such as ldap_add, ldap_modify, or + ldap_search. Three LDAP controls are defined for + transmission of access control information. These + controls allow access control information to be get/set + while manipulating other directory information. The + controls are: + + - getEffectiveRights to obtain the effective rights + for a given directory entry(s) for a given subject + during a ldap_search operation + + - listSubjectRights to get the access control + information for a given directory entry(s) during a + ldap_search operation + + - specifyCredentials to specify a set of credentials + for the bind identity (DN) during a ldap_bind + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 12] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + operation + + 7.1 getEffectiveRights Control + + + 7.1.1 Request Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + getEffectiveRightsRequest ::= SEQUENCE { + targetDN LDAPDN, + effectiveRightsRequest SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + subjectDN LDAPString, + } + } + + The targetDN specifies the initial directory entry in DN + syntax on which the getEffectiveRights control is + performed. request is a set of sequences that state the + whichObject (entry or entry plus subtree) and specifics + of the control request to be performed. One or more + rightsFamily can be be obtained for a given subjectDN ad + dnType. A "*" in the rightsFamily field indicates that + the rights for all rights families defined for the + subjectDN / dnType are to be returned. This control is + applied to the scope set by the ldap_search operation, + i.e. base, one-level, subtree. + + 7.1.2 Response Control + + This control is included in the ldap_search_response + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 13] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + message as part of the controls field of the LDAPMessage, + as defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + getEffectiveRightsResponse ::= { + result ENUMERATED { + success (0), + operationsError (1), + unavailableCriticalExtension (12), + noSuchAttribute (16), + undefinedAttributeType (17), + invalidAttributeSyntax (21), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + The effective rights returned are returned with each + attribute returned by the search result. So, the result + for ldap_search is: + + SearchResultEntry ::= [APPLICATION 4] SEQUENCE { + objectName LDAPDN, + rightsAttributes PartialEffectiveRightsList } + + PartialEffectiveRightsList ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + rightsList ENUMERATED, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + } + } + + Although this extends the search operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control, hence the above structure cannot be returned to + a LDAPv2 client. A LDAPv3 client cannot send this + request to a LDAPv2 server. A LDAPv3 server not + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 14] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + supporting this control cannot return the additional + data. + + 7.1.3 Client-Server Interaction + + The getEffectiveRightsRequest control requests the rights + that MUST be in effect for requested directory + entry/attribute based on the subject DN. The server that + consumes the search operation looks up the rights for the + returned directory information based on the subject DN + and returns that rights information. + + There are six possible scenarios that may occur as a + result of the getEffectiveRights control being included + on the search request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the searchResponse message and not send back any + other results. This behavior is specified in + section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified TRUE for the + control's criticality field, then the server SHOULD + do the following: return + unavailableCriticalExtension as a return code in + the searchResult message. + + 4. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified FALSE for the + control's criticality field, then the server should + process as 'no rights returned for that family' and + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 15] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + include the result Unavailable in the + getEffectiveRightsResponse control in the + searchResult message. + + 5. If the server supports this control and can return + the rights per the rightsFamily information, then + it should include the getEffectiveRightsResponse + control in the searchResult message with a result + of success. + + 6. If the search request failed for any other reason, + then the server SHOULD omit the + getEffectiveRightsResponse control from the + searchResult message. + + The client application is assured that the correct rights + are returned for scope of the search operation if and + only if the getEffectiveRightsResponse control returns + the rights. If the server omits the + getEffectiveRightsResponse control from the searchResult + message, the client SHOULD assume that the control was + ignored by the server. + + The getEffectiveRightsResponse control, if included by + the server in the searchResponse message, should have the + getEffectiveRightsResult set to either success if the + rights are returned or set to the appropriate error code + as to why the rights could not be returned. + + The server may not be able to return a right because it + may not exist in that directory object's attribute; in + this case, the rights request is ignored with success. + + 7.2 listSubjectRights Control + + + 7.2.1 Request Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 16] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + listSubjectRightsRequest ::= SEQUENCE { + targetDN LDAPDN, + listRightsRequest SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + listSubjectDN LDAPString | "*", + } + } + + The targetDN specifies the initial directory entry in DN + syntax on which the listSubjectRights control is + performed. request is a set of sequences that state the + whichObject (entry or entry plus subtree) and specifics + of the control request to be performed. One or more + rightsFamily can be be obtained for a given subjectDN ad + dnType. A "*" in the rightsFamily field indicates that + the rights for all rights families defined for the + subjectDN / dnType are to be returned. A "*" in the + dnType field indicates that all dnTypes are processed by + this request. A "*" in the subjectDN field indicates + that all subjectDNs are processed by this request. The + scope of the operation is controlled by the scope set in + the ldap_search operation. + + 7.2.2 Response Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as defined + in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + listSubjectRightsResponse ::= { + result ENUMERATED { + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 17] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + success (0), + operationsError (1), + unavailableCriticalExtension (12), + noSuchAttribute (16), + undefinedAttributeType (17), + invalidAttributeSyntax (21), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + The subjects' rights returned are returned with each + attribute returned by the search result. So, the result + for ldap_search is: + + SearchResultEntry ::= [APPLICATION 4] SEQUENCE { + objectName LDAPDN, + attributes PartialSubjRightsAttributeList } + + PartialSubjRightsAttributeList ::= SEQUENCE OF SEQUENCE + { + rightFamily LDAPOID, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPString, + rightsList ENUMERATED + } + + Although this extends the search operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control, hence the above structure cannot be returned to + a LDAPv2 client. A LDAPv3 client cannot send this + request to a LDAPv2 server. A LDAPv3 server not + supporting this control cannot return the additional + data. + + 7.2.3 Client-Server Interaction + + The listSubjectRightsRequest control specifies the rights + that MUST be returned for the scope of the search. The + server that consumes the search operation looks up the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 18] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + rights for the returned directory information and returns + the result as search information associated with the + scope of that search. + + There are six possible scenarios that may occur as a + result of the listSubjectRights control being included on + the search request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the searchResponse message and not send back any + other results. This behavior is specified in + section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified TRUE for the + control's criticality field, then the server SHOULD + do the following: return + unavailableCriticalExtension as a return code in + the searchResult message and omit the + listSubjectRightsResponse control in the + searchResult message. + + 4. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified FALSE for the + control's criticality field, then the server should + process as 'no rights returned for that family' and + include the result Unavailable in the + listSubjectRightsResponse control in the + searchResult message. + + 5. If the server supports this control and can return + the rights per the rightsFamily information, then + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 19] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + it should include the listSubjectRightsResponse + control in the searchResult message with a result + of success. + + 6. If the search request failed for any other reason, + then the server SHOULD omit the + listSubjectRightsResponse control from the + searchResult message. + + The client application is assured that the correct rights + are returned for the scope of the search operation if and + only if the listSubjectRightsResponse control returns the + rights. If the server omits the + listSubjectRightsResponse control from the searchResponse + message, the client SHOULD assume that the control was + ignored by the server. + + The listSubjectRightsResponse control, if included by the + server in the searchResponse message, should have the + searchResult set to either success if the rights were + returned or set to the appropriate error code as to why + the rights could not be returned. + + The server may not be able to return a right because it + may not exist in that directory object's attribute; in + this case, the rights request is ignored with success. + + 7.3 specifyCredentials Control + + + 7.3.1 Request Control + + This control is included in the ldap_bind message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + specifyCredentialRequest ::= SEQUENCE { + credential LDAPString + } + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 20] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + } + + The credential specifies the credential (e.g. groups, + roles, etc) that the client is requesting be associated + with the bind DN for access control determination in + subsequent ldap operations. This provides a 'push' model + for credentials where the client attempts to 'push' the + credential to the server. The server may process at bind + time as follows: + + - server may unconditionally ignore + + - server may unconditionally accept + + - server may define trust model and evaluate of the + trust of each credential + + If this control is not used, it is assumed that the + server determines (pulls) the credentials associated with + the bind DN when needed in subsequent ldap operations to + provide access control. + + 7.3.2 Response Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as defined + in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + specifyCredentialsResponse ::= { + result ENUMERATED { + success (0), + operationsError (1), + unavailableCriticalExtension (12), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 21] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + No data is returned; just the result is returned. + + Although this extends the bind operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control. A LDAPv3 client cannot send this request to a + LDAPv2 server. A LDAPv3 server not supporting this + control cannot return the additional data. + + 7.3.3 Client-Server Interaction + + The specifyCredentialsRequest control specifies the + credentials that the client was the server to use for + access control in subsequent ldap operations. The server + that consumes the bind operation may unconditionally + accept, ignore, or evaluate the trust of the specified + credentials at bind time and returns only a success or + failure response (no data returned). + + There are six possible scenarios that may occur as a + result of the specifyCredential control being included on + the bind request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the bindResponse message. This behavior is + specified in section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified credential + (e.g. server decided to evaluate the trust of that + credential and the result is the server not + trusting all the credentials or unconditionally + ignores the credential) and the client specified + TRUE for the control's criticality field, then the + server SHOULD do the following: return + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 22] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + unavailableCriticalExtension as a return code in + the bindResult message and omit the + specifyCredentialResponse control in the bindResult + message. + + 4. If the server supports this control but for some + reason such as cannot process specified credential + (e.g. server decided to evaluate the trust of that + credential and the result is the server not + trusting all the credentials or unconditionally + ignores the credential) and the client specified + FALSE for the control's criticality field, then the + server should process as 'credential ignored' and + include the result Unavailable in the + specifyCredentialResponse control in the bindResult + message. + + 5. If the server supports this control and evaulates + the trust of that credential and the result is the + server trusting all the credentials, then it should + include the specifyCredentialResponse control in + the bindResult message with a result of success. + + 6. If the bind request failed for any other reason, + then the server SHOULD omit the + specifyCredentialResponse control from the + bindResult message. + + The client application is assured that the correct + credentials are used by the server when specified by the + client for subsequent ldap operations if and only if the + specifyCredentialResponse is successful. If the server + omits the specifyCredentialResponse control from the + searchResponse message, the client SHOULD assume that the + control was ignored by the server. + + The specifyCredentialResponse control, if included by the + server in the bindResponse message, should have the + bindResult set to either success if the credentials were + accepted by the server or set to the appropriate error + code as to why the credentials were not accepted. + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 23] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 8. Access Control Extended Operations + + Two extended operations (analogous to the controls) are + defined for transmission of access control information. + These operations help with the management of access + control information independent of manipulating other + directory information. The extended operations are: + + - LDAP Get Effective Rights to obtain the effective + rights for a given directory entry for a given + subject + + - LDAP List Subject Rights to get the access control + information for a given directory entry + + 8.1 LDAP Get Effective Rights Operation + + ldapGetEffectiveRightsRequest ::= [APPLICATION 23] + SEQUENCE { + requestName [0] , + requestValue [1] OCTET STRING OPTIONAL } + + where + + requestValue ::= SEQUENCE { + targetDN LDAPDN, + updates SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + subjectDN LDAPString, + } + } + + + The requestName is a dotted-decimal representation of the + OBJECT IDENTIFIER corresponding to the request. The + requestValue is information in a form defined by that + request, encapsulated inside an OCTET STRING. + + The server will respond to this with an LDAPMessage + containing the ExtendedResponse which is a rights list. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 24] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + ldpGetEffectiveRightsResponse ::= [APPLICATION 24] + SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] OPTIONAL, + effectiveRights [11] OCTET STRING OPTIONAL } + + where + + effectiveRights ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + rightsList ENUMERATED, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPSTRING + } + + If the server does not recognize the request name, it + MUST return only the response fields from LDAPResult, + containing the protocolError result code. + + 8.2 LDAP List Subject Rights + + ldapListSubjectRightsRequest ::= [APPLICATION 23] + SEQUENCE { + requestName [0] , + requestValue [1] OCTET STRING } + + where + + requestValue ::= SEQUENCE { + targetDN LDAPDN, + updates SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + listSubjectDN LDAPString | "*", + } + } + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 25] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The requestName is a dotted-decimal representation of the + OBJECT IDENTIFIER corresponding to the request. The + requestValue is information in a form defined by that + request, encapsulated inside an OCTET STRING. + + The server will respond to this with an LDAPMessage + containing the ExtendedResponse which is a result code. + + ldapListSubjectRightsResponse ::= [APPLICATION 24] + SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] OPTIONAL, + subjectRightsList [11] OCTET STRING OPTIONAL } + + where + + subjectRightsList ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPString, + perms SEQUENCE OF SEQUENCE { + rightsList ENUMERATED, + attrs LDAPSTRING + } + } + } + + If the server does not recognize the request name, it + MUST return only the response fields from LDAPResult, + containing the protocolError result code. + + + + 9. Operational Semantics of Access Control Operations + + The semantics of access control operations described in + this document are defined operationally in terms of + "histories". A history is a sequence of actions (x1, x2, + ..., xN). + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 26] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + We consider five types of actions: + + - LDAP Access Control Policy Update actions: + invocations of the LDAP Update Access Extended + Operation or LDAP Update Access Control. + + - LDAP Access Control Policy Query operations: + invocations of the LDAP Get Effective Access + Extended Operation, LDAP Get Effective Access + Control, LDAP List Subject Rights Extended + Operation, or LDAP List Subject Rights Control. + + - Datastore Access Control Policy Update Actions: any + operation implemented by the server which LDAP is + using as its datastore which changes the access + policy enforced with respect to attempts to access + LDAP directory entries and their attributes. + + - LDAP Access Request operations: invocations of LDAP + entry or attribute access operations (Read, Update, + Search, Compare, etc...). + + - Other operations: anything else, including Datastore + operations which do not change the access policy + enforced by the server. + + + The semantics of histories are defined as follows: + + - LDAP Update (Replace), LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation, and no rights not + granted by the Update operation. + + - LDAP Update (Grant), LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation. The Query may show + that the subject also has other rights not granted + by the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Deny), LDAP Query + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 27] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The Query will show that the subject does not have + any right denied by the Update operation. The Query + may show that the subject has rights not denied by + the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Replace), LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request will fail with an access- + denied exception if it requires any right not + granted by the Update operation. + + - LDAP Update (Grant), LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request may succeed if it requires + rights not granted by the Update operation, + depending on the policy in force before the Update + operation. + + - LDAP Update (Deny), LDAP Access Request + + The Request will fail with an access-denied + exception if it requires any right denied to the + requesting subject by the Update operation. If the + Request requires only rights which were not denied + by the Update operation, it may succeed, depending + on the policy in force before the Update operation. + + - LDAP Update (Replace), Other, LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation, and no rights not + granted by the Update operation. + + - LDAP Update (Grant), Other, LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation. The Query may show + that the subject also has other rights not granted + by the Update operation, depending on the policy in + force before the Update operation. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 28] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + - LDAP Update (Deny), Other, LDAP Query + + The Query will show that the subject does not have + any right denied by the Update operation. The Query + may show that the subject has rights not denied by + the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Replace), Other, LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request will fail with an access- + denied exception if it requires any right not + granted by the Update operation. + + - LDAP Update (Grant), Other, LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request may succeed if it requires + rights not granted by the Update operation, + depending on the policy in force before the Update + operation. + + - LDAP Update (Deny), Other, LDAP Access Request + + The Request will fail with an access-denied + exception if it requires any right denied to the + requesting subject by the Update operation. If the + Request requires only rights which were not denied + by the Update operation, it may succeed, depending + on the policy in force before the Update operation. + + - LDAP Update (Replace), Datastore Update, LDAP Query + + The result of the Query is not defined. + + - LDAP Update (Grant), Datastore Update, LDAP Query + + The result of the Query is not defined. + + - LDAP Update (Deny), Datastore Update, LDAP Query + + The result of the Query is not defined. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 29] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + - LDAP Update (Replace), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + - LDAP Update (Grant), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + - LDAP Update (Deny), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + + + 10. LDIF Syntax for Access Control Information + + + 10.1 LDIF Purpose + + The intent of the LDIF is to design a common interchange + format. Any given LDAP server should be able to translate + the below defined LDIF into a meaningful request. Each + server should be able to understand each part of the + LDIF; there should not be any ambiguity into what any + part of the syntax means. + + While the end goal is to have a common behavior model + between different LDAP server implementations, the LDIF + alone will not ensure identical ACL processing behavior + between servers. The semantics of how a server + interprets the aci syntax are not defined here. What + 'deny' means on server1 might be different than on + server2. + + The LDIF maintains an assumption that the receiving + server supports inheritance within the security model. If + the server does not support inheritance, the receiving + server must expand any inherited information based on the + scope flag. + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 30] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 10.2 ACL Attributes + + There are three attributes which are allowed on all + directory objects: aci, vendorAci and policyOwner. The + syntax of these attributes is defined below. The aci, + vendorAci and policyOwner attribute are all multivalued. + In determining the order of the syntax, the DN was left + until the end for parsing reasons. Examples follow the + BNF + + + 10.2.1 VendorACI_ + + The Vendor specific ACI information is listed in its own + attribute. The assumption here is that if the vendor's + need to provide information in an additional attribute, + then the vendor specific information would not + necessarily be of the same syntax as the ACI attribute + which would have < acl syntax> . + + + 10.2.2 Policy Owner_ + + The intent behind policy ownership is that it controls + administrative subdomains. It can also control who has + permission to set / change acls for implementations that + do not have an acl controlling access to itself. If + there are multiple policy owners it is implementation + specific as to the behavior of whether policy owner #1 + can override policy owner # 2. + + The syntax for policyOwner includes the 'scope' flag. + Servers which do not support inheritance must expand the + policyOwner inheritance similar to the expansion of the + ACI. If the policy owner is not specified for any + object in the tree, behavior is implementation defined. + For instance, if no object anywhere in the tree has a + policy owner, then the server could simply assert that + the 'root DN' is considered the policy owner for all + objects. An alternate approach might be that the + implementation defines the entryDN to be the policy + owner. + + The policyOwner and ACI are left as distinct attributes + for several reasons. They syntax of the policy owner is + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 31] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + very similar to the syntax of the ACI. In parsing, it + would be difficult to tell when one stops and the other + begins (especially since there are no reserved characters + in LDAP Dns ). Additionally, the inheritance models of + the administrative subdomains may be different then the + models guiding the ACI inheritance. Since there is no + flag to tell if a given ACI is explicit vs inherited, + combining the two sets of information ties the + policyOwner inheritance to ACI inheritance. Additionally, + keeping the information separate makes it easier for the + applications to construct views of various models by only + requesting the information they need. + + + 10.2.3 ACI + + The aci attribute is defined using < acl syntax>. Within + the acl syntax, the family OID describes the permissions, + dnType, subhectDn and scope that will be found in the + following string. The permissions for the IETF family + are found below. The family OID is listed first in the + syntax to be consistent with other LDAP LDIF definitions + which list OIDs first. If the OID within the ACI + attribute is listed as other than the IETF family oid, + the syntax is the same as l isted below, but one or more + of the scope, dnType, subjectDn or permissions may vary + from the IETF defined syntax. + + Within the acl syntax, there is a string which describes + the rights. This is a composite of the permissions and + resources to which the user is being granted or denied + access. The set of permissions is fixed. Either of the + actions "grant" | "deny" may be used when creating or + updating an aci. + + Using the BNF defined below, it is possible for the + permission string to be empty. The aci + + aci: + 1.2.3.4#subtree#grant;;attribute1$grant;r,s;[all]#group#cn=Dept + XYZ, c=US + + mean that this group is granted permission to read and + search all attributes except attribute1. + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 32] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Similarly, the aci + + aci: 1.2.3.4#subtree#group#cn=Dept XYZ, c=US simply + means that no permissions have been defined for this + group. It is up to the server implementation as to + whether the group does or does not receive permission to + attributes on an entry with an empty rights list. + + The attributeString is an attribute Name (defined to be a + printable string). If the string refers to an attribute + not defined in the given server's schema, the server + SHOULD report an error. Another option for the + attributeString is "[entry]". This is provided to + describe permissions which apply to an entire object. + This could mean actions such as delete the object, or add + a child object. The third option for attributeString is + "[all]" which means the permission set should apply to + all attributes. + + If the keyword "[all]" and another attribute are both + specified within an aci, the more specific permission set + for the attribute overrides the less specific permission + set for "[all]". If two acis contain identical + familyOID, scope, DnTypes and DNs, the permission given + DN is specified in two distinct acis on any given entry, + the rights lists can be combined into one list. For + example: + + aci: 1.2.3.4#subtree#group#grant;r,w;[all]#cn=Dept XYZ + aci: 1.2.3.4#subtree#group#grant;r;attribute1#cn=Dept + XYZ + + is the equivalent of + + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];r,attribute1#cn=Dept + XYZ + + Multiple attributeStrings can be listed after any given + permission set; for instance, "r,w ; attribute1, + attribute2". This means that if the server supports a + attribute aggregation mechanism, attribute1 and + attribute2 should be considered to be part of the same + group. If the server does not support a grouping + mechanism, the permission set applies independently to + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 33] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + attribute1 and attribute2. For servers that do not + support attribute grouping, "r,w ; attribute1, + attribute2" results in the same operations as " r,w; + attribute1; r,w; attribute2 " + + Within the vendorACI, the oid determines the format or + the printable string to follow. + + + 10.3 Modifying the ACI Values + + The attribute: value pairs listed below would be possible + inputs for normal LDAP operations such as ldapadd and + ldapmodify. Within the ldapmodify command there are + three changetypes: add, delete, replace. + + Replace works similarly to all other attributes. If the + attribute value does not exist, create the value. If the + attribute does exist, replace the value. If the aci + value is replaced, all aci values are replaced. Given an + aci for an entry: + + aci: + 1.2.3.4#subtree#deny;r,w;[all];grant;rsc;attirbute2#group#cn=Dept + ABC + aci: + 1.2.3.4#subtree#grant;r,;[all];grant;rsc;attirbute1#group#cn=Dept + XYZ + + perform the following change: + + dn: cn=someEntry + changetype: replace + add: aci + aci: 1.2.3.4#subtree#grant;r,w;[all];#group#cn=Dept LMN + + The resulting acl is: + + aci: 1.2.3.4#subtree#grant;r,w;[all];#group#cn=Dept LMN + + (aci values for Dept XYZ and ABC are lost through the + replace) + + During an ldapmodify-add, if the aci does not exist, the + create the aci with the specific aci value(s). If the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 34] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + aci does exist, then add the specified values to the + given aci. For example a given aci: + + aci: 1.2.3.4#subtree#group#grant;r,w;[all]#cn=Dept XYZ + + with a modification: + dn: cn=someEntry + changetype: add + add: aci + aci: 1.2.3.4#subtree#group#grant;r;attribute1#cn=Dept + XYZ + + would yield an aci value of: + + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];r,attribute1#cn=Dept + XYZ + + To delete an entire acl, use ldapmodify - delete without + specifying a value for the aci. The entry would then + inherit its aci from some other node in the tree + depending on the server inheritance model. + + dn: cn = some Entry + changetype: delete + delete: aci + + During an ldapmodify-delete, there are two possible + interpretations of the delete. + + dn: cn = some Entry + changetype: delete + delete: aci + aci: < > (see below) + + Interpretation 1. + + aci: 1.2.3.4#subtree#group#cn=Dept XYZ + would delete the entire aci for the group cn=Dept XYZ + + Interpretation 2. + + aci: + 1.2.3.4#subtree#grant;rsc;attribute1#group#cn=Dept XYZ + would delete the 'grant;rsc;attribute1' portion of the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 35] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + aci + for the group cn=Dept XYZ + + before ldapmodify - delete: + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];grant;rsc;attribute1#cn=Dept + XYZ + + after ldapmodify - delete of attribute1 + aci: 1.2.3.4#subtree#group#grant;r,w;[all];#cn=Dept + XYZ + + if the delete is for an attribute not existing within + the aci, nothing + is changed in the expected outcome. For example, if now + attribute2 + is deleted, + + aci: 1.2.3.4#subtree#grant;[attribute2]#group#cn=Dept + XYZ + + the resulting aci would still be + + aci: 1.2.3.4#subtree#group#grant;r,w;[all];#cn=Dept + XYZ + + + 10.4 BNF + + ::= + ::= + '#' + + + ::= + '#' + + '#' + + + '#' + + '#' + + + ::= + '#' + + '#' + + + '#' + + + ::= + ::= < oid > + + :: "entry" | "subtree" + + :: "access-id" | "role" | "group" + ::= [ ] | [ < right > + [ '$' + ] * ] + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 36] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + ::= + ';' + + + ';' + + + ::= "grant" | "deny" + + ::= [ ] | [ < permission > + + [ ',' + ] * ] + ::= [ + + [ ',' + ] * ] + + ::= "[all]" | "[entry]" | + + + : "a" | "d" | "r" | "s" | "w" | "c" + | "g" | "s" | "m" | "u" + These are the permissions defined for + the IETF family OID. + + + 10.5 Examples + + Suppose IETFFamilyOID = 1.2.3.4 + + The following two examples show an administrative + subdomain being established. The first example shows a + single user being assigned the policyOwner for the entire + domain. The second example shows a group of ids assigned + to the policy Owner. + + policyOwner: 1.2.3.4#subtree#access-id#cn=Hoyt + + policyOwner: 1.2.3.4#subtree#group#cn=System Owners, + o=Company + + The next example shows an aci attribute where a group + "cn=Dept XYZ, c=US" is being given permissions to read, + search and compare attribute1. The permission should + apply to the entire subtree below the node containing + this aci. + + aci: 1.2.3.4#subtree#group#grant;r,s,c;attribute1#cn=Dept + XYZ, c=US + + The next example shows an ACI attribute where a role + "cn=SysAdmins,o=Company" is being given permissions to + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 37] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + add objects below this node, and read, search and compare + attributes2 and 3. The permission should apply to the + entire subtree below the node containing this ACI. + + aci: + 1.2.3.4#subtree#role#grant;a;[entry]$grant;r,s,c;attribute2,attribute3#cn=SysAdmins,o=Company + + + + 11. Security Considerations + + This draft proposes protocol elements for transmission of + security policy information. Security considerations are + discussed throughout this draft. Because subject + security attribute information is used to evaluate + decision requests, it is security-sensitive information + and must be protected against unauthorized modification + whenever it is stored or transmitted. + + + + 12. References + + [LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight + Directory Access Protocol (v3)", RFC 2251, December 1997. + + [ECMA] ECMA, "Security in Open Systems: A Security + Framework" ECMA TR/46, July 1988 + + [REQTS] Stokes, Byrne, Blakley, "Access Control + Requirements for LDAP, INTERNET-DRAFT , August 1998. + + [ATTR] M.Wahl, A, Coulbeck, T. Howes, S. Kille, + "Lightweight Directory Access Protocol (v3)": Attribute + Syntax Definitions, RFC 2252, December 1997. + + [UTF] M. Wahl, S. Kille, "Lightweight Directory Access + Protocol (v3)": A UTF-8 String Representation of + Distinguished Names", RFC 2253, December 1997. + + [Bradner97] Bradner, Scott, "Key Words for use in RFCs to + Indicate Requirement Levels", RFC 2119. + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 38] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + AUTHOR(S) ADDRESS + + Ellen Stokes Bob Blakley + IBM Dascom + 11400 Burnet Rd + Austin, TX 78758 Austin, TX + USA USA + mail-to: stokes@austin.ibm.com mail-to: blakley@dascom.com + phone: +1 512 838 3725 + fax: +1 512 838 8597 + + + Debbie Byrne + IBM + 11400 Burnet Rd + Austin, TX 78758 + USA + mail-to: djbyrne@us.ibm.com + phone: +1 512 838 1960 + fax: +1 512 838 0156 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 39] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 40] + + + + + + + + + + CONTENTS + + + 1. Introduction....................................... 2 + + 2. Overview........................................... 2 + + 3. Terminology........................................ 3 + + 4. The Model.......................................... 6 + 4.1 Access Control Activity Lifecycle............ 6 + 4.2 Access Control Information Model............. 6 + 4.3 Bind and Credentials......................... 8 + + 5. Access Control Information Schema.................. 8 + 5.1 Attributes................................... 8 + 5.1.1 Root DSE Attribute for Access + Control Mechanism 8 + 5.1.2 Subschema Attribute for Access + Control Mechanism 9 + 5.2 Other Defined Parameters/OIDs................ 9 + 5.2.1 Rights Families and Rights 9 + 5.2.2 DN Types 10 + + 6. Access Control Parameters for LDAP Controls & + Extended Operations................................ 10 + + 7. Access Control Information (ACI) Controls.......... 12 + 7.1 getEffectiveRights Control................... 13 + 7.1.1 Request Control 13 + 7.1.2 Response Control 13 + 7.1.3 Client-Server Interaction 15 + 7.2 listSubjectRights Control.................... 16 + 7.2.1 Request Control 16 + 7.2.2 Response Control 17 + 7.2.3 Client-Server Interaction 18 + 7.3 specifyCredentials Control................... 20 + 7.3.1 Request Control 20 + 7.3.2 Response Control 21 + 7.3.3 Client-Server Interaction 22 + + 8. Access Control Extended Operations................. 24 + 8.1 LDAP Get Effective Rights Operation.......... 24 + 8.2 LDAP List Subject Rights..................... 25 + + + + + - i - + + + + + + + + + + + + 9. Operational Semantics of Access Control + Operations......................................... 26 + + 10. LDIF Syntax for Access Control Information......... 30 + 10.1 LDIF Purpose................................. 30 + 10.2 ACL Attributes............................... 31 + 10.2.1 VendorACI 31 + 10.2.2 Policy Owner 31 + 10.2.3 ACI 32 + 10.3 Modifying the ACI Values..................... 34 + 10.4 BNF.......................................... 36 + 10.5 Examples..................................... 37 + + 11. Security Considerations............................ 38 + + 12. References......................................... 38 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - ii - + + + + diff --git a/doc/drafts/draft-ietf-ldapext-ldap-c-api-02.txt b/doc/drafts/draft-ietf-ldapext-ldap-c-api-02.txt new file mode 100644 index 0000000000..0ed82cf4b1 --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-ldap-c-api-02.txt @@ -0,0 +1,4315 @@ + + + + + + +Network Working Group M. Smith, Editor +INTERNET-DRAFT Netscape Communications Corp. +Intended Category: Standards Track T. Howes +Obsoletes: RFC 1823 Netscape Communications Corp. +Expires: 23 August 1999 A. Herron + Microsoft Corp. + M. Wahl + Innosoft International, Inc. + A. Anantha + Microsoft Corp. + + + 23 February 1999 + + The C LDAP Application Program Interface + + + +1. Status of this Memo + +This document is an Internet-Draft and is in full conformance with all +provisions of Section 10 of RFC2026. Internet-Drafts are working docu- +ments of the Internet Engineering Task Force (IETF), its areas, and its +working groups. Note that other groups may also distribute working +documents as Internet-Drafts. + +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any +time. It is inappropriate to use Internet-Drafts as reference material +or to cite them other than as "work in progress." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt. + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html. + +This draft document will be submitted to the RFC Editor as a Standards +Track document. Distribution of this memo is unlimited. Technical dis- +cussion of this document will take place on the IETF LDAP Extension +Working Group mailing list . Please send +editorial comments directly to the authors. + +Copyright (C) The Internet Society (1997-1999). All Rights Reserved. + +Please see the Copyright section near the end of this document for more +information. + + + + +Expires: 23 August 1999 [Page 1] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +2. Introduction + +This document defines a C language application program interface (API) +to the Lightweight Directory Access Protocol (LDAP). This document +replaces the previous definition of this API, defined in RFC 1823, +updating it to include support for features found in version 3 of the +LDAP protocol. New extended operation functions were added to support +LDAPv3 features such as controls. In addition, other LDAP API changes +were made to support information hiding and thread safety. + +The C LDAP API is designed to be powerful, yet simple to use. It defines +compatible synchronous and asynchronous interfaces to LDAP to suit a +wide variety of applications. This document gives a brief overview of +the LDAP model, then an overview of how the API is used by an applica- +tion program to obtain LDAP information. The API calls are described in +detail, followed by appendices that provide example code demonstrating +use of the API, the namespace consumed by the API, a summary of require- +ments for API extensions, known incompatibilities with RFC 1823, and a +list of changes made since the last revision of this document. + + +3. Table of Contents + +1. Status of this Memo............................................1 +2. Introduction...................................................2 +3. Table of Contents..............................................2 +4. Overview of the LDAP Model.....................................4 +5. Overview of LDAP API Use.......................................4 +6. Header File Requirements.......................................6 +7. Common Data Structures.........................................7 +8. Retrieving Information About the API Implementation............8 +8.1. Retrieving Information at Compile Time......................8 +8.2. Retrieving Information During Execution.....................10 +9. LDAP Error Codes...............................................13 +10. Performing LDAP Operations.....................................14 +10.1. Initializing an LDAP Session................................14 +10.2. LDAP Session Handle Options.................................15 +10.3. Working With Controls.......................................21 +10.3.1. A Client Control That Governs Referral Processing........22 +10.4. Authenticating to the directory.............................22 +10.5. Closing the session.........................................25 +10.6. Searching...................................................26 +10.7. Reading an Entry............................................30 +10.8. Listing the Children of an Entry............................30 +10.9. Comparing a Value Against an Entry..........................30 +10.10. Modifying an entry..........................................32 +10.11. Modifying the Name of an Entry..............................34 +10.12. Adding an entry.............................................36 + + + +Expires: 23 August 1999 [Page 2] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +10.13. Deleting an entry...........................................38 +10.14. Extended Operations.........................................40 +11. Abandoning An Operation........................................41 +12. Obtaining Results and Peeking Inside LDAP Messages.............42 +13. Handling Errors and Parsing Results............................44 +14. Stepping Through a List of Results.............................47 +15. Parsing Search Results.........................................48 +15.1. Stepping Through a List of Entries or References............48 +15.2. Stepping Through the Attributes of an Entry.................49 +15.3. Retrieving the Values of an Attribute.......................50 +15.4. Retrieving the name of an entry.............................51 +15.5. Retrieving controls from an entry...........................52 +15.6. Parsing References..........................................53 +16. Encoded ASN.1 Value Manipulation...............................54 +16.1. General.....................................................54 +16.2. Encoding....................................................55 +16.3. Encoding Example............................................58 +16.4. Decoding....................................................59 +16.5. Decoding Example............................................61 +17. Security Considerations........................................64 +18. Acknowledgements...............................................64 +19. Copyright......................................................64 +20. Bibliography...................................................65 +21. Authors' Addresses.............................................66 +22. Appendix A - Sample C LDAP API Code............................67 +23. Appendix B - Namespace Consumed By This Specification..........68 +24. Appendix C - Summary of Requirements for API Extensions........69 +24.1. Compatibility...............................................69 +24.2. Style.......................................................69 +24.3. Dependence on Externally Defined Types......................69 +24.4. Compile Time Information....................................69 +24.5. Runtime Information.........................................70 +24.6. Values Used for Session Handle Options......................70 +25. Appendix D - Known Incompatibilities with RFC 1823.............70 +25.1. Opaque LDAP Structure.......................................70 +25.2. Additional Error Codes......................................70 +25.3. Freeing of String Data with ldap_memfree()..................71 +25.4. Changes to ldap_result()....................................71 +25.5. Changes to ldap_first_attribute() and ldap_next_attribute...71 +25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......71 +25.7. API Specification Clarified.................................72 +25.8. Deprecated Functions........................................72 +26. Appendix E - Changes Made Since Last Document Revision.........72 +26.1. API Changes.................................................73 +26.2. Editorial changes...........................................74 + + + + + + +Expires: 23 August 1999 [Page 3] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +4. Overview of the LDAP Model + +LDAP is the lightweight directory access protocol, described in [2] and +[6]. It can provide a lightweight frontend to the X.500 directory [1], +or a stand-alone service. In either mode, LDAP is based on a client- +server model in which a client makes a TCP connection to an LDAP server, +over which it sends requests and receives responses. + +The LDAP information model is based on the entry, which contains infor- +mation about some object (e.g., a person). Entries are composed of +attributes, which have a type and one or more values. Each attribute has +a syntax that determines what kinds of values are allowed in the attri- +bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those +values behave during directory operations (e.g., is case significant +during comparisons). + +Entries may be organized in a tree structure, usually based on politi- +cal, geographical, and organizational boundaries. Each entry is uniquely +named relative to its sibling entries by its relative distinguished name +(RDN) consisting of one or more distinguished attribute values from the +entry. At most one value from each attribute may be used in the RDN. +For example, the entry for the person Babs Jensen might be named with +the "Barbara Jensen" value from the commonName attribute. + +A globally unique name for an entry, called a distinguished name or DN, +is constructed by concatenating the sequence of RDNs from the entry up +to the root of the tree. For example, if Babs worked for the University +of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, +o=University of Michigan, c=US". The DN format used by LDAP is defined +in [4]. + +Operations are provided to authenticate, search for and retrieve infor- +mation, modify information, and add and delete entries from the tree. +The next sections give an overview of how the API is used and detailed +descriptions of the LDAP API calls that implement all of these func- +tions. + + +5. Overview of LDAP API Use + +An application generally uses the C LDAP API in four simple steps. + + 1. Initialize an LDAP session with a primary LDAP server. The + ldap_init() function returns a handle to the session, allowing + multiple connections to be open at once. + + 2. Authenticate to the LDAP server. The ldap_sasl_bind() function + and friends support a variety of authentication methods. + + + +Expires: 23 August 1999 [Page 4] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + 3. Perform some LDAP operations and obtain some results. + ldap_search() and friends return results which can be parsed by + ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc. + + 4. Close the session. The ldap_unbind() function closes the connec- + tion. + +Operations can be performed either synchronously or asynchronously. The +names of the synchronous functions end in _s. For example, a synchronous +search can be completed by calling ldap_search_s(). An asynchronous +search can be initiated by calling ldap_search(). All synchronous rou- +tines return an indication of the outcome of the operation (e.g, the +constant LDAP_SUCCESS or some other error code). The asynchronous rou- +tines make available to the caller the message id of the operation ini- +tiated. This id can be used in subsequent calls to ldap_result() to +obtain the result(s) of the operation. An asynchronous operation can be +abandoned by calling ldap_abandon() or ldap_abandon_ext(). + +Results and errors are returned in an opaque structure called LDAPMes- +sage. Routines are provided to parse this structure, step through +entries and attributes returned, etc. Routines are also provided to +interpret errors. Later sections of this document describe these rou- +tines in more detail. + +LDAP version 3 servers may return referrals and references to other +servers. By default, implementations of this API will attempt to follow +referrals automatically for the application. This behavior can be dis- +abled globally (using the ldap_set_option() call) or on a per-request +basis through the use of a client control. + +All DN and string attribute values passed into or produced by this C +LDAP API are represented using the character set of the underlying LDAP +protocol version in use. When this API is used with LDAPv3, DN and +string values are represented as UTF-8[10] characters. When this API is +used with LDAPv2, the US-ASCII[12] or T.61[12] character set are used. +Future documents may specific additional APIs supporting other character +sets. + +For compatibility with existing applications, implementations of this +API will by default use version 2 of the LDAP protocol. Applications +that intend to take advantage of LDAP version 3 features will need to +use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to +switch to version 3. + +Note that this API is designed for use in environments where the 'int' +type is at least 32 bits in size. + + + + + +Expires: 23 August 1999 [Page 5] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +6. Header File Requirements + +To promote portability of applications, implementations of this C LDAP +API must conform to the following requirements of the header files used +by applications to access the services of this API: + +Name and Inclusion + Applications are only required to include a single header file + named ldap.h to access all of the API services described in this + document. Therefore, the following C source program must com- + pile without errors: + + #include + + int + main() + { + return 0; + } + + Note that it is permissible for the ldap.h header file to + include other implementation-specific header files. + +Implementations SHOULD also provide a header file named lber.h to faci- +late development of applications desiring compatibility with older LDAP +implementations. The lber.h header file may be empty. + + +Idempotence + All header files should be idempotent; that is, if they are + included more than once the effect is as if they had only been + included once. + +Must Be Included Before API Is Used + An application must include the ldap.h header file before + referencing any of the function or type definitions described in + this API specification. + +Mutual Independence + If possible, header files should be mutually independent with + minimal dependence on system or any other header files. + +Use of the 'const' Keyword + This API specification is defined in terms of ISO C[13]. It + makes use of function prototypes and the 'const' keyword. The + use of 'const' in this specification is limited to simple, non- + array function parameters to avoid forcing applications to + declare parameters and variables that accept return values from + + + +Expires: 23 August 1999 [Page 6] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP API functions as 'const.' Implementations specifically + designed to be used with non-ISO C translators may provide func- + tion declarations without prototypes or function prototypes + without specification of 'const' arguments. + +Definition of 'struct timeval' + This API specification uses the 'struct timeval' type. Imple- + mentations of this API should ensure that the struct timeval + type is by default defined as a consequence of including the + ldap.h header file. Because struct timeval is usually defined + in one or more system header files, it is possible for header + file conflicts to occur if ldap.h also defines it or arranges + for it to be defined by including another header file. There- + fore, applications may want to arrange for struct timeval to be + defined before they include ldap.h. To support this, the ldap.h + header file must not itself define struct timeval if the prepro- + cessor symbol LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h + is included. + + +7. Common Data Structures + +Some data structures that are common to several LDAP API functions are +defined here: + + typedef struct ldap LDAP; + + typedef struct ldapmsg LDAPMessage; + + typedef struct berelement BerElement; + + struct berval { + unsigned long bv_len; + char *bv_val; + }; + + struct timeval { + long tv_sec; + long tv_usec; + }; + +The LDAP structure is an opaque data type that represents an LDAP ses- +sion Typically this corresponds to a connection to a single server, but +it may encompass several server connections in the face of LDAPv3 refer- +rals. + +The LDAPMessage structure is an opaque data type that is used to return +entry, reference, result, and error information. An LDAPMessage + + + +Expires: 23 August 1999 [Page 7] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +structure may represent the beginning of a list, or chain of messages +that consists of a series of entries, references, and result messages as +returned by LDAP operations such as search. LDAP API functions such as +ldap_parse_result() that operate on message chains that may contain more +than one result message always operate on the first result message in +the chain. See the "Obtaining Results and Peeking Inside LDAP Messages" +section of this document for more information. + +The BerElement structure is an opaque data type that is used to hold +data and state information about encoded data. It is described in more +detail in the section "Encoded ASN.1 Value Manipulation" later in this +document. + +The berval structure is used to represent arbitrary binary data and its +fields have the following meanings: + +bv_len Length of data in bytes. + +bv_val A pointer to the data itself. + + +The timeval structure is used to represent an interval of time and its +fields have the following meanings: + +tv_sec Seconds component of time interval. + +tv_usec Microseconds component of time interval. + +See the earlier section "Header File Requirements" for more information +on struct timeval. + + +8. Retrieving Information About the API Implementation + +Applications developed to this specification need to be able to deter- +mine information about the particular API implementation they are using +both at compile time and during execution. + + +8.1. Retrieving Information at Compile Time + +All conformant implementations MUST include the following five defini- +tions in a header file so compile time tests can be done by LDAP +software developers: + + #define LDAP_API_VERSION level + #define LDAP_VERSION_MIN min-version + #define LDAP_VERSION_MAX max-version + + + +Expires: 23 August 1999 [Page 8] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_VENDOR_NAME "vend-name" + #define LDAP_VENDOR_VERSION vend-version + +where: + + "level" is replaced with the RFC number given to this C LDAP API + specification when it is published as a standards track RFC. + + min-version is replaced with the lowest LDAP protocol version sup- + ported by the implementation. + + max-version is replaced with the highest LDAP protocol version sup- + ported by the implementation. This should be 3. + + "vend-name" is replaced with a text string that identifies the + party that supplies the API implementation. + + "vend-version" is a supplier-specific version number multiplied + times 100. + +Note that the LDAP_VENDOR_NAME macro may be defined as "" if no vendor +name is available and the LDAP_VENDOR_VERSION macro may be defined as 0 +if no vendor-specific version information is available. + +For example, if this specification is published as RFC 88888, Netscape +Communication's version 4.0 implementation that supports LDAPv2 and v3 +might include macro definitions like these: + + #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */ + #define LDAP_VERSION_MIN 2 + #define LDAP_VERSION_MAX 3 + #define LDAP_VENDOR_NAME "Netscape Communications Corp." + #define LDAP_VENDOR_VERSION 400 /* version 4.0 */ + +and application code can test the C LDAP API version level using a +construct such as this one: + + #if (LDAP_API_VERSION >= 88888) + /* use features supported in RFC 88888 or later */ + #endif + +Until such time as this document is published as an RFC, implementations +should use the value 2000 plus the revision number of this draft for +LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION +for revision 03 of this draft is 2003. + +Documents that extend this specification SHOULD define a macro of the +form: + + + +Expires: 23 August 1999 [Page 9] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_API_FEATURE_x level + +where "x" is replaced with a name (textual identifier) for the feature +and "level" is replaced with the number of the RFC that specifies the +API extension. The name SHOULD NOT begin with the string "X_". + +For example, if C LDAP API extensions for Transport Layer Security [9] +were published in RFC 99999, that RFC might require conformant implemen- +tations to define a macro like this: + + #define LDAP_API_FEATURE_TLS 99999 + + +Private or experimental API extensions may be indicated by defining a +macro of this same form where "x" (the extension's name) begins with the +string "X_" and "level" is replaced with a integer number that is +specific to the extension. + + +8.2. Retrieving Information During Execution + +The ldap_get_option() call (described in greater detail later in this +document) can be used during execution in conjunction with an option +parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic +information about the API and about the specific implementation being +used. The ld parameter to ldap_get_option() can be either NULL or a +valid LDAP session handle which was obtained by calling ldap_init(). +The optdata parameter to ldap_get_option() MUST be the address of an +LDAPAPIInfo structure which is defined as follows: + + typedef struct ldapapiinfo { + int ldapai_info_version; /* version of this struct (1) */ + int ldapai_api_version; /* revision of API supported */ + int ldapai_protocol_version; /* highest LDAP version supported */ + char **ldapai_extensions; /* names of API extensions */ + char *ldapai_vendor_name; /* name of supplier */ + int ldapai_vendor_version; /* supplier-specific version times 100 */ + } LDAPAPIInfo; + +In addition, API implementations MUST include the following macro defin- +ition: + + #define LDAP_API_INFO_VERSION 1 + +Note that the ldapai_info_version field of the LDAPAPIInfo structure +should be set to the value LDAP_API_INFO_VERSION (1) before calling +ldap_get_option() so that it can be checked for consistency. All other +fields are set by the ldap_get_option() function. + + + +Expires: 23 August 1999 [Page 10] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +The members of the LDAPAPIInfo structure are: + +ldapai_info_version + A number that identifies the version of the LDAPAPIInfo struc- + ture. This should be set to the value LDAP_API_INFO_VERSION + (1) before calling ldap_get_option(). If the value received + is not recognized by the API implementation, the + ldap_get_option() function sets ldapai_info_version to a valid + value that would be recognized, sets the ldapai_api_version to + the correct value, and returns an error without filling in any + of the other fields in the LDAPAPIInfo structure. + +ldapai_api_version + A number that matches that assigned to the C LDAP API RFC sup- + ported by the API implementation. This should match the value + of the LDAP_API_VERSION macro defined earlier. + +ldapai_protocol_version + The highest LDAP protocol version supported by the implementa- + tion. For example, if LDAPv3 is the highest version supported + then this field will be set to 3. + +ldapai_extensions + A NULL-terminated array of character strings that lists the + names of the API extensions supported by the LDAP API imple- + mentation. These names will typically match the textual iden- + tifiers that appear in the "x" portion of the + LDAP_API_FEATURE_x macros described above, although the pre- + cise value MUST be defined by documents that specify C LDAP + API extensions. If no API extensions are supported, this + field will be set to NULL. The caller is responsible for + disposing of the memory occupied by this array by passing it + to ldap_value_free() which is described later in this docu- + ment. To retrieve more information about a particular exten- + sion, the ldap_get_option() call can be used with an option + parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt- + data parameter to the ldap_get_option() MUST be the address of + an LDAPAPIFeatureInfo structure which is defined as follows: + + typedef struct ldap_apifeature_info { + int ldapaif_info_version; /* version of this struct (1) */ + char *ldapaif_name; /* name of supported feature */ + int ldapaif_version; /* revision of supported feature */ + } LDAPAPIFeatureInfo; + + In addition, API implementations MUST include the following + macro definition: + + + + +Expires: 23 August 1999 [Page 11] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_FEATURE_INFO_VERSION 1 + + Note that the ldapaif_info_version field of the LDAPAPI- + FeatureInfo structure should be set to the value + LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field + should be set to the extension name string as described below + before ldap_get_option() is called. The call will fill in the + ldapaif_version field of the LDAPAPIFeatureInfo structure. + + The members of the LDAPAPIFeatureInfo structure are: + + ldapaif_info_version + A number that identifies the version of the LDAPAPI- + FeatureInfo structure. This should be set to the value + LDAP_FEATURE_INFO_VERSION (1) before calling + ldap_get_option(). If the value received is not recognized + by the API implementation, the ldap_get_option() function + sets ldapaif_info_version to a valid value that would be + recognized and returns an error without filling in the + ldapaif_version field in the LDAPAPIFeatureInfo structure. + + ldapaif_name + The name of an extension, as returned in the + ldapai_extensions array of the LDAPAPIInfo structure and as + specified in the document that describes the extension. + + ldapaif_version + This field will be set as a result of calling + ldap_get_option(). It is a number that matches that + assigned to the C LDAP API extension RFC supported for this + extension. For private or experimental API extensions, the + value is extension-specific. In either case, the value of + ldapaxi_ext_version should be identical to the value of the + LDAP_API_FEATURE_x macro defined for the extension + (described above). + +ldapai_vendor_name + A zero-terminated string that contains the name of the party + that produced the LDAP API implementation. This field may be + set to NULL if no name is available. If non-NULL, the caller + is responsible for disposing of the memory occupied by passing + this pointer to ldap_memfree() which is described later in + this document. This value SHOULD match the value of the + LDAP_VENDOR_NAME macro described earlier in this document. + +ldapai_vendor_version + An implementation-specific version number multiplied by 100. + For example, if the implementation version is 4.0 then this + + + +Expires: 23 August 1999 [Page 12] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + field will be set to 400. If no version information is avail- + able, this field will be set to 0. This value SHOULD match + the value of the LDAP_VENDOR_VERSION macro described earlier + in this document. + + +9. LDAP Error Codes + +Many of the LDAP API routines return LDAP error codes, some of which +indicate local errors and some of which may be returned by servers. All +of the LDAP error codes returned will be positive integers. Supported +error codes are (hexadecimal values are given in parentheses after the +constant): + + LDAP_SUCCESS (0x00) + LDAP_OPERATIONS_ERROR (0x01) + LDAP_PROTOCOL_ERROR (0x02) + LDAP_TIMELIMIT_EXCEEDED (0x03) + LDAP_SIZELIMIT_EXCEEDED (0x04) + LDAP_COMPARE_FALSE (0x05) + LDAP_COMPARE_TRUE (0x06) + LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) + LDAP_STRONG_AUTH_REQUIRED (0x08) + LDAP_REFERRAL (0x0a) -- new in LDAPv3 + LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 + LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 + LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 + LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 + LDAP_NO_SUCH_ATTRIBUTE (0x10) + LDAP_UNDEFINED_TYPE (0x11) + LDAP_INAPPROPRIATE_MATCHING (0x12) + LDAP_CONSTRAINT_VIOLATION (0x13) + LDAP_TYPE_OR_VALUE_EXISTS (0x14) + LDAP_INVALID_SYNTAX (0x15) + LDAP_NO_SUCH_OBJECT (0x20) + LDAP_ALIAS_PROBLEM (0x21) + LDAP_INVALID_DN_SYNTAX (0x22) + LDAP_IS_LEAF (0x23) -- not used in LDAPv3 + LDAP_ALIAS_DEREF_PROBLEM (0x24) + LDAP_INAPPROPRIATE_AUTH (0x30) + LDAP_INVALID_CREDENTIALS (0x31) + LDAP_INSUFFICIENT_ACCESS (0x32) + LDAP_BUSY (0x33) + LDAP_UNAVAILABLE (0x34) + LDAP_UNWILLING_TO_PERFORM (0x35) + LDAP_LOOP_DETECT (0x36) + LDAP_NAMING_VIOLATION (0x40) + LDAP_OBJECT_CLASS_VIOLATION (0x41) + + + +Expires: 23 August 1999 [Page 13] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) + LDAP_NOT_ALLOWED_ON_RDN (0x43) + LDAP_ALREADY_EXISTS (0x44) + LDAP_NO_OBJECT_CLASS_MODS (0x45) + LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP + LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 + LDAP_OTHER (0x50) + LDAP_SERVER_DOWN (0x51) + LDAP_LOCAL_ERROR (0x52) + LDAP_ENCODING_ERROR (0x53) + LDAP_DECODING_ERROR (0x54) + LDAP_TIMEOUT (0x55) + LDAP_AUTH_UNKNOWN (0x56) + LDAP_FILTER_ERROR (0x57) + LDAP_USER_CANCELLED (0x58) + LDAP_PARAM_ERROR (0x59) + LDAP_NO_MEMORY (0x5a) + LDAP_CONNECT_ERROR (0x5b) + LDAP_NOT_SUPPORTED (0x5c) + LDAP_CONTROL_NOT_FOUND (0x5d) + LDAP_NO_RESULTS_RETURNED (0x5e) + LDAP_MORE_RESULTS_TO_RETURN (0x5f) + LDAP_CLIENT_LOOP (0x60) + LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) + + +10. Performing LDAP Operations + +This section describes each LDAP operation API call in detail. All func- +tions take a "session handle," a pointer to an LDAP structure containing +per-connection information. Many routines return results in an LDAPMes- +sage structure. These structures and others are described as needed +below. + + +10.1. Initializing an LDAP Session + +ldap_init() initializes a session with an LDAP server. The server is not +actually contacted until an operation is performed that requires it, +allowing various options to be set after initialization. + + LDAP *ldap_init( + const char *hostname, + int portno + ); + +Use of the following routine is deprecated: + + + + +Expires: 23 August 1999 [Page 14] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ldap_open( + const char *hostname, + int portno + ); +Unlike ldap_init(), ldap_open() attempts to make a server connection +before returning to the caller. + +Parameters are: + +hostname Contains a space-separated list of hostnames or dotted strings + representing the IP address of hosts running an LDAP server to + connect to. Each hostname in the list can include an optional + port number which is separated from the host itself with a + colon (:) character. The hosts will be tried in the order + listed, stopping with the first one to which a successful con- + nection is made. + + Note: A suitable representation for including a literal IPv6[11] + address in the hostname parameter is desired, but has not yet been + determined or implemented in practice. + +portno Contains the TCP port number to connect to. The default LDAP + port of 389 can be obtained by supplying the constant + LDAP_PORT. If a host includes a port number then this parame- + ter is ignored. + +ldap_init() and ldap_open() both return a "session handle," a pointer to +an opaque structure that should be passed to subsequent calls pertaining +to the session. These routines return NULL if the session cannot be ini- +tialized in which case the operating system error reporting mechanism +can be checked to see why the call failed. + +Note that if you connect to an LDAPv2 server, one of the LDAP bind calls +described below must be completed before other operations can be per- +formed on the session. LDAPv3 does not require that a bind operation be +completed before other operations can be performed. + +The calling program can set various attributes of the session by calling +the routines described in the next section. + + +10.2. LDAP Session Handle Options + +The LDAP session handle returned by ldap_init() is a pointer to an +opaque data type representing an LDAP session. In RFC 1823 this data +type was a structure exposed to the caller, and various fields in the +structure could be set to control aspects of the session, such as size +and time limits on searches. + + + +Expires: 23 August 1999 [Page 15] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +In the interest of insulating callers from inevitable changes to this +structure, these aspects of the session are now accessed through a pair +of accessor functions, described below. + +ldap_get_option() is used to access the current value of various +session-wide parameters. ldap_set_option() is used to set the value of +these parameters. Note that some options are READ-ONLY and cannot be +set; it is an error to call ldap_set_option() and attempt to set a +READ-ONLY option. + +Note that if automatic referral following is enabled (the default), any +connections created during the course of following referrals will +inherit the options associated with the session that sent the original +request that caused the referrals to be returned. + + int ldap_get_option( + LDAP *ld, + int option, + void *outvalue + ); + + int ldap_set_option( + LDAP *ld, + int option, + const void *invalue + ); + + #define LDAP_OPT_ON ((void *)1) + #define LDAP_OPT_OFF ((void *)0) + + +Parameters are: + +ld The session handle. If this is NULL, a set of global defaults is + accessed. New LDAP session handles created with ldap_init() or + ldap_open() inherit their characteristics from these global + defaults. + +option The name of the option being accessed or set. This parameter + should be one of the following constants, which have the indi- + cated meanings. After the constant the actual hexadecimal value + of the constant is listed in parentheses. + + + LDAP_OPT_API_INFO (0x00) + Type for invalue parameter: not applicable (option is READ-ONLY) + + Type for outvalue parameter: LDAPAPIInfo * + + + +Expires: 23 August 1999 [Page 16] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Description: + Used to retrieve some basic information about the LDAP API + implementation at execution time. See the section "Retriev- + ing Information About the API Implementation" above for more + information. This option is READ-ONLY and cannot be set. + + LDAP_OPT_DESC (0x01) + Type for invalue parameter: not applicable (option is READ- + ONLY) + + Type for outvalue parameter: int * + + Description: + The underlying socket descriptor corresponding to the pri- + mary LDAP connection. This option is READ-ONLY and cannot + be set. + + LDAP_OPT_DEREF (0x02) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + Determines how aliases are handled during search. It can + have one of the following values: LDAP_DEREF_NEVER (0x00), + LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or + LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value + means aliases should be dereferenced during the search but + not when locating the base object of the search. The + LDAP_DEREF_FINDING value means aliases should be derefer- + enced when locating the base object but not during the + search. + + LDAP_OPT_SIZELIMIT (0x03) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + A limit on the number of entries to return from a search. + A value of LDAP_NO_LIMIT (0) means no limit. + + LDAP_OPT_TIMELIMIT (0x04) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + + + +Expires: 23 August 1999 [Page 17] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + A limit on the number of seconds to spend on a search. A + value of LDAP_NO_LIMIT (0) means no limit. This value is + passed to the server in the search request only; it does + not affect how long the C LDAP API implementation itself + will wait locally for search results. The timeout parame- + ter passed to ldap_search_ext_s() or ldap_result() -- both + of which are described later in this document -- can be + used to specify both a local and server side time limit. + + LDAP_OPT_REFERRALS (0x08) + Type for invalue parameter: void * (LDAP_OPT_ON or + LDAP_OPT_OFF) + + Type for outvalue parameter: int * + + Description: + Determines whether the LDAP library automatically follows + referrals returned by LDAP servers or not. It can be set + to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any + non-NULL pointer value passed to ldap_set_option() enables + this option. When reading the current setting using + ldap_get_option(), a zero value means off and any non-zero + value means on. + + LDAP_OPT_RESTART (0x09) + Type for invalue parameter: void * (LDAP_OPT_ON or + LDAP_OPT_OFF) + + Type for outvalue parameter: int * + + Description: + Determines whether LDAP I/O operations should automati- + cally be restarted if they abort prematurely. It should be + set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; + any non-NULL pointer value passed to ldap_set_option() + enables this option. When reading the current setting + using ldap_get_option(), a zero value means off and any + non-zero value means on. This option is useful if an LDAP + I/O operation may be interrupted prematurely, for example + by a timer going off, or other interrupt. + + LDAP_OPT_PROTOCOL_VERSION (0x11) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + This option indicates the version of the LDAP protocol + + + +Expires: 23 August 1999 [Page 18] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + used when communicating with the primary LDAP server. It + must be one of the constants LDAP_VERSION2 (2) or + LDAP_VERSION3 (3). If no version is set the default is + LDAP_VERSION2 (2). + + LDAP_OPT_SERVER_CONTROLS (0x12) + Type for invalue parameter: LDAPControl ** + + Type for outvalue parameter: LDAPControl *** + + Description: + A default list of LDAP server controls to be sent with + each request. See the Working With Controls section + below. + + LDAP_OPT_CLIENT_CONTROLS (0x13) + Type for invalue parameter: LDAPControl ** + + Type for outvalue parameter: LDAPControl *** + + Description: + A default list of client controls that affect the LDAP + session. See the Working With Controls section below. + + LDAP_OPT_API_FEATURE_INFO (0x15) + Type for invalue parameter: not applicable (option is READ- + ONLY) + + Type for outvalue parameter: LDAPAPIFeatureInfo * + + Description: + Used to retrieve version information about LDAP API + extended features at execution time. See the section + "Retrieving Information About the API Implementation" + above for more information. This option is READ-ONLY and + cannot be set. + + LDAP_OPT_HOST_NAME (0x30) + Type for invalue parameter: char * + + Type for outvalue parameter: char ** + + Description: + The host name (or list of hosts) for the primary LDAP + server. See the definition of the hostname parameter to + ldap_init() for the allowed syntax. + + LDAP_OPT_ERROR_NUMBER (0x31) + + + +Expires: 23 August 1999 [Page 19] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + The code of the most recent LDAP error that occurred for + this session. + + LDAP_OPT_ERROR_STRING (0x32) + Type for invalue parameter: char * + + Type for outvalue parameter: char ** + + Description: + The message returned with the most recent LDAP error that + occurred for this session. + + + outvalue The address of a place to put the value of the option. The + actual type of this parameter depends on the setting of the + option parameter. For outvalues of type char ** and LDAP- + Control **, a copy of the data that is associated with the + LDAP session ld is returned; callers should dispose of the + memory by calling ldap_memfree() or ldap_controls_free(). + + invalue A pointer to the value the option is to be given. The actual + type of this parameter depends on the setting of the option + parameter. The data associated with invalue is copied by the + API implementation to allow callers of the API to dispose of + or otherwise change their copy of the data after a success- + ful call to ldap_set_option(). If a value passed for + invalue is invalid or cannot be accepted by the implementa- + tion, ldap_set_option() should return -1 to indicate an + error. + +Both ldap_get_option() and ldap_set_option() return 0 if successful and +-1 if an error occurs. + +Standards track documents that extend this specification and specify new +options MUST use values for option macros that are between 0x1000 and +0x3FFF inclusive. Private and experimental extensions MUST use values +for the option macros that are between 0x4000 and 0x7FFF inclusive. All +values below 0x1000 and above 0x7FFF that are not defined in this docu- +ment are reserved and MUST NOT be used. + + + + + + + +Expires: 23 August 1999 [Page 20] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +10.3. Working With Controls + +LDAPv3 operations can be extended through the use of controls. Controls +may be sent to a server or returned to the client with any LDAP message. +These controls are referred to as server controls. + +The LDAP API also supports a client-side extension mechanism through the +use of client controls. These controls affect the behavior of the LDAP +API only and are never sent to a server. A common data structure is +used to represent both types of controls: + + typedef struct ldapcontrol { + char *ldctl_oid; + struct berval ldctl_value; + char ldctl_iscritical; + } LDAPControl, *PLDAPControl; + +The fields in the ldapcontrol structure have the following meanings: + +ldctl_oid The control type, represented as a string. + +ldctl_value The data associated with the control (if any). To + specify a zero-length value, set ldctl_value.bv_len to + zero and ldctl_value.bv_val to a zero-length string. + To indicate that no data is associated with the con- + trol, set ldctl_value.bv_val to NULL. + +ldctl_iscritical Indicates whether the control is critical of not. If + this field is non-zero, the operation will only be car- + ried out if the control is recognized by the server + and/or client. Note that the LDAP unbind and abandon + operations have no server response, so clients SHOULD + NOT mark server controls critical when used with these + two operations. + +Some LDAP API calls allocate an ldapcontrol structure or a NULL- +terminated array of ldapcontrol structures. The following routines can +be used to dispose of a single control or an array of controls: + + void ldap_control_free( LDAPControl *ctrl ); + void ldap_controls_free( LDAPControl **ctrls ); + +A set of controls that affect the entire session can be set using the +ldap_set_option() function (see above). A list of controls can also be +passed directly to some LDAP API calls such as ldap_search_ext(), in +which case any controls set for the session through the use of +ldap_set_option() are ignored. Control lists are represented as a NULL- +terminated array of pointers to ldapcontrol structures. + + + +Expires: 23 August 1999 [Page 21] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Server controls are defined by LDAPv3 protocol extension documents; for +example, a control has been proposed to support server-side sorting of +search results [7]. + +One client control is defined in this document (described in the follow- +ing section). Other client controls may be defined in future revisions +of this document or in documents that extend this API. + + +10.3.1. A Client Control That Governs Referral Processing + +As described previously in the section "LDAP Session Handle Options," +applications can enable and disable automatic chasing of referrals on a +session-wide basic by using the ldap_set_option() function with the +LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer- +ral chasing on per-request basis. A client control with an OID of +1.2.840.113556.1.4.616 exists to provide this functionality. + + /* OID for referrals client control */ + #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" + + /* Flags for referrals client control value */ + #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020 + #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040 + +To create a referrals client control, the ldctl_oid field of an LDAPCon- +trol structure should be set to LDAP_CONTROL_REFERRALS +("1.2.840.113556.1.4.616") and the ldctl_value field should be set to a +4-octet value that contains a set of flags. The ldctl_value.bv_len +field should always be set to 4. The ldctl_value.bv_val field should +point to a 4-octet integer flags value. This flags value can be set to +zero to disable automatic chasing of referrals and LDAPv3 references +altogether. Alternatively, the flags value can be set to the value +LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020) to indicate that only +LDAPv3 search continuation references should be automatically chased by +the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS +(0x00000040) to indicate that only LDAPv3 referrals should be automati- +cally chased, or the logical OR of the two flag values (0x00000060) to +indicate that both referrals and references should be automatically +chased. + + +10.4. Authenticating to the directory + +The following functions are used to authenticate an LDAP client to an +LDAP directory server. + +The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do + + + +Expires: 23 August 1999 [Page 22] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +general and extensible authentication over LDAP through the use of the +Simple Authentication Security Layer [8]. The routines both take the dn +to bind as, the method to use, as a dotted-string representation of an +OID identifying the method, and a struct berval holding the credentials. +The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to +request simple authentication, or the simplified routines +ldap_simple_bind() or ldap_simple_bind_s() can be used. + + int ldap_sasl_bind( + LDAP *ld, + const char *dn, + const char *mechanism, + const struct berval *cred, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_sasl_bind_s( + LDAP *ld, + const char *dn, + const char *mechanism, + const struct berval *cred, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct berval **servercredp + ); + + int ldap_simple_bind( + LDAP *ld, + const char *dn, + const char *passwd + ); + + int ldap_simple_bind_s( + LDAP *ld, + const char *dn, + const char *passwd + ); + + The use of the following routines is deprecated: + + int ldap_bind( LDAP *ld, const char *dn, const char *cred, + int method ); + + int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, + int method ); + + + + +Expires: 23 August 1999 [Page 23] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_kerberos_bind( LDAP *ld, const char *dn ); + + int ldap_kerberos_bind_s( LDAP *ld, const char *dn ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to bind as. + +mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica- + tion, or a text string identifying the SASL method. + +cred The credentials with which to authenticate. Arbitrary + credentials can be passed using this parameter. The format + and content of the credentials depends on the setting of + the mechanism parameter. + +passwd For ldap_simple_bind(), the password to compare to the + entry's userPassword attribute. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_sasl_bind() call succeeds. + +servercredp This result parameter will be filled in with the creden- + tials passed back by the server for mutual authentication, + if given. An allocated berval structure is returned that + should be disposed of by calling ber_bvfree(). NULL may be + passed to ignore this field. + +Additional parameters for the deprecated routines are not described. +Interested readers are referred to RFC 1823. + +The ldap_sasl_bind() function initiates an asynchronous bind operation +and returns the constant LDAP_SUCCESS if the request was successfully +sent, or another LDAP error code if not. See the section below on error +handling for more information about possible errors and how to interpret +them. If successful, ldap_sasl_bind() places the message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the bind. + +The ldap_simple_bind() function initiates a simple asynchronous bind +operation and returns the message id of the operation initiated. A sub- +sequent call to ldap_result(), described below, can be used to obtain + + + +Expires: 23 August 1999 [Page 24] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +the result of the bind. In case of error, ldap_simple_bind() will return +-1, setting the session error parameters in the LDAP structure appropri- +ately. + +The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions +both return the result of the operation, either the constant +LDAP_SUCCESS if the operation was successful, or another LDAP error code +if it was not. See the section below on error handling for more informa- +tion about possible errors and how to interpret them. + +Note that if an LDAPv2 server is contacted, no other operations over the +connection should be attempted before a bind call has successfully com- +pleted. + +Subsequent bind calls can be used to re-authenticate over the same con- +nection, and multistep SASL sequences can be accomplished through a +sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). + + +10.5. Closing the session + +The following functions are used to unbind from the directory, close +open connections, and dispose of the session handle. + + int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, + LDAPControl **clientctrls ); + + int ldap_unbind( LDAP *ld ); + + int ldap_unbind_s( LDAP *ld ); + +Parameters are: + +ld The session handle. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn- +chronously in the sense that they send an unbind request to the server, +close all open connections associated with the LDAP session handle, and +dispose of all resources associated with the session handle before +returning. Note, however, that there is no server response to an LDAP +unbind operation. All three of the unbind functions return LDAP_SUCCESS +(or another LDAP error code if the request cannot be sent to the LDAP +server). After a call to one of the unbind functions, the session han- +dle ld is invalid and it is illegal to make any further LDAP API calls + + + +Expires: 23 August 1999 [Page 25] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +using ld. + +The ldap_unbind() and ldap_unbind_s() functions behave identically. The +ldap_unbind_ext() function allows server and client controls to be +included explicitly, but note that since there is no server response to +an unbind request there is no way to receive a response to a server con- +trol sent with an unbind request. + + + +10.6. Searching + +The following functions are used to search the LDAP directory, returning +a requested set of attributes for each entry matched. There are five +variations. + + int ldap_search_ext( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct timeval *timeout, + int sizelimit, + int *msgidp + ); + + int ldap_search_ext_s( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct timeval *timeout, + int sizelimit, + LDAPMessage **res + ); + + int ldap_search( + LDAP *ld, + const char *base, + int scope, + + + +Expires: 23 August 1999 [Page 26] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *filter, + char **attrs, + int attrsonly + ); + + int ldap_search_s( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPMessage **res + ); + + int ldap_search_st( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + struct timeval *timeout, + LDAPMessage **res + ); + +Parameters are: + +ld The session handle. + +base The dn of the entry at which to start the search. + +scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), + or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the + search. + +filter A character string as described in [3], representing the + search filter. The value NULL can be passed to indicate + that the filter "(objectclass=*)" which matches all entries + should be used. Note that if the caller of the API is + using LDAPv2, only a subset of the filter functionality + described in [3] can be successfully used. + +attrs A NULL-terminated array of strings indicating which attri- + butes to return for each matching entry. Passing NULL for + this parameter causes all available user attributes to be + retrieved. The special constant string LDAP_NO_ATTRS + ("1.1") can be used as the only string in the array to + + + +Expires: 23 August 1999 [Page 27] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + indicate that no attribute types should be returned by the + server. The special constant string LDAP_ALL_USER_ATTRS + ("*") can be used in the attrs array along with the names + of some operational attributes to indicate that all user + attributes plus the listed operational attributes should be + returned. + +attrsonly A boolean value that should be zero if both attribute types + and values are to be returned, non-zero if only types are + wanted. + +timeout For the ldap_search_st() function, this specifies the local + search timeout value (if it is NULL, the timeout is infin- + ite). For the ldap_search_ext() and ldap_search_ext_s() + functions, this specifies both the local search timeout + value and the operation time limit that is sent to the + server within the search request. For the + ldap_search_ext() and ldap_search_ext_s() functions, pass- + ing a NULL value for timeout causes the global default + timeout stored in the LDAP session handle (set by using + ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to + be sent to the server with the request but an infinite + local search timeout to be used. + +sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, + this is a limit on the number of entries to return from the + search. A value of LDAP_NO_LIMIT (0) means no limit. + +res For the synchronous calls, this is a result parameter which + will contain the results of the search upon completion of + the call. If no results are returned, *res is set to NULL. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_search_ext() call succeeds. + +There are three options in the session handle ld which potentially +affect how the search is performed. They are: + +LDAP_OPT_SIZELIMIT + A limit on the number of entries to return from the search. + A value of LDAP_NO_LIMIT (0) means no limit. Note that the + value from the session handle is ignored when using the + ldap_search_ext() or ldap_search_ext_s() functions. + + + + +Expires: 23 August 1999 [Page 28] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +LDAP_OPT_TIMELIMIT + A limit on the number of seconds to spend on the search. A + value of LDAP_NO_LIMIT (0) means no limit. Note that the + value from the session handle is ignored when using the + ldap_search_ext() or ldap_search_ext_s() functions. + +LDAP_OPT_DEREF + One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING + (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS + (0x03), specifying how aliases should be handled during the + search. The LDAP_DEREF_SEARCHING value means aliases should + be dereferenced during the search but not when locating the + base object of the search. The LDAP_DEREF_FINDING value + means aliases should be dereferenced when locating the base + object but not during the search. + +The ldap_search_ext() function initiates an asynchronous search opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_search_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the results from the search. These results +can be parsed using the result parsing routines described in detail +later. + +Similar to ldap_search_ext(), the ldap_search() function initiates an +asynchronous search operation and returns the message id of the opera- +tion initiated. As for ldap_search_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +bind. In case of error, ldap_search() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_search_ext_s(), ldap_search_s(), and +ldap_search_st() functions all return the result of the operation, +either the constant LDAP_SUCCESS if the operation was successful, or +another LDAP error code if it was not. See the section below on error +handling for more information about possible errors and how to interpret +them. Entries returned from the search (if any) are contained in the +res parameter. This parameter is opaque to the caller. Entries, attri- +butes, values, etc., should be extracted by calling the parsing routines +described below. The results contained in res should be freed when no +longer in use by calling ldap_msgfree(), described later. + +The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 +server controls, client controls, and allow varying size and time limits +to be easily specified for each search operation. The ldap_search_st() +function is identical to ldap_search_s() except that it takes an + + + +Expires: 23 August 1999 [Page 29] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +additional parameter specifying a local timeout for the search. The +local search timeout is used to limit the amount of time the API imple- +mentation will wait for a search to complete. After the local search +timeout expires, the API implementation will send an abandon operation +to abort the search operation. + +10.7. Reading an Entry + +LDAP does not support a read operation directly. Instead, this operation +is emulated by a search with base set to the DN of the entry to read, +scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or +NULL. attrs contains the list of attributes to return. + + +10.8. Listing the Children of an Entry + +LDAP does not support a list operation directly. Instead, this operation +is emulated by a search with base set to the DN of the entry to list, +scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or +NULL. attrs contains the list of attributes to return for each child +entry. + +10.9. Comparing a Value Against an Entry + +The following routines are used to compare a given attribute value +assertion against an LDAP entry. There are four variations: + + int ldap_compare_ext( + LDAP *ld, + const char *dn, + const char *attr, + struct berval *bvalue + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_compare_ext_s( + LDAP *ld, + const char *dn, + const char *attr, + struct berval *bvalue, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_compare( + LDAP *ld, + + + +Expires: 23 August 1999 [Page 30] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *dn, + const char *attr, + const char *value + ); + + int ldap_compare_s( + LDAP *ld, + const char *dn, + const char *attr, + const char *value + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to compare against. + +attr The attribute to compare against. + +bvalue The attribute value to compare against those found in the + given entry. This parameter is used in the extended rou- + tines and is a pointer to a struct berval so it is possible + to compare binary values. + +value A string attribute value to compare against, used by the + ldap_compare() and ldap_compare_s() functions. Use + ldap_compare_ext() or ldap_compare_ext_s() if you need to + compare binary values. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_compare_ext() call succeeds. + +The ldap_compare_ext() function initiates an asynchronous compare opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_compare_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the compare. + +Similar to ldap_compare_ext(), the ldap_compare() function initiates an +asynchronous compare operation and returns the message id of the opera- +tion initiated. As for ldap_compare_ext(), a subsequent call to + + + +Expires: 23 August 1999 [Page 31] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +ldap_result(), described below, can be used to obtain the result of the +bind. In case of error, ldap_compare() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + +The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.10. Modifying an entry + +The following routines are used to modify an existing LDAP entry. There +are four variations: + + typedef struct ldapmod { + int mod_op; + char *mod_type; + union { + char **modv_strvals; + struct berval **modv_bvals; + } mod_vals; + } LDAPMod; + #define mod_values mod_vals.modv_strvals + #define mod_bvalues mod_vals.modv_bvals + + int ldap_modify_ext( + LDAP *ld, + const char *dn, + LDAPMod **mods, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_modify_ext_s( + LDAP *ld, + const char *dn, + LDAPMod **mods, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_modify( + + + +Expires: 23 August 1999 [Page 32] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + const char *dn, + LDAPMod **mods + ); + + int ldap_modify_s( + LDAP *ld, + const char *dn, + LDAPMod **mods + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to modify. + +mods A NULL-terminated array of modifications to make to the + entry. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_modify_ext() call succeeds. + +The fields in the LDAPMod structure have the following meanings: + +mod_op The modification operation to perform. It should be one of + LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or + LDAP_MOD_REPLACE (0x02). This field also indicates the + type of values included in the mod_vals union. It is logi- + cally ORed with LDAP_MOD_BVALUES (0x80) to select the + mod_bvalues form. Otherwise, the mod_values form is used. + +mod_type The type of the attribute to modify. + +mod_vals The values (if any) to add, delete, or replace. Only one of + the mod_values or mod_bvalues variants should be used, + selected by ORing the mod_op field with the constant + LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of + zero-terminated strings and mod_bvalues is a NULL- + terminated array of berval structures that can be used to + pass binary values such as images. + +For LDAP_MOD_ADD modifications, the given values are added to the +entry, creating the attribute if necessary. + + + +Expires: 23 August 1999 [Page 33] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +For LDAP_MOD_DELETE modifications, the given values are deleted from the +entry, removing the attribute if no values remain. If the entire attri- +bute is to be deleted, the mod_vals field should be set to NULL. + +For LDAP_MOD_REPLACE modifications, the attribute will have the listed +values after the modification, having been created if necessary, or +removed if the mod_vals field is NULL. All modifications are performed +in the order in which they are listed. + +The ldap_modify_ext() function initiates an asynchronous modify opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_modify_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the modify. + +Similar to ldap_modify_ext(), the ldap_modify() function initiates an +asynchronous modify operation and returns the message id of the opera- +tion initiated. As for ldap_modify_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +modify. In case of error, ldap_modify() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + +The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.11. Modifying the Name of an Entry + +In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and +ldap_modrdn2_s() routines were used to change the name of an LDAP entry. +They could only be used to change the least significant component of a +name (the RDN or relative distinguished name). LDAPv3 provides the +Modify DN protocol operation that allows more general name change +access. The ldap_rename() and ldap_rename_s() routines are used to +change the name of an entry, and the use of the ldap_modrdn(), +ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre- +cated. + + int ldap_rename( + LDAP *ld, + + + +Expires: 23 August 1999 [Page 34] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *dn, + const char *newrdn, + const char *newparent, + int deleteoldrdn, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + + ); + int ldap_rename_s( + LDAP *ld, + const char *dn, + const char *newrdn, + const char *newparent, + int deleteoldrdn, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + Use of the following routines is deprecated. + + int ldap_modrdn( + LDAP *ld, + const char *dn, + const char *newrdn + ); + int ldap_modrdn_s( + LDAP *ld, + const char *dn, + const char *newrdn + ); + int ldap_modrdn2( + LDAP *ld, + const char *dn, + const char *newrdn, + int deleteoldrdn + ); + int ldap_modrdn2_s( + LDAP *ld, + const char *dn, + const char *newrdn, + int deleteoldrdn + ); + +Parameters are: + +ld The session handle. + + + + +Expires: 23 August 1999 [Page 35] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +dn The name of the entry whose DN is to be changed. + +newrdn The new RDN to give the entry. + +newparent The new parent, or superior entry. If this parameter is + NULL, only the RDN of the entry is changed. The root DN + may be specified by passing a zero length string, "". The + newparent parameter should always be NULL when using ver- + sion 2 of the LDAP protocol; otherwise the server's + behavior is undefined. + +deleteoldrdn This parameter only has meaning on the rename routines if + newrdn is different than the old RDN. It is a boolean + value, if non-zero indicating that the old RDN value(s) + should be removed, if zero indicating that the old RDN + value(s) should be retained as non-distinguished values of + the entry. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_rename() call succeeds. + +The ldap_rename() function initiates an asynchronous modify DN operation +and returns the constant LDAP_SUCCESS if the request was successfully +sent, or another LDAP error code if not. See the section below on error +handling for more information about possible errors and how to interpret +them. If successful, ldap_rename() places the DN message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the rename. + +The synchronous ldap_rename_s() returns the result of the operation, +either the constant LDAP_SUCCESS if the operation was successful, or +another LDAP error code if it was not. See the section below on error +handling for more information about possible errors and how to interpret +them. + +The ldap_rename() and ldap_rename_s() functions both support LDAPv3 +server controls and client controls. + + +10.12. Adding an entry + +The following functions are used to add entries to the LDAP directory. +There are four variations: + + + + +Expires: 23 August 1999 [Page 36] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_add_ext( + LDAP *ld, + const char *dn, + LDAPMod **attrs, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_add_ext_s( + LDAP *ld, + const char *dn, + LDAPMod **attrs, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_add( + LDAP *ld, + const char *dn, + LDAPMod **attrs + ); + + int ldap_add_s( + LDAP *ld, + const char *dn, + LDAPMod **attrs + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to add. + +attrs The entry's attributes, specified using the LDAPMod struc- + ture defined for ldap_modify(). The mod_type and mod_vals + fields should be filled in. The mod_op field is ignored + unless ORed with the constant LDAP_MOD_BVALUES, used to + select the mod_bvalues case of the mod_vals union. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_add_ext() call succeeds. + + + + +Expires: 23 August 1999 [Page 37] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Note that the parent of the entry being added must already exist or the +parent must be empty (i.e., equal to the root DN) for an add to succeed. + +The ldap_add_ext() function initiates an asynchronous add operation and +returns the constant LDAP_SUCCESS if the request was successfully sent, +or another LDAP error code if not. See the section below on error han- +dling for more information about possible errors and how to interpret +them. If successful, ldap_add_ext() places the message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the add. + +Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- +chronous add operation and returns the message id of the operation ini- +tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), +described below, can be used to obtain the result of the add. In case of +error, ldap_add() will return -1, setting the session error parameters +in the LDAP structure appropriately. + +The synchronous ldap_add_ext_s() and ldap_add_s() functions both return +the result of the operation, either the constant LDAP_SUCCESS if the +operation was successful, or another LDAP error code if it was not. See +the section below on error handling for more information about possible +errors and how to interpret them. + +The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server +controls and client controls. + + + +10.13. Deleting an entry + +The following functions are used to delete a leaf entry from the LDAP +directory. There are four variations: + + int ldap_delete_ext( + LDAP *ld, + const char *dn, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_delete_ext_s( + LDAP *ld, + const char *dn, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + + +Expires: 23 August 1999 [Page 38] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + + int ldap_delete( + LDAP *ld, + const char *dn + ); + + int ldap_delete_s( + LDAP *ld, + const char *dn + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to delete. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_delete_ext() call succeeds. + +Note that the entry to delete must be a leaf entry (i.e., it must have +no children). Deletion of entire subtrees in a single operation is not +supported by LDAP. + +The ldap_delete_ext() function initiates an asynchronous delete opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_delete_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the delete. + +Similar to ldap_delete_ext(), the ldap_delete() function initiates an +asynchronous delete operation and returns the message id of the opera- +tion initiated. As for ldap_delete_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +delete. In case of error, ldap_delete() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + + + +Expires: 23 August 1999 [Page 39] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.14. Extended Operations + +The ldap_extended_operation() and ldap_extended_operation_s() routines +allow extended LDAP operations to be passed to the server, providing a +general protocol extensibility mechanism. + + int ldap_extended_operation( + LDAP *ld, + const char *exoid, + struct berval *exdata, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_extended_operation_s( + LDAP *ld, + const char *exoid, + struct berval *exdata, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + char **retoidp, + struct berval **retdatap + ); + +Parameters are: + +ld The session handle. + +requestoid The dotted-OID text string naming the request. + +requestdata The arbitrary data required by the operation (if NULL, no + data is sent to the server). + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_extended_operation() call succeeds. + +retoidp Pointer to a character string that will be set to an allo- + cated, dotted-OID text string returned by the server. This + string should be disposed of using the ldap_memfree() + + + +Expires: 23 August 1999 [Page 40] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + function. If no OID was returned, *retoidp is set to NULL. + +retdatap Pointer to a berval structure pointer that will be set an + allocated copy of the data returned by the server. This + struct berval should be disposed of using ber_bvfree(). If + no data is returned, *retdatap is set to NULL. + +The ldap_extended_operation() function initiates an asynchronous +extended operation and returns the constant LDAP_SUCCESS if the request +was successfully sent, or another LDAP error code if not. See the sec- +tion below on error handling for more information about possible errors +and how to interpret them. If successful, ldap_extended_operation() +places the message id of the request in *msgidp. A subsequent call to +ldap_result(), described below, can be used to obtain the result of the +extended operation which can be passed to ldap_parse_extended_result() +to obtain the OID and data contained in the response. + +The synchronous ldap_extended_operation_s() function returns the result +of the operation, either the constant LDAP_SUCCESS if the operation was +successful, or another LDAP error code if it was not. See the section +below on error handling for more information about possible errors and +how to interpret them. The retoid and retdata parameters are filled in +with the OID and data from the response. If no OID or data was +returned, these parameters are set to NULL. + +The ldap_extended_operation() and ldap_extended_operation_s() functions +both support LDAPv3 server controls and client controls. + + +11. Abandoning An Operation + +The following calls are used to abandon an operation in progress: + + int ldap_abandon_ext( + LDAP *ld, + int msgid, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_abandon( + LDAP *ld, + int msgid + ); + + +ld The session handle. + + + + +Expires: 23 August 1999 [Page 41] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +msgid The message id of the request to be abandoned. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +ldap_abandon_ext() abandons the operation with message id msgid and +returns the constant LDAP_SUCCESS if the abandon was successful or +another LDAP error code if not. See the section below on error handling +for more information about possible errors and how to interpret them. + +ldap_abandon() is identical to ldap_abandon_ext() except that it does +not accept client or server controls and it returns zero if the abandon +was successful, -1 otherwise. + +After a successful call to ldap_abandon() or ldap_abandon_ext(), results +with the given message id are never returned from a subsequent call to +ldap_result(). There is no server response to LDAP abandon operations. + + +12. Obtaining Results and Peeking Inside LDAP Messages + +ldap_result() is used to obtain the result of a previous asynchronously +initiated operation. Note that depending on how it is called, +ldap_result() may actually return a list or "chain" of result messages. +The ldap_result() function only returns messages for a single request, +so for all LDAP operations other than search only one result message is +expected; that is, the only time the "result chain" may contain more +than one message is if results from a search operation are returned. +Once a chain of messages has been returned to the caller, it is no +longer tied in any caller-visible way to the LDAP request that produced +it. Therefore, a chain of messages returned by calling ldap_result() or +by calling a synchronous search routine will never be affected by subse- +quent LDAP API calls (except for ldap_msgfree() which is used to dispose +of a chain of messages). + +ldap_msgfree() frees the result messages (possibly an entire chain of +messages) obtained from a previous call to ldap_result() or from a call +to a synchronous search routine. + +ldap_msgtype() returns the type of an LDAP message. ldap_msgid() +returns the message ID of an LDAP message. + + int ldap_result( + LDAP *ld, + int msgid, + int all, + struct timeval *timeout, + + + +Expires: 23 August 1999 [Page 42] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAPMessage **res + ); + + int ldap_msgfree( LDAPMessage *res ); + + int ldap_msgtype( LDAPMessage *res ); + + int ldap_msgid( LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +msgid The message id of the operation whose results are to be + returned, or the constant LDAP_RES_ANY (-1) if any result is + desired. + +all Specifies how many messages will be retrieved in a single call + to ldap_result(). This parameter only has meaning for search + results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one + message at a time. Pass LDAP_MSG_ALL (0x01) to request that + all results of a search be received before returning all + results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to + indicate that all messages retrieved so far should be returned + in the result chain. + +timeout A timeout specifying how long to wait for results to be + returned. A NULL value causes ldap_result() to block until + results are available. A timeout value of zero seconds speci- + fies a polling behavior. + +res For ldap_result(), a result parameter that will contain the + result(s) of the operation. If no results are returned, *res is + set to NULL. For ldap_msgfree(), the result chain to be freed, + obtained from a previous call to ldap_result(), + ldap_search_s(), or ldap_search_st(). If res is NULL, nothing + is done and ldap_msgfree() returns zero. + +Upon successful completion, ldap_result() returns the type of the first +result returned in the res parameter. This will be one of the following +constants. + + LDAP_RES_BIND (0x61) + LDAP_RES_SEARCH_ENTRY (0x64) + LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 + LDAP_RES_SEARCH_RESULT (0x65) + LDAP_RES_MODIFY (0x67) + LDAP_RES_ADD (0x69) + + + +Expires: 23 August 1999 [Page 43] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_RES_DELETE (0x6B) + LDAP_RES_MODDN (0x6D) + LDAP_RES_COMPARE (0x6F) + LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 + +ldap_result() returns 0 if the timeout expired and -1 if an error +occurs, in which case the error parameters of the LDAP session handle +will be set accordingly. + +ldap_msgfree() frees the result structure pointed to by res and returns +the type of the message it freed. If res is NULL, nothing is done and +the value zero is returned. + +ldap_msgtype() returns the type of the LDAP message it is passed as a +parameter. The type will be one of the types listed above, or -1 on +error. + +ldap_msgid() returns the message ID associated with the LDAP message +passed as a parameter. + + +13. Handling Errors and Parsing Results + +The following calls are used to extract information from results and +handle errors returned by other LDAP API routines. Note that +ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- +ically be used in addition to ldap_parse_result() to retrieve all the +result information from SASL Bind and Extended Operations respectively. + + int ldap_parse_result( + LDAP *ld, + LDAPMessage *res, + int *errcodep, + char **matcheddnp, + char **errmsgp, + char ***referralsp, + LDAPControl ***serverctrlsp, + int freeit + ); + + int ldap_parse_sasl_bind_result( + LDAP *ld, + LDAPMessage *res, + struct berval **servercredp, + int freeit + ); + + int ldap_parse_extended_result( + + + +Expires: 23 August 1999 [Page 44] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + LDAPMessage *res, + char **retoidp, + struct berval **retdatap, + int freeit + ); + + char *ldap_err2string( int err ); + + The use of the following routines is deprecated. + + int ldap_result2error( + LDAP *ld, + LDAPMessage *res, + int freeit + ); + + void ldap_perror( LDAP *ld, const char *msg ); + +Parameters are: + +ld The session handle. + +res The result of an LDAP operation as returned by + ldap_result() or one of the synchronous API operation + calls. + +errcodep This result parameter will be filled in with the LDAP error + code field from the LDAPMessage message. This is the indi- + cation from the server of the outcome of the operation. + NULL may be passed to ignore this field. + +matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result + parameter will be filled in with a DN indicating how much + of the name in the request was recognized. NULL may be + passed to ignore this field. The matched DN string should + be freed by calling ldap_memfree() which is described later + in this document. + +errmsgp This result parameter will be filled in with the contents + of the error message field from the LDAPMessage message. + The error message string should be freed by calling + ldap_memfree() which is described later in this document. + NULL may be passed to ignore this field. + +referralsp This result parameter will be filled in with the contents + of the referrals field from the LDAPMessage message, indi- + cating zero or more alternate LDAP servers where the + + + +Expires: 23 August 1999 [Page 45] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + request should be retried. The referrals array should be + freed by calling ldap_value_free() which is described later + in this document. NULL may be passed to ignore this field. + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of the LDAPMessage message. + The control array should be freed by calling + ldap_controls_free() which was described earlier. + +freeit A boolean that determines whether the res parameter is + disposed of or not. Pass any non-zero value to have these + routines free res after extracting the requested informa- + tion. This is provided as a convenience; you can also use + ldap_msgfree() to free the result later. If freeit is + non-zero, the entire chain of messages represented by res + is disposed of. + +servercredp For SASL bind results, this result parameter will be filled + in with the credentials passed back by the server for + mutual authentication, if given. An allocated berval struc- + ture is returned that should be disposed of by calling + ber_bvfree(). NULL may be passed to ignore this field. + +retoidp For extended results, this result parameter will be filled + in with the dotted-OID text representation of the name of + the extended operation response. This string should be + disposed of by calling ldap_memfree(). NULL may be passed + to ignore this field. + +retdatap For extended results, this result parameter will be filled + in with a pointer to a struct berval containing the data in + the extended operation response. It should be disposed of + by calling ber_bvfree(). NULL may be passed to ignore this + field. + +err For ldap_err2string(), an LDAP error code, as returned by + ldap_parse_result() or another LDAP API call. + +Additional parameters for the deprecated routines are not described. +Interested readers are referred to RFC 1823. + +All three of the ldap_parse_*_result() routines skip over messages of +type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking +for a result message to parse. They return the constant LDAP_SUCCESS if +the result was successfully parsed and another LDAP error code if not. +Note that the LDAP error code that indicates the outcome of the opera- +tion performed by the server is placed in the errcodep +ldap_parse_result() parameter. If a chain of messages that contains + + + +Expires: 23 August 1999 [Page 46] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +more than one result message is passed to these routines they always +operate on the first result in the chain. + +ldap_err2string() is used to convert a numeric LDAP error code, as +returned by one of the three ldap_parse_*_result() routines, or one of +the synchronous API operation calls, into an informative zero-terminated +character string message describing the error. It returns a pointer to +static data. + + +14. Stepping Through a List of Results + +The ldap_first_message() and ldap_next_message() routines are used to +step through the list of messages in a result chain returned by +ldap_result(). For search operations, the result chain may actually +include referral messages, entry messages, and result messages. +ldap_count_messages() is used to count the number of messages returned. +The ldap_msgtype() function, described above, can be used to distinguish +between the different message types. + + LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); + + int ldap_count_messages( LDAP *ld, LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +res The result chain, as obtained by a call to one of the synchronous + search routines or ldap_result(). + +msg The message returned by a previous call to ldap_first_message() + or ldap_next_message(). + +ldap_first_message() and ldap_next_message() will return NULL when no +more messages exist in the result set to be returned. NULL is also +returned if an error occurs while stepping through the entries, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +ldap_count_messages() returns the number of messages contained in a +chain of results. It can also be used to count the number of messages +that remain in a chain if called with a message, entry, or reference +returned by ldap_first_message(), ldap_next_message(), +ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), +ldap_next_reference(). + + + +Expires: 23 August 1999 [Page 47] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +15. Parsing Search Results + +The following calls are used to parse the entries and references +returned by ldap_search() and friends. These results are returned in an +opaque structure that should only be accessed by calling the routines +described below. Routines are provided to step through the entries and +references returned, step through the attributes of an entry, retrieve +the name of an entry, and retrieve the values associated with a given +attribute in an entry. + + +15.1. Stepping Through a List of Entries or References + +The ldap_first_entry() and ldap_next_entry() routines are used to step +through and retrieve the list of entries from a search result chain. +The ldap_first_reference() and ldap_next_reference() routines are used +to step through and retrieve the list of continuation references from a +search result chain. ldap_count_entries() is used to count the number +of entries returned. ldap_count_references() is used to count the number +of references returned. + + LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); + + LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); + + int ldap_count_entries( LDAP *ld, LDAPMessage *res ); + + int ldap_count_references( LDAP *ld, LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +res The search result, as obtained by a call to one of the synchro- + nous search routines or ldap_result(). + +entry The entry returned by a previous call to ldap_first_entry() or + ldap_next_entry(). + +ref The reference returned by a previous call to + ldap_first_reference() or ldap_next_reference(). + +ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and +ldap_next_reference() all return NULL when no more entries or references + + + +Expires: 23 August 1999 [Page 48] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +exist in the result set to be returned. NULL is also returned if an +error occurs while stepping through the entries or references, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +ldap_count_entries() returns the number of entries contained in a chain +of entries. It can also be used to count the number of entries that +remain in a chain if called with a message, entry or reference returned +by ldap_first_message(), ldap_next_message(), ldap_first_entry(), +ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). + +ldap_count_references() returns the number of references contained in a +chain of search results. It can also be used to count the number of +references that remain in a chain. + + +15.2. Stepping Through the Attributes of an Entry + +The ldap_first_attribute() and ldap_next_attribute() calls are used to +step through the list of attribute types returned with an entry. + + char *ldap_first_attribute( + LDAP *ld, + LDAPMessage *entry, + BerElement **ptr + ); + + char *ldap_next_attribute( + LDAP *ld, + LDAPMessage *entry, + BerElement *ptr + ); + + void ldap_memfree( char *mem ); + +Parameters are: + +ld The session handle. + +entry The entry whose attributes are to be stepped through, as returned + by ldap_first_entry() or ldap_next_entry(). + +ptr In ldap_first_attribute(), the address of a pointer used inter- + nally to keep track of the current position in the entry. In + ldap_next_attribute(), the pointer returned by a previous call to + ldap_first_attribute(). The BerElement type itself is an opaque + structure that is described in more detail later in this document + in the section "Encoded ASN.1 Value Manipulation". + + + +Expires: 23 August 1999 [Page 49] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +mem A pointer to memory allocated by the LDAP library, such as the + attribute type names returned by ldap_first_attribute() and + ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem + is NULL, nothing is done. + +ldap_first_attribute() and ldap_next_attribute() will return NULL when +the end of the attributes is reached, or if there is an error, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +Both routines return a pointer to an allocated buffer containing the +current attribute name. This should be freed when no longer in use by +calling ldap_memfree(). + +ldap_first_attribute() will allocate and return in ptr a pointer to a +BerElement used to keep track of the current position. This pointer +should be passed in subsequent calls to ldap_next_attribute() to step +through the entry's attributes. After a set of calls to +ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it +should be freed by calling ber_free( ptr, 0 ). Note that it is very +important to pass the second parameter as 0 (zero) in this call, since +the buffer associated with the BerElement does not point to separately +allocated memory. + +The attribute type names returned are suitable for passing in a call to +ldap_get_values() and friends to retrieve the associated values. + + +15.3. Retrieving the Values of an Attribute + +ldap_get_values() and ldap_get_values_len() are used to retrieve the +values of a given attribute from an entry. ldap_count_values() and +ldap_count_values_len() are used to count the returned values. +ldap_value_free() and ldap_value_free_len() are used to free the values. + + char **ldap_get_values( + LDAP *ld, + LDAPMessage *entry, + const char *attr + ); + + struct berval **ldap_get_values_len( + LDAP *ld, + LDAPMessage *entry, + const char *attr + ); + + int ldap_count_values( char **vals ); + + + +Expires: 23 August 1999 [Page 50] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_count_values_len( struct berval **vals ); + + void ldap_value_free( char **vals ); + + void ldap_value_free_len( struct berval **vals ); + +Parameters are: + +ld The session handle. + +entry The entry from which to retrieve values, as returned by + ldap_first_entry() or ldap_next_entry(). + +attr The attribute whose values are to be retrieved, as returned by + ldap_first_attribute() or ldap_next_attribute(), or a caller- + supplied string (e.g., "mail"). + +vals The values returned by a previous call to ldap_get_values() or + ldap_get_values_len(). + +Two forms of the various calls are provided. The first form is only +suitable for use with non-binary character string data. The second _len +form is used with any kind of data. + +ldap_get_values() and ldap_get_values_len() return NULL if no values are +found for attr or if an error occurs. + +ldap_count_values() and ldap_count_values_len() return -1 if an error +occurs such as the vals parameter being invalid. + +Note that the values returned are dynamically allocated and should be +freed by calling either ldap_value_free() or ldap_value_free_len() when +no longer in use. + + +15.4. Retrieving the name of an entry + +ldap_get_dn() is used to retrieve the name of an entry. +ldap_explode_dn() and ldap_explode_rdn() are used to break up a name +into its component parts. ldap_dn2ufn() is used to convert the name into +a more "user friendly" format. + + char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); + + char **ldap_explode_dn( const char *dn, int notypes ); + + char **ldap_explode_rdn( const char *rdn, int notypes ); + + + + +Expires: 23 August 1999 [Page 51] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + char *ldap_dn2ufn( const char *dn ); + +Parameters are: + +ld The session handle. + +entry The entry whose name is to be retrieved, as returned by + ldap_first_entry() or ldap_next_entry(). + +dn The dn to explode, such as returned by ldap_get_dn(). + +rdn The rdn to explode, such as returned in the components of the + array returned by ldap_explode_dn(). + +notypes A boolean parameter, if non-zero indicating that the dn or rdn + components should have their type information stripped off + (i.e., "cn=Babs" would become "Babs"). + +ldap_get_dn() will return NULL if there is some error parsing the dn, +setting error parameters in the session handle ld to indicate the error. +It returns a pointer to newly allocated space that the caller should +free by calling ldap_memfree() when it is no longer in use. Note the +format of the DNs returned is given by [4]. + +ldap_explode_dn() returns a NULL-terminated char * array containing the +RDN components of the DN supplied, with or without types as indicated by +the notypes parameter. The components are returned in the order they +appear in the dn. The array returned should be freed when it is no +longer in use by calling ldap_value_free(). + +ldap_explode_rdn() returns a NULL-terminated char * array containing the +components of the RDN supplied, with or without types as indicated by +the notypes parameter. The components are returned in the order they +appear in the rdn. The array returned should be freed when it is no +longer in use by calling ldap_value_free(). + +ldap_dn2ufn() converts the DN into the user friendly format described in +[5]. The UFN returned is newly allocated space that should be freed by a +call to ldap_memfree() when no longer in use. + + +15.5. Retrieving controls from an entry + +ldap_get_entry_controls() is used to extract LDAP controls from an +entry. + + + int ldap_get_entry_controls( + + + +Expires: 23 August 1999 [Page 52] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + LDAPMessage *entry, + LDAPControl ***serverctrlsp + ); + +Parameters are: + +ld The session handle. + +entry The entry to extract controls from, as returned by + ldap_first_entry() or ldap_next_entry(). + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of entry. The control array + should be freed by calling ldap_controls_free(). If ser- + verctrlsp is NULL, no controls are returned. + +ldap_get_entry_controls() returns an LDAP error code that indicates +whether the reference could be successfully parsed (LDAP_SUCCESS if all +goes well). + + + +15.6. Parsing References + +ldap_parse_reference() is used to extract referrals and controls from a +SearchResultReference message. + + + int ldap_parse_reference( + LDAP *ld, + LDAPMessage *ref, + char ***referralsp, + LDAPControl ***serverctrlsp, + int freeit + ); + +Parameters are: + +ld The session handle. + +ref The reference to parse, as returned by ldap_result(), + ldap_first_reference(), or ldap_next_reference(). + +referralsp This result parameter will be filled in with an allocated + array of character strings. The elements of the array are + the referrals (typically LDAP URLs) contained in ref. The + array should be freed when no longer in used by calling + + + +Expires: 23 August 1999 [Page 53] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + ldap_value_free(). If referralsp is NULL, the referral + URLs are not returned. + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of ref. The control array + should be freed by calling ldap_controls_free(). If ser- + verctrlsp is NULL, no controls are returned. + +freeit A boolean that determines whether the ref parameter is + disposed of or not. Pass any non-zero value to have this + routine free ref after extracting the requested informa- + tion. This is provided as a convenience; you can also use + ldap_msgfree() to free the result later. + +ldap_parse_reference() returns an LDAP error code that indicates whether +the reference could be successfully parsed (LDAP_SUCCESS if all goes +well). + + +16. Encoded ASN.1 Value Manipulation + +This section describes routines which may be used to encode and decode +BER-encoded ASN.1 values, which are often used inside of control and +extension values. + +With the exceptions of two new functions ber_flatten() and ber_init(), +these functions are compatible with the University of Michigan LDAP 3.3 +implementation of BER. + + +16.1. General + + struct berval { + unsigned long bv_len; + char *bv_val; + }; + +A struct berval contains a sequence of bytes and an indication of its +length. The bv_val is not necessarily zero-terminated. bv_len must +always be a nonnegative number. Applications may allocate their own +berval structures. + +As defined earlier, the BerElement structure is an opaque structure: + + typedef struct berelement BerElement; + +It contains not only a copy of the encoded value, but also state infor- +mation used in encoding or decoding. Applications cannot allocate their + + + +Expires: 23 August 1999 [Page 54] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +own BerElement structures. The internal state is neither thread- +specific nor locked, so two threads should not manipulate the same +BerElement value simultaneously. + +A single BerElement value cannot be used for both encoding and decoding. + + void ber_bvfree( struct berval *bv ); + +ber_bvfree() frees a berval returned from this API. Both the bv->bv_val +string and the berval itself are freed. Applications should not use +ber_bvfree() with bervals which the application has allocated. + + void ber_bvecfree( struct berval **bv ); + +ber_bvecfree() frees an array of bervals returned from this API. Each +of the bervals in the array are freed using ber_bvfree(), then the array +itself is freed. + + struct berval *ber_bvdup( const struct berval *bv ); + +ber_bvdup() returns a copy of a berval. The bv_val field in the +returned berval points to a different area of memory than the bv_val +field in the argument berval. The NULL pointer is returned on error +(e.g. out of memory). + + void ber_free( BerElement *ber, int fbuf ); + +ber_free() frees a BerElement which is returned from the API calls +ber_alloc_t() or ber_init(). Each BerElement must be freed by the +caller. The second argument fbuf should always be set to 1 to ensure +that the internal buffer used by the BER functions is freed as well as +the BerElement container itself. + + +16.2. Encoding + + BerElement *ber_alloc_t( int options ); + +ber_alloc_t() constructs and returns BerElement. The NULL pointer is +returned on error. The options field contains a bitwise-or of options +which are to be used when generating the encoding of this BerElement. +One option is defined and must always be supplied: + + #define LBER_USE_DER 0x01 + +When this option is present, lengths will always be encoded in the +minimum number of octets. Note that this option does not cause values +of sets to be rearranged in tag and byte order or default values to be + + + +Expires: 23 August 1999 [Page 55] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +removed, so these functions are not sufficient for generating DER output +as defined in X.509 and X.680. If the caller takes responsibility for +ordering values of sets correctly and removing default values, DER out- +put as defined in X.509 and X.680 can be produced. + +Unrecognized option bits are ignored. + +The BerElement returned by ber_alloc_t() is initially empty. Calls to +ber_printf() will append bytes to the end of the ber_alloc_t(). + + int ber_printf( BerElement *ber, const char *fmt, ... ) + +The ber_printf() routine is used to encode a BER element in much the +same way that sprintf() works. One important difference, though, is +that state information is kept in the ber argument so that multiple +calls can be made to ber_printf() to append to the end of the BER ele- +ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). +ber_printf() interprets and formats its arguments according to the for- +mat string fmt. ber_printf() returns -1 if there is an error during +encoding and a positive number if successful. As with sprintf(), each +character in fmt refers to an argument to ber_printf(). + +The format string can contain the following format characters: + +'t' Tag. The next argument is an int specifying the tag to override + the next element to be written to the ber. This works across + calls. The int value must contain the tag class, constructed + bit, and tag value. For example, a tag of "[3]" for a con- + structed type is 0xA3. All implementations must support tags + that fit in a single octet (i.e., where the tag value is less + than 32) and they may support larger tags. + +'b' Boolean. The next argument is an int, containing either 0 for + FALSE or 0xff for TRUE. A boolean element is output. If this + format character is not preceded by the 't' format modifier, the + tag 0x01 is used for the element. + +'i' Integer. The next argument is an int, containing the integer in + the host's byte order. An integer element is output. If this + format character is not preceded by the 't' format modifier, the + tag 0x02 is used for the element. + +'X' Bitstring. The next two arguments are a char * pointer to the + start of the bitstring, followed by an int containing the number + of bits in the bitstring. A bitstring element is output, in + primitive form. If this format character is not preceded by the + 't' format modifier, the tag 0x03 is used for the element. + + + + +Expires: 23 August 1999 [Page 56] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +'n' Null. No argument is required. An ASN.1 NULL element is out- + put. If this format character is not preceded by the 't' format + modifier, the tag 0x05 is used for the element. + +'o' Octet string. The next two arguments are a char *, followed by + an int with the length of the string. The string may contain + null bytes and need not be zero-terminated. An octet string + element is output, in primitive form. If this format character + is not preceded by the 't' format modifier, the tag 0x04 is used + for the element. + +'s' Octet string. The next argument is a char * pointing to a + zero-terminated string. An octet string element in primitive + form is output, which does not include the trailing '\0' (null) + byte. If this format character is not preceded by the 't' format + modifier, the tag 0x04 is used for the element. + +'v' Several octet strings. The next argument is a char **, an array + of char * pointers to zero-terminated strings. The last element + in the array must be a NULL pointer. The octet strings do not + include the trailing '\0' (null) byte. Note that a construct + like '{v}' is required to get an actual SEQUENCE OF octet + strings. The 't' format modifier cannot be used with this for- + mat character. + +'V' Several octet strings. A NULL-terminated array of berval *'s is + supplied. Note that a construct like '{V}' is required to get an + actual SEQUENCE OF octet strings. The 't' format modifier cannot + be used with this format character. + +'{' Begin sequence. No argument is required. If this format char- + acter is not preceded by the 't' format modifier, the tag 0x30 + is used. + +'}' End sequence. No argument is required. The 't' format modifier + cannot be used with this format character. + +'[' Begin set. No argument is required. If this format character + is not preceded by the 't' format modifier, the tag 0x31 is + used. + +']' End set. No argument is required. The 't' format modifier can- + not be used with this format character. + +Each use of a '{' format character must be matched by a '}' character, +either later in the format string, or in the format string of a subse- +quent call to ber_printf() for that BerElement. The same applies to the +'[' and ']' format characters. + + + +Expires: 23 August 1999 [Page 57] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Sequences and sets nest, and implementations of this API must maintain +internal state to be able to properly calculate the lengths. + + int ber_flatten( const BerElement *ber, struct berval **bvPtr ); + +The ber_flatten routine allocates a struct berval whose contents are a +BER encoding taken from the ber argument. The bvPtr pointer points to +the returned berval, which must be freed using ber_bvfree(). This rou- +tine returns 0 on success and -1 on error. + +The ber_flatten API call is not present in U-M LDAP 3.3. + +The use of ber_flatten on a BerElement in which all '{' and '}' format +modifiers have not been properly matched is an error (i.e., -1 will be +returned by ber_flatten() if this situation is exists). + + +16.3. Encoding Example + +The following is an example of encoding the following ASN.1 data type: + + Example1Request ::= SEQUENCE { + s OCTET STRING, -- must be printable + val1 INTEGER, + val2 [0] INTEGER DEFAULT 0 + } + + + int encode_example1(const char *s,int val1,int val2,struct berval **bvPtr) + { + BerElement *ber; + int rc = -1; + + ber = ber_alloc_t(LBER_USE_DER); + + if (ber == NULL) return -1; + + if (ber_printf(ber,"{si",s,val1) == -1) { + goto done; + } + + if (val2 != 0) { + if (ber_printf(ber,"ti",0x80,val2) == -1) { + goto done; + } + } + + if (ber_printf(ber,"}") == -1) { + + + +Expires: 23 August 1999 [Page 58] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + goto done; + } + + rc = ber_flatten(ber,bvPtr); + + done: + ber_free(ber,1); + return rc; + } + + +16.4. Decoding + +The following two symbols are available to applications. + + #define LBER_ERROR 0xffffffffUL + #define LBER_DEFAULT 0xffffffffUL + + BerElement *ber_init( const struct berval *bv ); + +The ber_init function constructs a BerElement and returns a new BerEle- +ment containing a copy of the data in the bv argument. ber_init returns +the NULL pointer on error. + + unsigned long ber_scanf( BerElement *ber, const char *fmt, ... ); + +The ber_scanf() routine is used to decode a BER element in much the same +way that sscanf() works. One important difference, though, is that some +state information is kept with the ber argument so that multiple calls +can be made to ber_scanf() to sequentially read from the BER element. +The ber argument must be a pointer to a BerElement returned by +ber_init(). ber_scanf interprets the bytes according to the format +string fmt, and stores the results in its additional arguments. +ber_scanf() returns LBER_ERROR on error, and a different value on suc- +cess. + +The format string contains conversion specifications which are used to +direct the interpretation of the BER element. The format string can +contain the following characters: + +'a' Octet string. A char ** argument should be supplied. Memory is + allocated, filled with the contents of the octet string, zero- + terminated, and the pointer to the string is stored in the argu- + ment. The returned value must be freed using ldap_memfree. The + tag of the element must indicate the primitive form (constructed + strings are not supported) but is otherwise ignored and dis- + carded during the decoding. This format cannot be used with + octet strings which could contain null bytes. + + + +Expires: 23 August 1999 [Page 59] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +'O' Octet string. A struct berval ** argument should be supplied, + which upon return points to an allocated struct berval contain- + ing the octet string and its length. ber_bvfree() must be + called to free the allocated memory. The tag of the element + must indicate the primitive form (constructed strings are not + supported) but is otherwise ignored during the decoding. + +'b' Boolean. A pointer to an int should be supplied. The int value + stored will be 0 for FALSE or nonzero for TRUE. The tag of the + element must indicate the primitive form but is otherwise + ignored during the decoding. + +'i' Integer. A pointer to an int should be supplied. The int value + stored will be in host byte order. The tag of the element must + indicate the primitive form but is otherwise ignored during the + decoding. ber_scanf() will return an error if the integer can- + not be stored in an int. + +'B' Bitstring. A char ** argument should be supplied which will + point to the allocated bits, followed by an unsigned long * + argument, which will point to the length (in bits) of the bit- + string returned. ldap_memfree must be called to free the bit- + string. The tag of the element must indicate the primitive form + (constructed bitstrings are not supported) but is otherwise + ignored during the decoding. + +'n' Null. No argument is required. The element is verified to have + a zero-length value and is skipped. The tag is ignored. + +'v' Several octet strings. A char *** argument should be supplied, + which upon return points to an allocated NULL-terminated array + of char *'s containing the octet strings. NULL is stored if the + sequence is empty. ldap_memfree must be called to free each + element of the array and the array itself. The tag of the + sequence and of the octet strings are ignored. + +'V' Several octet strings (which could contain null bytes). A + struct berval *** should be supplied, which upon return points + to a allocated NULL-terminated array of struct berval *'s con- + taining the octet strings and their lengths. NULL is stored if + the sequence is empty. ber_bvecfree() can be called to free the + allocated memory. The tag of the sequence and of the octet + strings are ignored. + +'x' Skip element. The next element is skipped. No argument is + required. + +'{' Begin sequence. No argument is required. The initial sequence + + + +Expires: 23 August 1999 [Page 60] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + tag and length are skipped. + +'}' End sequence. No argument is required. + +'[' Begin set. No argument is required. The initial set tag and + length are skipped. + +']' End set. No argument is required. + + unsigned long ber_peek_tag( BerElement *ber, unsigned long *lenPtr ); + +ber_peek_tag() returns the tag of the next element to be parsed in the +BerElement argument. The length of this element is stored in the +*lenPtr argument. LBER_DEFAULT is returned if there is no further data +to be read. The ber argument is not modified. + + unsigned long ber_skip_tag( BerElement *ber, unsigned long *lenPtr ); + +ber_skip_tag() is similar to ber_peek_tag(), except that the state +pointer in the BerElement argument is advanced past the first tag and +length, and is pointed to the value part of the next element. This rou- +tine should only be used with constructed types and situations when a +BER encoding is used as the value of an OCTET STRING. The length of the +value is stored in *lenPtr. + + unsigned long ber_first_element( BerElement *ber, + unsigned long *lenPtr, char **opaquePtr ); + + unsigned long ber_next_element( BerElement *ber, + unsigned long *lenPtr, char *opaque ); + +ber_first_element() and ber_next_element() are used to traverse a SET, +SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls +ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, +and calls ber_peek_tag() for the first element inside the constructed +value. LBER_DEFAULT is returned if the constructed value is empty. +ber_next_element() positions the state at the start of the next element +in the constructed type. LBER_DEFAULT is returned if there are no +further values. + +The len and opaque values should not be used by applications other than +as arguments to ber_next_element(), as shown in the example below. + + +16.5. Decoding Example + +The following is an example of decoding an ASN.1 data type: + + + + +Expires: 23 August 1999 [Page 61] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Example2Request ::= SEQUENCE { + dn OCTET STRING, -- must be printable + scope ENUMERATED { b (0), s (1), w (2) }, + ali ENUMERATED { n (0), s (1), f (2), a (3) }, + size INTEGER, + time INTEGER, + tonly BOOLEAN, + attrs SEQUENCE OF OCTET STRING, -- must be printable + [0] SEQUENCE OF SEQUENCE { + type OCTET STRING -- must be printable, + crit BOOLEAN DEFAULT FALSE, + value OCTET STRING + } OPTIONAL } + + #define TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ + + int decode_example2(struct berval *bv) + { + BerElement *ber; + unsigned long len, res; + int scope, ali, size, time, tonly; + char *dn = NULL, **attrs = NULL; + int i,rc = 0; + + ber = ber_init(bv); + if (ber == NULL) { + fputs("ERROR ber_init failed\n", stderr); + return -1; + } + + res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali, + &size,&time,&tonly,&attrs); + + if (res == LBER_ERROR) { + fputs("ERROR ber_scanf failed\n", stderr); + ber_free(ber,1); + return -1; + } + + /* *** use dn */ + ldap_memfree(dn); + + for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { + /* *** use attrs[i] */ + ldap_memfree(attrs[i]); + } + ldap_memfree(attrs); + + + + +Expires: 23 August 1999 [Page 62] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) { + char *opaque; + unsigned long tag; + + for (tag = ber_first_element(ber,&len,&opaque); + tag != LBER_DEFAULT; + tag = ber_next_element (ber,&len,opaque)) { + + unsigned long ttag, tlen; + char *type; + int crit; + struct berval *value; + + if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { + fputs("ERROR cannot parse type\n", stderr); + break; + } + /* *** use type */ + ldap_memfree(type); + + ttag = ber_peek_tag(ber,&tlen); + if (ttag == 0x01) { /* boolean */ + if (ber_scanf(ber,"b", + &crit) == LBER_ERROR) { + fputs("ERROR cannot parse crit\n", + stderr); + rc = -1; + break; + } + } else if (ttag == 0x04) { /* octet string */ + crit = 0; + } else { + fputs("ERROR extra field in controls\n", + stderr ); + break; + } + + if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { + fputs("ERROR cannot parse value\n", stderr); + rc = -1; + break; + } + /* *** use value */ + ber_bvfree(value); + } + } + + ber_scanf(ber,"}"); + + + +Expires: 23 August 1999 [Page 63] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + + ber_free(ber,1); + + return rc; + } + + + +17. Security Considerations + +LDAPv2 supports security through protocol-level authentication using +clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- +tication Security Layer) methods. LDAPv3 also supports operation over a +secure transport layer using Transport Layer Security TLS [9]. Readers +are referred to the protocol documents for discussion of related secu- +rity considerations. + +Implementations of this API should be cautious when handling authentica- +tion credentials. In particular, keeping long-lived copies of creden- +tials without the application's knowledge is discouraged. + + +18. Acknowledgements + +Many members of the IETF ASID and LDAPEXT working groups as well as +members of the Internet at large have provided useful comments and +suggestions that have been incorporated into this document. Chris +Weider deserves special mention for his contributions as co-author of +earlier revisions of this document. + +The original material upon which this specification is based was sup- +ported by the National Science Foundation under Grant No. NCR-9416667. + + +19. Copyright + +Copyright (C) The Internet Society (1997-1999). All Rights Reserved. + +This document and translations of it may be copied and furnished to oth- +ers, and derivative works that comment on or otherwise explain it or +assist in its implementation may be prepared, copied, published and dis- +tributed, in whole or in part, without restriction of any kind, provided +that the above copyright notice and this paragraph are included on all +such copies and derivative works. However, this document itself may not +be modified in any way, such as by removing the copyright notice or +references to the Internet Society or other Internet organizations, +except as needed for the purpose of developing Internet standards in +which case the procedures for copyrights defined in the Internet + + + +Expires: 23 August 1999 [Page 64] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Standards process must be followed, or as required to translate it into +languages other than English. + +The limited permissions granted above are perpetual and will not be +revoked by the Internet Society or its successors or assigns. + +This document and the information contained herein is provided on an "AS +IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK +FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT +LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT +INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- +NESS FOR A PARTICULAR PURPOSE. + + +20. Bibliography + +[1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation + X.520. + +[2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, + "Lightweight Directory Access Protocol (v3): Attribute Syntax + Definitions", RFC 2252, December 1997. + +[3] T. Howes, "The String Representation of LDAP Search Filters," RFC + 2254, December 1997. + +[4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol + (v3): A UTF-8 String Representation of Distinguished Names", RFC + 2253, December 1997. + +[5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- + ing," RFC 1781, March 1995. + +[6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol + (v3)", RFC 2251, December 1997. + +[7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control + Extension for Server Side Sorting of Search Results", INTERNET- + DRAFT , 7 August 1998. + +[8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC + 2222, October 1997. + +[9] "Lightweight Directory Access Protocol (v3): Extension for Tran- + sport Layer Security", INTERNET-DRAFT , November 1998. + +[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC + + + +Expires: 23 August 1999 [Page 65] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + 2044, October 1996. + +[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. + +[12] "Character Mnemonics and Character Sets," RFC 1345, June 1992. + +[13] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997. + + +21. Authors' Addresses + + Mark Smith (document editor) + Netscape Communications Corp. + 501 E. Middlefield Rd., Mailstop MV068 + Mountain View, CA 94043 + USA + +1 650 937-3477 + mcs@netscape.com + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd., Mailstop MV068 + Mountain View, CA 94043 + USA + +1 650 937-3419 + howes@netscape.com + + Andy Herron + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + +1 425 882-8080 + andyhe@microsoft.com + + Mark Wahl + Innosoft International, Inc. + 8911 Capital of Texas Hwy, Suite 4140 + Austin, TX 78759 + USA + +1 626 919 3600 + Mark.Wahl@innosoft.com + + Anoop Anantha + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + + + +Expires: 23 August 1999 [Page 66] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + +1 425 882-8080 + anoopa@microsoft.com + + +22. Appendix A - Sample C LDAP API Code + + #include + #include + + main() + { + LDAP *ld; + LDAPMessage *res, *e; + int i, rc; + char *a, *dn; + BerElement *ptr; + char **vals; + + /* open an LDAP session */ + if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) + return 1; + + /* authenticate as nobody */ + if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { + fprintf( stderr, "ldap_simple_bind_s: %s\n", + ldap_err2string( rc )); + ldap_unbind( ld ); + return 1; + } + + /* search for entries with cn of "Babs Jensen", return all attrs */ + if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", + LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) + != LDAP_SUCCESS ) { + fprintf( stderr, "ldap_search_s: %s\n", + ldap_err2string( rc )); + if ( res == NULL ) { + ldap_unbind( ld ); + return 1; + } + } + + /* step through each entry returned */ + for ( e = ldap_first_entry( ld, res ); e != NULL; + e = ldap_next_entry( ld, e ) ) { + /* print its name */ + dn = ldap_get_dn( ld, e ); + printf( "dn: %s\n", dn ); + + + +Expires: 23 August 1999 [Page 67] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + ldap_memfree( dn ); + + /* print each attribute */ + for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; + a = ldap_next_attribute( ld, e, ptr ) ) { + printf( "\tattribute: %s\n", a ); + + /* print each value */ + vals = ldap_get_values( ld, e, a ); + for ( i = 0; vals[i] != NULL; i++ ) { + printf( "\t\tvalue: %s\n", vals[i] ); + } + ldap_value_free( vals ); + ldap_memfree( a ); + } + if ( ptr != NULL ) { + ber_free( ptr, 0 ); + } + } + /* free the search results */ + ldap_msgfree( res ); + + /* close and free connection resources */ + ldap_unbind( ld ); + + return 0; + } + + +23. Appendix B - Namespace Consumed By This Specification + +The following 2 prefixes are used in this specification to name func- +tions: + ldap_ + ber_ + +The following 6 prefixes are used in this specification to name struc- +tures, unions, and typedefs: + ldap + LDAP + PLDAP + ber + Ber + timeval + +The following 3 prefixes are used in this specification to name #defined +macros: + LDAP + + + +Expires: 23 August 1999 [Page 68] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LBER_ + mod_ + + +24. Appendix C - Summary of Requirements for API Extensions + +As the LDAP protocol is extended, this C LDAP API will need to be +extended as well. For example, an LDAPv3 control extension has already +been defined for server-side sorting of search results [7]. This appen- +dix summarizes the requirements for extending this API. + +24.1. Compatibility + +Extensions to this document should not, by default, alter the behavior +of any of the APIs specified in this document. If an extension option- +ally changes the behavior of any existing C LDAP API function calls, the +behavior change must be well documented. + +24.2. Style + +Extensions to this API should follow the general style and naming con- +ventions used in this document. For example, function names should +start with "ldap_" or "ber_" and consist entirely of lowercase letters, +digits, and underscore ('_') characters. More information can be found +in the preceding appendix called "Namespace Consumed By This Specifica- +tion." + +24.3. Dependence on Externally Defined Types + +Extensions to this API should minimize dependencies on types and macros +that are defined in system header files and generally use only intrinsic +types that are part of the C language, types defined in this specifica- +tion, or types defined in the extension document itself. + +24.4. Compile Time Information + +Extensions to this API should conform to the requirements contained in +the "Retrieving Information at Compile Time" section of this document. +That is, extensions should define a macro of the form: + + #define LDAP_API_FEATURE_x level + +so that applications can detect the presence or absense of the extension +at compile time and also test the version or level of the extension pro- +vided by an API implementation. + + + + + + +Expires: 23 August 1999 [Page 69] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +24.5. Runtime Information + +Extensions to this API should conform to the requirements contained in +the "Retrieving Information During Execution" section of this document. +That is, each extension should be given a character string name and that +name should appear in the ldapai_extensions array field of the LDAPAPI- +Info structure following a successful call to ldap_get_option() with an +option parameter value of LDAP_OPT_API_INFO. In addition, information +about the extension should be available via a call to ldap_get_option() +with an option parameter value of LDAP_OPT_API_FEATURE_INFO. + +24.6. Values Used for Session Handle Options + +Extensions to this API that add new session options (for use with the +ldap_get_option() and ldap_set_option() functions) should meet the +requirements contained in the last paragraph of the "LDAP Session Handle +Options" section of this document. Specifically, standards track docu- +ments MUST use values for option macros that are between 0x1000 and +0x3FFF inclusive and private and experimental extensions MUST use values +for the option macros that are between 0x4000 and 0x7FFF inclusive. + + +25. Appendix D - Known Incompatibilities with RFC 1823 + +This appendix lists known incompatibilities between this API specifica- +tion and the one contained in RFC 1823, beyond the additional API func- +tions added in support of LDAPv3. + + +25.1. Opaque LDAP Structure + +In RFC 1823, some fields in the LDAP structure were exposed to applica- +tion programmers. To provide a cleaner interface and to make it easier +for implementations to evolve over time without sacrificing binary com- +patibility with older applications, the LDAP structure is now entirely +opaque. The new ldap_set_option() and ldap_get_option() calls can be +used to manipulate per-session and global options. + + +25.2. Additional Error Codes + +The following new error code macros were introduced to support LDAPv3: + LDAP_REFERRAL + LDAP_ADMINLIMIT_EXCEEDED + LDAP_UNAVAILABLE_CRITICAL_EXTENSION + LDAP_CONFIDENTIALITY_REQUIRED + LDAP_SASL_BIND_IN_PROGRESS + LDAP_AFFECTS_MULTIPLE_DSAS + + + +Expires: 23 August 1999 [Page 70] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_CONNECT_ERROR + LDAP_NOT_SUPPORTED + LDAP_CONTROL_NOT_FOUND + LDAP_NO_RESULTS_RETURNED + LDAP_MORE_RESULTS_TO_RETURN + LDAP_CLIENT_LOOP + LDAP_REFERRAL_LIMIT_EXCEEDED + + +25.3. Freeing of String Data with ldap_memfree() + +All strings received from the API (e.g., those returned by the +ldap_get_dn() or ldap_dn2ufn() functions) should be freed by calling +ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree() +function. + + +25.4. Changes to ldap_result() + +The meaning of the all parameter to ldap_result has changed slightly. +Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There +is also a new possible value, LDAP_MSG_RECEIVED (0x02). + +The result type LDAP_RES_MODDN is now returned where RFC 1823 returned +LDAP_RES_MODRDN. The actual value for these two macros is the same +(0x6D). + + +25.5. Changes to ldap_first_attribute() and ldap_next_attribute + +Each non-NULL return value should be freed by calling ldap_memfree() +after use. In RFC 1823, these two functions returned a pointer to a +per-session buffer, which was not very thread-friendly. + +After the last call to ldap_first_attribute() or ldap_next_attribute(), +the value set in the ptr parameter should be freed by calling ber_free( +ptr, 0 ). RFC 1823 did not mention that the ptr value should be freed. + +The type of the ptr parameter was changed from void * to BerElement *. + + +25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions + +In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a +parameter called deleteoldrdn. This does not match the great majority +of implementations, so in this specification the deleteoldrdn parameter +was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional +functions that support deleteoldrdn and are widely implemented as well + + + +Expires: 23 August 1999 [Page 71] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +were added to this specification: ldap_modrdn2() and ldap_modrdn2_s(). + + +25.7. API Specification Clarified + +RFC 1823 left many things unspecified, including behavior of various +memory disposal functions when a NULL pointer is presented, requirements +for header files, values of many macros, and so on. This specification +is more complete and generally tighter than the one in RFC 1823. + + +25.8. Deprecated Functions + +A number of functions that are in RFC 1823 are labeled as "deprecated" +in this specification. In most cases, a replacement that provides +equivalent functionality has been defined. The deprecated functions +are: + + ldap_bind() + Use ldap_simple_bind() or ldap_sasl_bind() instead. + + ldap_bind_s() + Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead. + + ldap_kerberos_bind() and ldap_kerberos_bind_s() + No equivalent functions are provided. + + ldap_modrdn() and ldap_modrdn2() + Use ldap_rename() instead. + + ldap_modrdn_s() and ldap_modrdn2_s() + Use ldap_rename_s() instead. + + ldap_open() + Use ldap_init() instead. + + ldap_perror() + Use ldap_err2string() instead. + + ldap_result2error() + Use ldap_parse_result() instead. + + +26. Appendix E - Changes Made Since Last Document Revision + +The previous version of this document was draft-ietf-ldapext-ldap-c- +api-01.txt, dated 7 August 1998. This appendix lists all of the changes +made to that document to produce the one you are reading now. + + + +Expires: 23 August 1999 [Page 72] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +26.1. API Changes + + General: added the 'const' keyword to function prototypes where + appropriate. + + Added two new sections that specify additional features and require- + ments for API implementors: + "Header File Requirements" + "A Client Control That Governs Referral Processing" + + "Retrieving Information at Compile Time" section: added + LDAP_VERSION_MIN, LDAP_VERSION_MAX, LDAP_VENDOR_NAME, and + LDAP_VENDOR_VERSION macros. Corrected LDAP_API_VERSION example code + to use >= instead of >. Added note about what value to use for + LDAP_API_VERSION prior to publication of this draft as an RFC (2000 + + draft revision number). + + "Retrieving Information During Execution" section: added + LDAP_API_INFO_VERSION macro and clarified the text to explain the + behavior when there is a mismatch between LDAPAPIInfo structure ver- + sions. Added LDAP_OPT_API_FEATURE_INFO to allow applications to + retrieve version information about API extended features. + + "LDAP Session Handle Options" section: Added macro definitions for + LDAP_OPT_ON and LDAP_OPT_OFF and changed the "invalue" type for + Boolean options from "int" to "void *". For consistency, we now + require that applications dispose of "char *" and "LDAPControl *" + values that are returned. Added note about which option value ranges + are to be used for various purposes. + + "Closing the session" section: added new function ldap_unbind_ext() + to allow controls to be used with unbind operations. + + "Searching" section: added requirement that *res be set to NULL by + synchronous calls that fail to return any results. + + "Modifying the Name of an Entry" section: added function prototypes + for ldap_modrdn2() and ldap_modrdn2_s() and corrected the ones for + ldap_modrdn() and ldap_modrdn_s() to match the most widely imple- + mented APIs. + + "Obtaining Results and Peeking Inside LDAP Messages" section: added + requirement that "*res" be set to NULL when ldap_result() fails to + return any results. Added requirement that ldap_msgfree() accept a + NULL "res" parameter. + + "Stepping Through the Attributes of an Entry" section: added + requirement that ldap_memfree() accept a NULL "mem" parameter. + + + +Expires: 23 August 1999 [Page 73] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + "Encoded ASN.1 Value Manipulation - Encoding" section: added note + that implementations may support tags with a value larger than 32 + (but this is not required). + + "Encoded ASN.1 Value Manipulation - Decoding" section: changed the + LBER_ERROR and LBER_DEFAULT macros to end in "UL" instead of "L" + since all the functions that return these two values return an + "unsigned long" value. + + +26.2. Editorial changes + + + Removed section: "Appendix - Outstanding Issues." + + Added two new editorial sections: + "Appendix - Summary of Requirements for API Extensions" + "Appendix - Known Incompatibilities with RFC 1823". + + General: replaced all occurrences of "LDAP C API" with "C LDAP API" + for consistency. + + "Status of Memo" section: added a statement that this document is in + full conformance with all provisions of Section 10 of RFC2026. Also + revised the text about the Internet Draft current and shadow direc- + tories to match the latest I-D guidelines. + + Document authors: removed Chris Weider from the list of authors (at + his own request) and added an explicit mention of him in the "Ack- + nowledgements" section. Updated Mark Wahl's company affiliation in + document preface. Added "(document editor)" after Mark Smith's name + in the "Authors' Addresses" section. + + Copyright: updated the year to 1999. + + "Introduction" section: expanded the sentence that mentioned the sam- + ple code appendix to mention all of the appendices. + + "Overview of LDAP API Use" section: numbered the four simple steps + for using the API. Added mention of the referrals client control. + Clarified the text on character sets. Replaced mention of + ldap_bind() with ldap_sasl_bind() because the former is deprecated. + Added note that this API is designed for use in environments where + the 'int' type is at least 32 bits in size. + + "Common Data Structures" section: added definition of BerElement so + it is defined before it is used. Added reference back to "Header + File Requirements" for "struct timeval" related considerations. + + + +Expires: 23 August 1999 [Page 74] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + "Initializing an LDAP Session" section: moved note about ldap_open() + attempting to make a server connection closer to the ldap_open() + function prototype. Added note that using literal IPv6 addresses in + the "hostname" parameter is not yet supported. + + "LDAP Session Handle Options" section: replaced one instance of + "Formerly" with "In RFC 1823." Added note about inheritance of + options when automatic referral following is enabled. Added + LDAP_OPT_API_INFO and LDAP_OPT_API_FEATURE_INFO for completeness (not + previously included in this section). Replaced erroneous references + to the "Using Controls" section with references to the "Working With + Controls" section. In the text describing the LDAP_OPT_HOST_NAME + option, added a reference to the "hostname" parameter of ldap_init() + for the syntax of the option value. Clarified that ldap_set_option() + makes a copy of the "invalue" data. + + "Working With Controls" section: added a note to remind the reader + that server controls that are marked critical should not be used with + unbind and abandon operations since those two operations have no + server response. + + "Closing the session" section: made it clear that all open connec- + tions associated with a session handle are closed when any of the + unbind API functions are called. + + "Searching" section: added note that only a subset of the filter + functionality is available when communicating with an LDAPv2 server. + Clarified text to explain when a local timeout is used and when it is + not. + + "Abandoning An Operation" section: removed some redundant text from + the paragraph that explains the differences between ldap_abandon() + and ldap_abandon_ext(). + + "Obtaining Results and Peeking Inside LDAP Messages" section: clari- + fied that ldap_result() only returns messages for one request at a + time. + + "Handling Errors and Parsing Results" section: replace a few + occurrences of LDAPResult with LDAPMessage (there is no type called + LDAPResult). Changed the names of the "resultoidp" and "resultdatap" + parameters to "retoidp" and "retdatap" to avoid confusion with LDAP + result messages. + + "Stepping Through a List of Entries or References" section: added "or + References" to the section name to better reflect its contents. + Added missing description of "ref" parameter. Added mention of + ldap_first_reference() and ldap_next_reference() in sentence about + + + +Expires: 23 August 1999 [Page 75] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + function return values. + + "Stepping Through the Attributes of an Entry" section: added forward + reference for BerElement type. + + "Parsing References" section: in the description of the "ref" parame- + ter, changed the phrase "these routines" to the more accurate "this + routine." + + "Encoded ASN.1 Value Manipulation - General" section: changed text to + make sense given that the definition of BerElement now appears first + in the "Common Data Structures" section. + + "Encoded ASN.1 Value Manipulation - Encoding" section: Changed the + style of function prototypes to better match the rest of the docu- + ment. Corrected a typo in the ber_bvdup() description ("as the" + replaced with "than the"). Changed "null" to "NULL" where appropri- + ate to be consistent with use elsewhere in the document. Removed + mention of sequences from the discussion of the LBER_USE_DER option. + Fixed some truncated sentences (by adding some missing '\' characters + to the nroff document source). + + "Encoded ASN.1 Value Manipulation - Encoding Example" section: sim- + plified the error handling in the example code through the use of a + 'goto' statement. + + "Encoded ASN.1 Value Manipulation - Decoding" section: Changed the + style of function prototypes to better match the rest of the docu- + ment. Changed "null" to "NULL" and "null-terminated" to "zero- + terminated" where appropriate to be consistent with use elsewhere in + the document. Fixed a typo (the text now says "an allocated" instead + of "a allocated."). Clarified the description of the 'n' format + character for ber_scanf(). + + "Encoded ASN.1 Value Manipulation - Decoding Example" section: + changed code to not define a macro that begins with "LDAP" since that + prefix is reserved for the API. Removed an extra 'i' from the format + string used in the first call to ber_scanf(). Changed error report- + ing code to send messages to stderr instead of stdout. Changed + declaration of "res" local variable from "int" to "unsigned long" and + corrected one test of the ber_scanf() return value to test against + LBER_ERROR instead of -1. Fixed improperly rendered strings (by + adding '\' characters to the nroff source for this document so that + '\t' and '\n' are correctly rendered). + + "Acknowledgements" section: added the mention of Chris Weider. + Rephrased the text that gives credit to the National Science Founda- + tion (it now says "The original material upon which this + + + +Expires: 23 August 1999 [Page 76] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + specification is based was supported by ..." instead of "This origi- + nal material upon which this revision is based was based upon work + supported by ..." + + In the "Bibliography" section: Added a reference to RFC 1345 and + ANSI/ISO C. Updated the LDAPv3 TLS and Sorting references to point + to the latest revisions of those documents. + + "Appendix - Sample C LDAP API Code": added #include to the + sample code. Changed the code to demonstrate good error handling by + freeing all memory and calling ldap_unbind() before returning. + Replaced calls to exit() with return statements. Fixed improperly + rendered strings (by adding '\' characters to the nroff source for + this document so that '\t' and '\n' are correctly rendered). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Expires: 23 August 1999 [Page 77] +