ClearPath Enterprise Servers

Transcription

1 ClearPath Enterprise Servers Lightweight Directory Access Protocol (LDAP) Programming Guide ClearPath MCP 12.0 April 2008

2 .

3 unisys imagine it. done. ClearPath Enterprise Servers Lightweight Directory Access Protocol (LDAP) Programming Guide ClearPath MCP 12.0 April

4 NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses. Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.

5 ClearPath Enterprise Servers Lightweight Directory Access Protocol (LDAP) Programming Guide ClearPath MCP 12.0 ClearPath Enterprise Servers Lightweight Directory Access Protocol (LDAP) Programming Guide ClearPath MCP Bend here, peel upwards and apply to spine.

6 .

7 Contents Section 1. LDAP and the Unisys LDAP Client Library Documentation Updates About This Guide Overview of LDAP Learning More About LDAP Unisys Implementation of LDAP Library File Name and Location Implementation Scope Using the Unisys LDAP Client Library Library Specifications Include Files for Library Declaration Other Uses for the LDAP Client Library Invoking Multiple LDAP Sessions Section 2. LDAP Entry Points Common Features LDAP Result Code Handling Parameter Usage Entry Points for Algol LDAP_ADD LDAP_ATTR_LIST_ADD_ATTR LDAP_ATTR_LIST_ADD_MODIFICATION LDAP_ATTR_LIST_ADD_V LDAP_ATTR_LIST_INIT LDAP_BIND LDAP_COMPARE LDAP_DELETE LDAP_DESCRIBEERROR LDAP_DISPLAYEERROR LDAP_FIND_SITE LDAP_MODIFY LDAP_MODIFYDN LDAP_REFERENCE LDAP_SEARCH LDAP_SEARCH_ADD_ATTR LDAP_SEARCH_ADD_BOOLEAN LDAP_SEARCH_ADD_FILTER LDAP_SEARCH_CONTINUE LDAP_SEARCH_EXPRESSION LDAP_SEARCH_INIT iii

8 Contents LDAP_SEARCH_RESPONSE LDAP_SERVER_LOOKUP LDAP_SET_DIRENTRY LDAP_SET_NEWNAME LDAP_SETUP_CCS LDAP_TRACE_SETUP LDAP_UNBIND Entry Points for COBOL, C, and Pascal Parameter Transformations List of _C Entry Points LDAP_GETDATA_C Section 3. Result Codes Result Codes Based on Standard LDAP Result Codes That Supplement Standard LDAP Troubleshooting for Failed Kerberos Authentication Section 4. Usage Examples and Sample Code Performing a Search Adding a Directory Entry Modifying a Directory Entry Deleting a Directory Entry Sample Search Query Appendix A. LDAP Constants and Values Index... 1 iv

9 Tables 3 1. Result Codes Based on Standard LDAP Result Codes That Supplement LDAP A 1. LDAP Constants and Values...A v

10 Tables vi

11 Section 1 LDAP and the Unisys LDAP Client Library Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site: Note: If you are not logged into the Product Support site, you will be asked to do so. About This Guide Purpose This programming guide describes the Unisys implementation of the Lightweight Directory Access Protocol (LDAP), including the entry points, constants, fields, and error result codes. Usage examples and sample code are also included. Audience This guide is intended primarily for programmers who are developing directory-enabled applications for a Unisys ClearPath MCP (Master Control Program) environment. Additionally, network administrators and system operators may also be interested in sections of this guide. Overview of LDAP The Lightweight Directory Access Protocol (LDAP) is a protocol for accessing and modifying directory information across a network. It is a simplification of, and to some extent a modification of, the X.500 directory access protocols. Within the LDAP protocol there are clients and servers. LDAP enables clients to access directories stored on servers and to modify directory entries as needed. The server side of LDAP is supported by many current directory products, including Microsoft Active Directory and directory products from Novell and Netscape

12 LDAP and the Unisys LDAP Client Library LDAP has three authentication models: anonymous authentication, clear text password authentication, and SASL authentication. One variant of SASL authentication is Kerberos V5 authentication encapsulated in GSS. (Microsoft Active Directory supports this variant of SASL authentication.) The ClearPath MCP implementation of LDAP supports all three authentication models, using GSS encapsulated Kerberos for SASL authentication. Within a directory to be accessed via LDAP, the entries are stored in a tree of named nodes. Each entry has a set of attributes, and each attribute has a set of values. Each directory that is accessed by LDAP has a schema, reflecting the structure of the directory. It specifies the structure of the directory tree, valid attributes, attribute types, and other information. Learning More About LDAP Books that provide detailed information about implementing LDAP and programming directory-enabled applications are available at bookstores and on booksellers web sites. Additionally, groups such as the IETF (Internet Engineering Task Force) and the Internet FAQs Consortium post RFCs (Requests for Comments) that describe various protocols and features of LDAP. To locate the RFC postings, use an internet search engine and enter RFC nnnn as the search key, where nnnn is the ID number assigned to that RFC. The following RFCs define LDAP and also include references to X.500: RFC 2251: Lightweight Directory Access Protocol (v3) RFC 2252: Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions RFC 2253: Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names Additional RFCs on directory services and security issues include the following: RFC 2254: A String Representation of LDAP Search Filters RCF 2255: The LDAP URL Format RFC 2222: Simple Authentication and Security Layer (SASL) RFC 2044: UTF-8, a transformation of Unicode and ISO RFC 1510: The Kerberos Network Authentication Service (V5) RFC 2743: The Generic Security Service Application Program Interface Version 2, Update

13 LDAP and the Unisys LDAP Client Library Unisys Implementation of LDAP The LDAP implementation on Unisys ClearPath servers is an LDAP client. Users of this LDAP client must know the schema of the LDAP server they want to access or at least the part of the directory they want to use or they must discover it dynamically by doing searches with search filter of objectclass=subschema. For details, see section 3.2 of RFC Notes: While this programming guide mentions certain LDAP semantics and provides a convenient reference to LDAP usage for Unisys ClearPath servers, the authoritative references for LDAP semantics are the LDAP RFCs previously listed, along with X.500 documents that are referenced within the LDAP RFCs. This programming guide does not always use exact LDAP RFC wording. For example, this guide uses the term attribute name in place of the LDAP term attribute description string. Library File Name and Location The LDAP client is implemented on Unisys ClearPath servers as an MCP environment library called LDAPSUPPORT. This library allows MCP environment programs to access and modify directory information stored in Active Directory and other directories that support LDAP. The physical location of the library code file, titled *SYSTEM/LDAPSUPPORT, is determined during installation. The installation also issues the SL command against the library to associate the function name and activate the library. To use the LDAPSUPPORT library, it is recommended to declare the library in your program by function rather than by name. For example: LIBRARY LDAPSUPPORT(LIBACCESS = BYFUNCTION, FUNCTIONNAME = LDAPSUPPORT. ); Implementation Scope The LDAP client implemented on Unisys ClearPath servers is limited to RFC 2251 and RFC Note the following points: Attribute value fields are simply passed to LDAPSUPPORT and returned by LDAPSUPPORT. LDAPSUPPORT can be used to access the attribute value fields of schema entries, but parsing and interpreting them in accordance with RFC 2252 is left as an exercise for the invoker of LDAPSUPPORT. Distinguished Names are currently simply translated to and from UTF-8. If they contain RFC 2253 escape sequences, the invoker of LDAPSUPPORT must handle them. For example, if a relative Distinguished Name contains a comma, RFC 2253 specifies that it should be represented escaped with a backslash character. This allows commas in relative Distinguished Names to be distinguished from the commas used to separate relative Distinguished Names within Distinguished

14 LDAP and the Unisys LDAP Client Library Names. If LDAPSUPPORT were to remove the RFC 2253 backslashes from Distinguished Names, the invoker of LDAPSUPPORT would not be able to parse the resulting Distinguished Names. Because of authentication issues, there are currently no entry points that accept RFC 2255 URLs. RFC 2255 is not specific enough in defining the credentials to be used when establishing an LDAP session in order to process an RFC 2255 URL. References returned on search operations are simply made available to the invoker of LDAPSUPPORT. Such references are returned by LDAP servers as RFC 2255 format URLs. Using the Unisys LDAP Client Library Library Specifications The Unisys client library was designed according to the following specifications: LDAPSUPPORT is a private server library. It requires no special privileges. LDAPSUPPORT uses SOCKETSUPPORT to send and receive UDP datagrams. It uses a PORT FILE to read and write TCP/IP data. LDAPSUPPORT links to RESOLVERSUPPORT for DNS service name lookup. LDAPSUPPORT links to GSSAPISUPPORT to obtain GSS encapsulated Kerberos credentials for SASL authentication. SASL authentication requires use of GSSAPI Wrap and Unwrap. This in turn requires presence of the KRD run-time key. The ability to translation to and from UTF-8 and local EBCDIC is included, based on the UCS to and from EBCDIC translations available from CENTRALSUPPORT. A library entry point named LDAP_SETUP_CCS allows specification of the localization, with the default being inferred from SYSOPS HostCCS. Include Files for Library Declaration For ALGOL Programs The file *SYMBOL/LDAP/INCLUDE/ALGOL contains declarations for The LDAPSUPPORT environment library All the entry points documented in Section 2 of this guide All the constants and fields referenced in the entry points and listed in Appendix A of this guide In addition, this include file contains a cover define or procedure for each procedure which has pointer-length parameter pairs. Each pointer-length parameter pair is replaced by a single string parameter, and the procedure name is suffixed with _S. Note that most of the string parameters are used more than once. String expressions with side effects should not be used

15 LDAP and the Unisys LDAP Client Library The cover defines and procedures are as follows: LDAP_SET_DIRENTRY_S(ENTRYTXT) LDAP_SET_NEWNAME_S(NAMETXT,SUPERIOR) LDAP_SEARCH_ADD_ATTR_S(ATTRTXT) LDAP_SEARCH_ADD_FILTER_S(TYPE,ATTRTXT,VALUETXT) LDAP_ATTR_LIST_ADD_V_S(VTXT) LDAP_ATTR_LIST_ADD_ATTR_S(ATTRTXT) LDAP_ATTR_LIST_ADD_MODIFICATION_S(OP,ATTRTXT) LDAP_BIND_S(HOSTTYPE, HOSTTXT, AUTHENTICATIONTYPE, NAMETXT, PASSWORDTXT, ERRTEXT,ERRTEXTCHRS) For C Programs The files *SYMBOL/CC/LIBRARY/LDAP/H and *SYMBOL/CC/LIBRARY/ LDAP.H contain C syntax declarations for The LDAPSUPPORT environment library All the _C cover functions documented in Section 2 of this guide All the constants and fields referenced in the entry points and listed in Appendix A of this guide. For COBOL Programs The file *SYMBOL/LDAP/INCLUDE/COBOL85 contains declarations for The LDAPSUPPORT environment library All the entry points documented in Section 2 of this guide All the constants and fields referenced in the entry points and listed in Appendix A of this guide Other Uses for the LDAP Client Library The LDAPSUPPORT library can also be used by other MCP system utilities. One such utility is available through a MARC screen called ADJOIN. This screen enables an MCP system administrator to configure the MCP system to trust a Microsoft Active Directory domain for purposes of authentication. This MARC screen calls the KERBEROSSUPPORT library, which in turn invokes certain procedures in LDAPSUPPORT to look up and update domain information. Refer to the ClearPath Kerberos Security Configuration and Administration Guide for more details about the ADJOIN screen

16 LDAP and the Unisys LDAP Client Library Invoking Multiple LDAP Sessions A sequence of LDAP sessions can be established using a single LDAPSUPPORT library declaration by invoking LDAP_UNBIND and then LDAP_BIND to switch sessions. To obtain simultaneous LDAP sessions, use multiple declarations of LDAPSUPPORT. One way to do this is to declare LDAPSUPPORT within a connection block. Note: Because the need for multiple simultaneous LDAP sessions might be limited, no further information is provided in this guide

17 Section 2 LDAP Entry Points This section documents the entry points into the LDAPSUPPORT library. Common Features LDAP Result Code Handling Standard LDAP defines a set of enumerated result codes that indicate the status of a protocol operation request. The LDAPSUPPORT library interprets the LDAP result code for use by your application. Many procedures in the LDAPSUPPORT library return an INTEGER result and have parameters ERRTEXT and ERRTEXTCHRS. These are the parameters that return the result of the operation. The values in ERRTEXT and ERRTEXTCHRS may then be passed to the library procedures titled LDAP_DESCRIBEERROR and LDAP_DISPLAYERROR, which generate text error messages and are documented under Entry Points in this section. The INTEGER result is partitioned into two fields as follows: LDAP_COMMANDF = [31:16] LDAP_ERRORF = [15:16] LDAP_COMMANDF will contain either zero when the command was successful or a command enumeration when it was not. This field is intended for use by LDAP_DESCRIBEERROR and LDAP_DISPLAYERROR, which use it to include text identifying the command that incurred the error. LDAP_ERRORF will contain either zero when the command was successful or an error enumeration when it was not. Error enumerations are documented in Section 3. The LDAP protocol allows LDAP servers to return descriptive text in addition to an error enumeration when an error occurs. ERRTEXT and ERRTEXTCHRS are used to return this descriptive text when such text is supplied by an LDAP server. ERRTEXT will be resized if necessary

18 Parameter Usage Many procedures have one or more pairs of parameters, the first parameter being a pointer type and the second parameter being an integer type. The integer type conveys the length of the data pointed to by the pointer type. If a negative value is passed to the integer, LDAPSUPPORT will scan the data for null (48 00 ) termination to determine the length. Text parameters will be assumed to be in the coded character set specified by SYSOPS HostCCS, unless your application invokes the LDAP_SETUP_CCS procedure. The case sensitivity of text parameters will depend on the underlying protocols and on the LDAP server implementation. Examples of case sensitivity are as follows: DNS names are not case sensitive. Passwords are almost always case sensitive. User names are case sensitive sometimes. Attribute names are usually not case sensitive. Entry Points for Algol The syntax for the entry points documented in this subsection apply to Algol programming. For usage in Cobol, C, or Pascal programs, see Entry Points for Cobol, C, and Pascal later in this section. To use these entry points, include the file *SYMBOL/LDAP/INCLUDE/ALGOL in your program. For more information about this INCLUDE file, refer to Using the Unisys LDAP Client Library in Section

19 LDAP_ADD The LDAP AddRequest operation allows a client to request the addition of an entry into the directory. The LDAPSUPPORT library provides this function with an integer procedure titled LDAP_ADD. Recommended Usage Use the following algorithm to add a directory entry: 1. Invoke the following procedures in this sequence to set up attributes and values for the desired entry: a. LDAP_ATTR_LIST_INIT b. LDAP_ATTR_LIST_ADD_V c. LDAP_ATTR_LIST_ADD_ATTR 2. Call procedure LDAP_SET_DIRENTRY to specify the desired Distinguished Name. 3. Call procedure LDAP_ADD. Declarations INTEGER PROCEDURE LDAP_ADD(ERRTEXT,ERRTEXTCHRS); REFERENCE INTEGER ERRTEXTCHRS; ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

20 LDAP_ATTR_LIST_ADD_ATTR LDAP_ATTR_LIST_ADD_ATTR adds the specified attribute name to the list of attributes to be used on the next LDAP_ADD. Recommended Usage 1. Invoke procedure LDAP_ATTR_LIST_ADD_V to specify the values to be associated with the attribute. You may invoke LDAP_ATTR_LIST_ADD_V multiple times if needed. 2. Call LDAP_ATTR_LIST_ADD_ATTR. Declarations PROCEDURE LDAP_ATTR_LIST_ADD_ATTR(ATTRP,ATTRCHRS); VALUE ATTRP, ATTRCHRS; POINTER ATTRP; INTEGER ATTRCHRS; LIBRARY LDAPSUPPORT; Parameters ATTRP ATTRCHRS The name of the specified attribute. Number of characters in the attribute name provided in ATTRP

21 LDAP_ATTR_LIST_ADD_MODIFICATION LDAP_ATTR_LIST_ADD_MODIFICATION adds the specified attribute name to the list of attributes to be modified by the next LDAP_MODIFY. Recommended Usage 1. Invoke procedure LDAP_ATTR_LIST_ADD_V to specify the values that will be added to, deleted from, or replaced within the attribute. You may invoke LDAP_ATTR_LIST_ADD_V multiple times if needed. 2. Call LDAP_ATTR_LIST_ADD_MODIFICATION. Declaration PROCEDURE LDAP_ATTR_LIST_ADD_MODIFICATION(OP,ATTRP,ATTRCHRS); VALUE OP, ATTRP, ATTRCHRS; INTEGER OP, ATTRCHRS; POINTER ATTRP; LIBRARY LDAPSUPPORT; Parameters OP An integer value representing one of the following operations: 0 = LDAP_C_ADD If attribute values were specified, the values will be added to the specified attribute, creating the attribute if it does not already exist. 1 = LDAP_C_DELETE If attribute values were specified, the values will be deleted from the specified attribute. If this deletes all values of the attribute, the attribute will be deleted. If no attribute values were specified, the attribute and all its values will be deleted. 2 = LDAP_C_REPLACE If attribute values were specified, the values will replace all existing values of the specified attribute. ATTRP ATTRCHRS If no attribute values were specified, the attribute and all its values will be deleted. The name of the specified attribute. Number of characters in the attribute name provided in ATTRP

22 LDAP_ATTR_LIST_ADD_V LDAP_ATTR_LIST_ADD_V adds an attribute value to the list of attribute values that will be associated with the next invocation of either LDAP_ATTR_LIST_ADD_ATTR or LDAP_ATTR_LIST_ADD_MODIFICATION. Declaration PROCEDURE LDAP_ATTR_LIST_ADD_V(VP,VCHRS); VALUE VP, VCHRS; POINTER VP; INTEGER VCHRS; LIBRARY LDAPSUPPORT; Parameters VP VCHRS The name of the attribute value. It will be translated from EBCDIC to UTF-8. Number of characters in the value provided in VP

23 LDAP_ATTR_LIST_INIT LDAP_ATTR_LIST_INIT nulls the attribute specifications used by LDAP_ADD and LDAP_MODIFY. Recommended Usage When setting up an Add: Invoke LDAP_ATTR_LIST_INIT prior to any other invocations, and then call LDAP_ATTR_LIST_ADD_V and LDAP_ATTR_LIST_ADD_ATTR. When setting up a Modify: Invoke LDAP_ATTR_LIST_INIT prior to any other invocations, and then call LDAP_ATTR_LIST_ADD_V and LDAP_ATTR_LIST_ADD_MODIFICATION. Declaration PROCEDURE LDAP_ATTR_LIST_INIT; LIBRARY LDAPSUPPORT;

24 LDAP_BIND The LDAP Bind operation initiates a protocol session between a client and a server and allows the authentication of the client to the server. The Bind operation must be the first operation request received by a server from a client in a protocol session. The LDAPSUPPORT library provides a bind request with an integer procedure called LDAP_BIND. To terminate the protocol session, use LDAP_UNBIND. Declaration INTEGER PROCEDURE LDAP_BIND(HOSTTYPE, HOSTP,HOSTCHRS, AUTHENTICATIONTYPE, NAMEP,NAMECHRS, PASSWORDP,PASSWORDCHRS, ERRTEXT,ERRTEXTCHRS); VALUE HOSTTYPE, HOSTP, HOSTCHRS, AUTHENTICATIONTYPE, NAMEP, NAMECHRS, PASSWORDP, PASSWORDCHRS; REFERENCE POINTER ERRTEXTCHRS; HOSTP, NAMEP, PASSWORDP; INTEGER HOSTTYPE,

25 HOSTCHRS, AUTHENTICATIONTYPE, NAMECHRS, PASSWORDCHRS, ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters HOSTTYPE HOSTP An integer value representing one of the following usages: 1 = LDAP_EXPLICIT_SERVER 2 = LDAP_EXPLICIT_SERVER_UDP 3 = LDAP_STANDARD_DOMAIN 4 = LDAP_STANDARD_SITE 5 = LDAP_ACTIVE_DIRECTORY_DOMAIN 6 = LDAP_ACTIVE_DIRECTORY_SITE 7 = LDAP_ACTIVE_DIRECTORY_DOMAIN_PRIMARY Specifies a DNS name that identifies either the LDAP server or the domain to which the LDAP server belongs. Value is set as follows: If HOSTTYPE=1, then HOSTP and HOSTCHRS specify the DNS name of the LDAP server. If HOSTTYPE=2, then HOSTP and HOSTCHRS specify the DNS name of the LDAP server. Notes: LDAP over UDP will be used. AUTHENTICATIONTYPE must be set to 1 (anonymous). Only search operations will be permitted. If HOSTTYPE=3, then HOSTP and HOSTCHRS specify the DNS name of the domain to which the LDAP server belongs. Note: The LDAP servers in the domain will be tried one at a time until one responds or the list is exhausted. If HOSTTYPE=4, then HOSTP and HOSTCHRS specify the site name and the DNS name of the site and domain to which the LDAP server belongs. Notes: The first node will be taken as the site name. For example, ustr.na.uis.unisys.com would mean site ustr of domain na.uis.unisys.com. The LDAP servers in the site will be tried one at a time until one responds or the list is exhausted

26 If HOSTTYPE=5, then usage is similar to a standard domain (HOSTTYPE=3) except that only Microsoft Active Directory LDAP servers will be used. If HOSTTYPE=6, then usage is similar to a standard site (HOSTTYPE=4) except that only Microsoft Active Directory LDAP servers will be used. If HOSTTYPE=7, then usage is similar to an active directory domain (HOSTTYPE=5) except that only the primary Microsoft Active Directory LDAP server of the domain will be used. HOSTCHRS AUTHENTICATIONTYPE NAMEP Number of characters in the DNS name supplied in HOSTP. An integer value representing one of the following usages: 1 = LDAP_BIND_ANONYMOUS Perform an anonymous LDAP bind. NAMEP, NAMECHRS, PASSWORDP, and PASSWORDCHRS will be ignored. Note: LDAP servers usually place severe restrictions on operations that may be preformed using an anonymous (unauthenticated) session. 2 = LDAP_BIND_CLEARTEXT Perform an authenticated LDAP bind, passing the user name and password across the network in clear text. NAMEP and NAMECHRS specify the user name. PASSWORDP and PASSWORCHRS specify the password. Note: Some LDAP servers may be configured to reject an LDAP bind with cleartext password authentication. 3 = LDAP_BIND_CREDENTIALS Perform an authenticated LDAP bind using Kerberos. NAMEP and NAMECHRS specify the Kerberos identity. PASSWORDP and PASSWORCHRS specify the password. Note: If NAMECHRS and PASSWORDCHRS are both zero in this case, the user must have already acquired Kerberos credentials (for example, by performing a KRB INIT command from MARC), and those credentials will be used for authentication. 11 = LDAP_BIND_ANONYMOUS_ANYVERSION Similar to LDAP_BIND_ANONYMOUS (value=1), except that if the server reports LDAP_RC_protocolError, then LDAPSUPPORT will retry the bind at LDAP protocol level V2. Note: LDAP version V2 (RFC 1777) is a subset of LDAP version V3 (RFC 2251). LDAP version V2 does not support international characters, does not return search references, and does not support the current version of Kerberos authentication. 12 = LDAP_BIND_CLEARTEXT_ANYVERSION Similar to LDAP_BIND_CLEARTEXT (value=2) except that if the server reports LDAP_RC_protocolError, then LDAPSUPPORT will retry the bind at LDAP protocol level V2. Specifies a user name for authentication. Note the following exceptions: If AUTHENTICATIONTYPE=1, then NAMEP and NAMECHRS will

27 be ignored. If AUTHENTICATIONTYPE=3, then NAMEP should be a full Kerberos principal identifier, unless the LDAP server is in the MCP system's default Kerberos realm. For example, if the LDAP server is in realm NA.UIS.UNISYS.COM and that is not the MCP system's default realm, then [email protected] would be appropriate. If the MCP system's default realm was NA.UIS.UNISYS.COM, then craig would be sufficient. NAMECHRS PASSWORDP PASSWORDCHRS Number of characters in the user name supplied in NAMEP. Specifies a password for authentication. Note the following exception: If AUTHENTICATIONTYPE=1, then PASSWORDP, and PASSWORDCHRS will be ignored. Number of characters in the password supplied in PASSWORDP. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

28 LDAP_COMPARE The LDAP Compare operation allows a client to compare an assertion provided with an entry in the Directory. The LDAPSUPPORT library provides this function with an integer procedure titled LDAP_COMPARE. Recommended Usage Use the following algorithm to issue a compare request: 1. Invoke the following procedures in this sequence to set up attributes and values for the compare request: a. LDAP_ATTR_LIST_INIT b. LDAP_ATTR_LIST_ADD_V c. LDAP_ATTR_LIST_ADD_ATTR 2. Call procedure LDAP_COMPARE. 3. To interpret the compare results: If the attribute specified by LDAP_ATTR_LIST_ADD_ATTR exists, and one of its values matches the value specified by LDAP_ATTR_LIST_ADD_V, field LDAP_ERRORF of the procedure result will contain LDAP_RC_compareTrue. If the attribute specified by LDAP_ATTR_LIST_ADD_ATTR exists, and none of its values matches the value specified by LDAP_ATTR_LIST_ADD_V, field LDAP_ERRORF of the procedure result will contain LDAP_RC_compareFalse. Declaration INTEGER PROCEDURE LDAP_COMPARE(ERRTEXT,ERRTEXTCHRS); REFERENCE INTEGER ERRTEXTCHRS; ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

29 LDAP_DELETE The LDAP Delete operation allows a client to request the removal of an entry from the Directory. The LDAPSUPPORT library provides this function with an integer procedure titled LDAP_DELETE. Recommended Usage LDAP_DELETE deletes the entry with the Distinguished Name specified in the most recent LDAP_SET_DIRENTRY invocation. A suggested algorithm is as follows: 1. Call procedure LDAP_SET_DIRENTRY to specify the desired Distinguished Name. 2. Call procedure LDAP_DELETE. Declaration INTEGER PROCEDURE LDAP_DELETE(ERRTEXT,ERRTEXTCHRS); REFERENCE INTEGER ERRTEXTCHRS; ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

30 LDAP_DESCRIBEERROR LDAP_DESCRIBEERROR produces a human-readable text message corresponding to the result, ERRTEXT and ERRCHRS that are returned by an LDAP entry point. Declaration PROCEDURE LDAP_DESCRIBEERROR(ERR,ERRTEXTP,ERRTEXTCHRS, DESCRIPTION,DESCRIPTIONCHRS); VALUE ERR, ERRTEXTP, ERRTEXTCHRS; REFERENCE INTEGER DESCRIPTIONCHRS; ERR, ERRTEXTCHRS, DESCRIPTIONCHRS; POINTER ERRTEXTP; EBCDIC ARRAY DESCRIPTION[0]; Parameters LIBRARY LDAPSUPPORT; ERR ERRTEXTP ERRTEXTCHRS DESCRIPTION DESCRIPTIONCHRS Passes the INTEGER result returned by an LDAP entry point. Passes the error text returned by the LDAP entry point. If the LDAP entry point did not have error text parameters (for example, LDAP_SEARCH_RESPONSE), pass an arbitrary pointer and zero length. The human readable text message is stored in this array. The array will be resized if necessary. The length of the text stored in DESCRIPTION is stored in this variable

31 LDAP_DISPLAYEERROR LDAP_DISPLAYEERROR displays (via the Algol DISPLAY feature) a human readable text message corresponding to the result, ERRTEXT and ERRCHRS returned by an LDAP entry point. Declaration PROCEDURE LDAP_DISPLAYEERROR(ERR,ERRTEXTP,ERRTEXTCHRS); VALUE ERR, ERRTEXTP, ERRTEXTCHRS; INTEGER ERR, ERRTEXTCHRS; POINTER ERRTEXTP; Parameters LIBRARY LDAPSUPPORT; ERR ERRTEXTP ERRTEXTCHRS Pass the INTEGER result returned by an LDAP entry point. Pass the error text returned by the LDAP entry point. If the LDAP entry point did not have error text parameters (for example, LDAP_SEARCH_RESPONSE) pass an arbitrary pointer and zero length

32 LDAP_FIND_SITE LDAP_FIND_SITE uses a combination of DNS and LDAP queries to determine the local site name of the MCP system. It works only in Active Directory domains and relies on the Active Directory's tables of site name to IP subnet masks. Declaration INTEGER PROCEDURE LDAP_FIND_SITE(DOMAINP,DOMAINCHRS, SITE,SITECHRS, ERRTEXT,ERRTEXTCHRS); VALUE DOMAINP, DOMAINCHRS; REFERENCE SITECHRS, ERRTEXTCHRS; POINTER INTEGER DOMAINP; DOMAINCHRS, SITECHRS, ERRTEXTCHRS; EBCDIC ARRAY SITE[0], ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters DOMAINP DOMAINCHRS SITE SITECHRS The DNS name of the domain. Number of characters in the domain name provided in DOMAINP. The site name is stored in this array. The array will be resized if necessary. The number of characters in the site name is stored in this variable. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

33 LDAP_MODIFY The LDAP Modify operation allows a client to request that a modification of the Directory Information Base (DIB) be performed on its behalf by a server. The LDAPSUPPORT library provides this feature with an integer procedure titled LDAP_MODIFY. Recommended Usage Use the following algorithm to modify a directory entry: 1. Invoke the following procedures in this sequence to set up attributes and values for the entry that will be modified: a. LDAP_ATTR_LIST_INIT b. LDAP_ATTR_LIST_ADD_V c. LDAP_ATTR_LIST_ADD_ATTR 2. Call procedure LDAP_SET_DIRENTRY to specify the desired Distinguished Name. 3. Call procedure LDAP_MODIFY. Declaration INTEGER PROCEDURE LDAP_MODIFY(ERRTEXT,ERRTEXTCHRS); REFERENCE INTEGER ERRTEXTCHRS; ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

34 LDAP_MODIFYDN The LDAP ModifyDN operation allows a client to change the leftmost (least significant) component of the name of an entry in the directory, or to move a subtree of entries to a new location in the directory. The LDAPSUPPORT library provides these functions with an integer procedure titled LDAP_MODIFYDN. Recommended Usage To rename a node in the tree, use the following algorithm: 1. Invoke procedure LDAP_SET_DIRENTRY to specify the Distinguished Name to be changed. 2. Invoke procedure LDAP_SET_NEWNAME with parameter SUPERIOR set to FALSE. 3. Call procedure LDAP_MODIFYDN. The Relative Distinguished Name will be set to the name used in LDAP_SET_NEWNAME. To move a node in the tree up by one level, use the following algorithm: 1. Invoke procedure LDAP_SET_DIRENTRY to specify the Distinguished Name to be changed. 2. Invoke procedure LDAP_SET_NEWNAME with parameter SUPERIOR set to TRUE. 3. Call procedure LDAP_MODIFYDN. The Distinguished Name specified by this invocation will become the immediate superior of the entry. Declaration INTEGER PROCEDURE LDAP_MODIFYDN(DELETEOLDRDN, ERRTEXT,ERRTEXTCHRS); VALUE REFERENCE BOOLEAN INTEGER DELETEOLDRDN; ERRTEXTCHRS; DELETEOLDRDN; ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT;

35 Parameters DELETEOLDRDN If FALSE, then the new Relative Distinguished Name will be added to the entry. Note: This value will generate an error if the entry is not permitted to have more than one Relative Distinguished Name. If TRUE, then the new Relative Distinguished Name will replace the old. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

36 LDAP_REFERENCE LDAP_REFERENCE is used to obtain references returned by a search, one reference at a time. LDAP_REFERENCE returns a result partitioned into LDAP_COMMANDF and LDAP_ERRORF, as described in Common Features: LDAP Result Code Handling at the beginning of this section. There are no ERRTEXT and ERRORCHRS parameters for this procedure because none of the possible errors come directly from the LDAP server. Declaration INTEGER PROCEDURE LDAP_REFERENCE(N,REF,REFCHRS); VALUE N; REFERENCE REFCHRS; INTEGER N, REFCHRS; EBCDIC ARRAY REF[0]; LIBRARY LDAPSUPPORT; Parameters N REF REFCHRS The number of the reference. Must be between 1 and the value returned by NREFS of LDAP_SEARCH. The reference is stored in this array. The array will be resized if necessary. Note: LDAP references are formatted as LDAP URL. See RFC The length of the text stored in REF is stored in this variable

37 LDAP_SEARCH The LDAP Search operation allows a client to request that a search be performed on its behalf by a server. The LDAPSUPPORT library provides this function with an integer procedure titled LDAP_SEARCH. Recommended Usage Use the following algorithm to perform an LDAP search: 1. Invoke the following procedures as needed to set up the directory context, filter, and attribute list: LDAP_SET_DIRENTRY LDAP_SEARCH_INIT LDAP_SEARCH_ADD_FILTER LDAP_SEARCH_ADD_BOOLEAN LDAP_SEARCH_ADD_ATTR 2. Call procedure LDAP_SEARCH. Notes: The base object of the search is either a directory entry or a node in the tree of directory entries, and is specified by an earlier invocation of LDAP_SET_DIRENTRY. Note that the root schema of an LDAP server may be obtained by a search with a null base object. (Tip: Specify a search filter of objectclass present and a SCOPE of LDAP_C_BASEOBJECT). Among other things, this will return the root nodes of the various trees of directory entries stored in the LDAP server. Declaration INTEGER PROCEDURE LDAP_SEARCH(SCOPE, DEREFALIASES, SIZELIMIT, TIMELIMIT, TYPESONLY, ASYNC, NFOUND, NREFS, ERRTEXT,ERRTEXTCHRS);

38 VALUE SCOPE, DEREFALIASES, SIZELIMIT, TIMELIMIT, TYPESONLY, ASYNC; REFERENCE NFOUND, NREFS, ERRTEXTCHRS; INTEGER SCOPE, DEREFALIASES, SIZELIMIT, TIMELIMIT, NFOUND, ERRTEXTCHRS; BOOLEAN TYPESONLY, ASYNC; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters SCOPE DEREFALIASES An integer value that indicates the scope of the search to be performed. Possible values are 0 = LDAP_C_BASEOBJECT 1 = LDAP_C_SINGLELEVEL 2 = LDAP_C_WHOLESUBTREE An integer value that indicates how alias objects are to be handled in searching. Possible values are 0 = LDAP_C_NEVERDEREFALIASES

39 SIZELIMIT Do not de-reference aliases. 1 = LDAP_C_DEREFINSEARCHING De-reference aliases in subordinates of the base object. 2 = LDAP_C_DEREFFINDINGBASEOBJ De-reference aliases when locating the base object of the search. 3 = LDAP_C_DEREFALWAYS De-reference aliases in both contexts. The maximum number of entries to be returned. A value of 0 indicates no limit. TIMELIMIT The maximum time (in seconds) allowed for the search. A value of 0 indicates no limit. TYPESONLY FALSE = Return both the attribute names and the associated values. TRUE = Return only the attributes names. ASYNC NFOUND NREFS FALSE = Perform the entire search. TRUE = Issue the search command. Do not wait for the responses. If LDAP_SEARCH succeeds, then LDAP_SEARCH_CONTINUE must be invoked until it fails or until its WHAT parameter returns LDAP_SEARCH_DONE. The number of entries returned by the search is stored in this variable. The data returned by the search may be obtained by invoking procedure LDAP_SEARCH_RESPONSE. Note: A search that locates no entries is not an error. If no entries were found, then NFOUND is set to 0 (zero). The number of references returned by the search is stored in this variable. The references returned by the search may be obtained by invoking procedure LDAP_REFERENCE. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

40 LDAP_SEARCH_ADD_ATTR LDAP_SEARCH_ADD_ATTR is used to construct the list of attributes to be returned by a search. Invoke this procedure once for each attribute to be added to the list. Notes: A null list of attributes (LDAP_SEARCH_ADD_ATTR not invoked after LDAP_SEARCH_INIT) is interpreted by LDAP servers as a request to return all user attributes and no operational attributes. To request all user attributes and a list of specific operational attributes, set the attribute name value to an asterisk (*). Declaration PROCEDURE LDAP_SEARCH_ADD_ATTR(ATTRP,ATTRCHRS); VALUE ATTRP, ATTRCHRS; POINTER ATTRP; INTEGER ATTRCHRS; LIBRARY LDAPSUPPORT; Parameters ATTRP ATTRCHRS The name of the specified attribute. Number of characters in the attribute name provided in ATTRP

41 LDAP_SEARCH_ADD_BOOLEAN LDAP_SEARCH_ADD_FILTER and LDAP_SEARCH_ADD_BOOLEAN are procedures for constructing custom search filters. Recommended Usage To construct more complex search filters, use multiple invocations of LDAP_SEARCH_ADD_FILTER and one or more invocations of LDAP_SEARCH_ADD_BOOLEAN. To combine or negate filter terms constructed with earlier filter invocations, use LDAP_SEARCH_ADD_BOOLEAN. Note: Terms and expressions are added to the left side of the expression, in a manner often referred to as reverse Polish. Declaration BOOLEAN PROCEDURE LDAP_SEARCH_ADD_BOOLEAN(TYPE,TERMS); VALUE TYPE, TERMS; INTEGER TYPE, TERMS; LIBRARY LDAPSUPPORT; Parameters TYPE TERMS An integer value representing one of the following: 18 = LDAP_FILTER_AND The search filter assumes an AND operator between each of the specified terms. 19 = LDAP_FILTER_OR The search filter assumes an OR operator between each of the specified terms. 20 = LDAP_FILTER_NOT Negates a single term. The value provided in TERMS is ignored. 22 = LDAP_FILTER_COMBINE_SUBSTR Combine together the specified number of terms, which must all be SUBSTR terms with the same attribute name. See the example below. The number of terms

42 Example The following sample shows how to construct a filter for attribute LastName to match the wildcard pattern st*i*nd. LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_SUBSTR_FINAL, "LastName","nd"); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_SUBSTR_ANY, "LastName","i"); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_SUBSTR_INITIAL, "LastName","st"); LDAP_SEARCH_ADD_BOOLEAN(LDAP_FILTER_COMBINE_SUBSTR, 3); Procedure Results If there are not enough terms in the filter currently being constructed, LDAP_SEARCH_ADD_BOOLEAN will return TRUE. If TYPE is LDAP_FILTER_COMBINE_SUBSTR and the specified terms are not all SUBSTR terms with the same attribute name, LDAP_SEARCH_ADD_BOOLEAN will return TRUE. If the filter currently being constructed has more than one term at the point where LDAP_SEARCH is invoked, LDAP_SEARCH will report error LDAP_INCOMPLETEFILTER

43 LDAP_SEARCH_ADD_FILTER LDAP_SEARCH_ADD_FILTER and LDAP_SEARCH_ADD_BOOLEAN are procedures for constructing custom search filters. Recommended Usage To establish a simple search filter, use a single invocation of LDAP_SEARCH_ADD_FILTER. To construct more complex search filters, use multiple invocations of LDAP_SEARCH_ADD_FILTER and one or more invocations of LDAP_SEARCH_ADD_BOOLEAN. Declaration PROCEDURE LDAP_SEARCH_ADD_FILTER(TYPE,ATTRP,ATTRCHRS, VALUEP,VALUECHRS); VALUE TYPE, ATTRP, ATTRCHRS, VALUEP, VALUECHRS; INTEGER TYPE, ATTRCHRS, VALUECHRS; POINTER ATTRP, VALUEP; LIBRARY LDAPSUPPORT; Parameters TYPE An integer value representing one of the following: Note: Except where indicated, the specified value is translated from EBCDIC to UTF-8 before being sent to the LDAP server. 10 = LDAP_FILTER_EQL Condition fulfilled when the value of the specified attribute equals the specified value. 11 = LDAP_FILTER_GEQ

44 Condition fulfilled when the value of the specified attribute is greater than or equal to the specified value. 12 = LDAP_FILTER_LEQ Condition fulfilled when the value of the specified attribute is less than or equal to the specified value. 13 = LDAP_FILTER_APPROX Condition fulfilled when the value of the specified attribute is an approximate match to the specified value. Approximate is interpreted by the LDAP server. 14 = LDAP_FILTER_PRESENT Condition fulfilled when the specified attribute is present. (The specified value is ignored.) 15 = LDAP_FILTER_SUBSTR_INITIAL Condition fulfilled when the value of the specified attribute begins with the specified value. 16 = LDAP_FILTER_SUBSTR_ANY Condition fulfilled when the value of the specified attribute contains the specified value. 17 = LDAP_FILTER_SUBSTR_FINAL Condition fulfilled when the value of the specified attribute ends with the specified value. 21 = LDAP_FILTER_EQL_BINARY Condition fulfilled when the value of the specified attribute equals the specified value. The specified value is sent to the LDAP server as EBCDIC, without translation to UTF-8. ATTRP ATTRCHRS VALUEP VALUECHRS The name of the specified attribute. Number of characters in the attribute name provided in ATTRP. The specified value. Note: This parameter is ignored when TYPE = LDAP_FILTER_PRESENT. Number of characters in the value provided in VALUEP

45 LDAP_SEARCH_CONTINUE LDAP_SEARCH_CONTINUE is used for continuing a search that was initiated by an invocation of LDAP_SEARCH with ASYNC TRUE. After LDAP_SEARCH succeeds, LDAP_SEARCH_CONTINUE must be invoked either until it fails or until its WHAT parameter returns LDAP_SEARCH_DONE. Note: To terminate an asynchronous search early, invoke LDAP_SEARCH_CONTINUE with both RESPONSES and REFERENCES set to FALSE. This procedure can take a while, as all search data must be received and discarded. Declaration INTEGER PROCEDURE LDAP_SEARCH_CONTINUE(RESPONSES, REFERENCES, WHAT, RSLTS, TRANSLATED, RAW, REF, REFCHRS, ERRTEXT,ERRTEXTCHRS); VALUE RESPONSES, REFERENCES, TRANSLATED, RAW; REFERENCE WHAT, REFCHRS, ERRTEXTCHRS; BOOLEAN RESPONSES, REFERENCES, TRANSLATED,

46 RAW; INTEGER WHAT, REFCHRS, ERRTEXTCHRS; EBCDIC ARRAY RSLTS[0], REF[0], ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters RESPONSES REFERENCES WHAT FALSE = Do not return search data. Discard it and continue. TRUE = Return search data. FALSE = Do not return search references. Discard them and continue. TRUE = Return search references. An integer value that indicates one of the following: 1 = LDAP_SEARCH_GOTRESPONSE A search response is being returned in RSLTS, formatted according to TRANSLATED and RAW. No search reference is returned. 2 = LDAP_SEARCH_GOTREFERENCE A search reference is being returned in REF that is REFCHRS long. No search response is returned. 3 = LDAP_SEARCH_DONE The search is finished. No search response or search reference is returned. RSLTS The search entry is stored in this array, which will be resized if necessary. The data in this array is structured as a sequence of elements, each with a four-byte header and a variable number of bytes of data. The sequence is terminated by a single null byte. The header for each element consists of a one-byte type followed by a three byte length. The length is the length in bytes of the variable length data that follows and that is the representation of the element. The types are: 0 = LDAP_SEARCH_RESPONSE_STOPPER Indicates that there are no further elements. This tag is not followed by a length and data. 1 = LDAP_SEARCH_RESPONSE_OBJECT The Distinguished Name of the entry. 2 = LDAP_SEARCH_RESPONSE_ATTR

47 The name of an attribute of the entry. 3 = LDAP_SEARCH_RESPONSE_V A value of the attribute named in the prior LDAP_SEARCH_RESPONSE_ATTR element. Note that some attributes will have more than one value. The value has been translated to EBCDIC. 4 = LDAP_SEARCH_RESPONSE_V_RAW A value of the attribute named in the prior LDAP_SEARCH_RESPONSE_ATTR element. The value has not been translated. TRANSLATED RAW REF REFCHRS FALSE = Translated attribute values are not included in RESULTS. TRUE = Attribute values translated to EBCDIC are included in RESULTS. FALSE = Un-translated attribute values are not included in RESULTS. TRUE = Un-translated attribute values are included in RESULTS. Note that if both TRANSLATED and RAW are TRUE, attribute values will appear in RESULTS in pairs, the LDAP_SEARCH_RESPONSE_V value preceding the corresponding LDAP_SEARCH_RESPONSE_V_RAW value. The reference is stored in this array, which will be resized if necessary. Note: LDAP references are formatted as LDAP URL. See RFC The length of the text stored in REF is stored in this variable. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

48 LDAP_SEARCH_EXPRESSION LDAP_SEARCH_EXPRESSION provides an alternate method of constructing a search filter, rather than using LDAP_SEARCH_ADD_FILTER and LDAP_SEARCH_ADD_BOOLEAN LDAP_SEARCH_EXPRESSION accepts a string search filter as defined by RFC Refer to RFC 2254 for the syntax. Declaration INTEGER PROCEDURE LDAP_SEARCH_EXPRESSION(EXPP,EXPCHRS, ERRTEXT,ERRTEXTCHRS); VALUE EXPP, EXPCHRS; REFERENCE POINTER INTEGER ERRTEXTCHRS; EXPP; EXPCHRS, ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters EXPP The string search filter as defined by RFC EXPCHRS Number of characters in the string provided in EXPP. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

49 LDAP_SEARCH_INIT LDAP_SEARCH_INIT nulls the filter and attribute specifications used by LDAP_SEARCH. Recommended Usage When setting up a search, invoke LDAP_SEARCH_INIT prior to invoking a series of the following procedures: LDAP_SEARCH_ADD_FILTER LDAP_SEARCH_ADD_BOOLEAN LDAP_SEARCH_ADD_ATTR Declaration PROCEDURE LDAP_SEARCH_INIT; LIBRARY LDAPSUPPORT;

50 LDAP_SEARCH_RESPONSE LDAP_SEARCH_RESPONSE is used to obtain the data returned by a search, one entry at a time. LDAP_REFERENCE returns a result partitioned into LDAP_COMMANDF and LDAP_ERRORF, as described in Common Features: LDAP Result Code Handling at the beginning of this section. There are no ERRTEXT and ERRORCHRS parameters for this procedure because none of the possible errors come directly from the LDAP server. Declaration INTEGER PROCEDURE LDAP_SEARCH_RESPONSE(N,RSLTS,TRANSLATED,RAW); VALUE N, TRANSLATED, RAW; INTEGER N; EBCDIC ARRAY RSLTS[0]; BOOLEAN TRANSLATED, Parameters RAW; LIBRARY LDAPSUPPORT; N The number of the search result entry. Must be between 1 and the value returned by NFOUND of LDAP_SEARCH. RSLTS The search entry is stored in this array, which will be resized if necessary. The data in this array is structured as a sequence of elements, each with a four-byte header and a variable number of bytes of data. The sequence is terminated by a single null byte. The header for each element consists of a one-byte type followed by a three-byte length. The length is the length in bytes of the variable length data that follows and that is the representation of the element. The types are: 0 = LDAP_SEARCH_RESPONSE_STOPPER Indicates that there are no further elements. This tag is not followed by a length and data. 1 = LDAP_SEARCH_RESPONSE_OBJECT The Distinguished Name of the entry

51 2 = LDAP_SEARCH_RESPONSE_ATTR The name of an attribute of the entry. 3 = LDAP_SEARCH_RESPONSE_V A value of the attribute named in the prior LDAP_SEARCH_RESPONSE_ATTR element. Note that some attributes will have more than one value. The value has been translated to EBCDIC. 4 = LDAP_SEARCH_RESPONSE_V_RAW A value of the attribute named in the prior LDAP_SEARCH_RESPONSE_ATTR element. The value has not been translated. TRANSLATED RAW FALSE = Translated attribute values are not included in RESULTS. TRUE = Attribute values translated to EBCDIC are included in RESULTS. FALSE = Un-translated attribute values are not included in RESULTS. TRUE = Un-translated attribute values are included in RESULTS. Note: If both TRANSLATED and RAW are TRUE, the attribute values will appear in RESULTS in pairs, with the LDAP_SEARCH_RESPONSE_V value preceding the corresponding LDAP_SEARCH_RESPONSE_V_RAW value

52 LDAP_SERVER_LOOKUP LDAP_SERVER_LOOKUP is an internal procedure within the LDAPSUPPORT library. It performs DNS lookups in order to find LDAP (or other service) servers for specified domain names. It is library-exported so that this functionality may be used by itself. Declaration INTEGER PROCEDURE LDAP_SERVER_LOOKUP(DOMAINTYPE, DOMAINP,DOMAINCHRS, SERVERS,NSERVERS); VALUE DOMAINTYPE, DOMAINP, DOMAINCHRS; REFERENCE INTEGER NSERVERS; DOMAINCHRS, DOMAINTYPE, NSERVERS; POINTER DOMAINP; EBCDIC ARRAY SERVERS[0]; Parameters LIBRARY LDAPSUPPORT; DOMAINTYPE DOMAINP DOMAINCHRS An integer value representing one of the following usages: 1 = LDAP_EXPLICIT_SERVER 3 = LDAP_STANDARD_DOMAIN 4 = LDAP_STANDARD_SITE 5 = LDAP_ACTIVE_DIRECTORY_DOMAIN 6 = LDAP_ACTIVE_DIRECTORY_SITE 7 = LDAP_ACTIVE_DIRECTORY_DOMAIN_PRIMARY Specifies a service and a domain, a site and a domain, or just a domain. The value is set as follows: If DOMAINTYPE = 1, then DOMAINP and DOMAINCHRS specify the full DNS name of some service and domain. The DNS names of the appropriate servers in the domain will be returned. For example,

53 _kerberos._tcp.na.uis.unisys.com would return the DNS names of all servers in domain na.uis.unisys.com that have registered with DNS as Kerberos servers. If DOMAINTYPE = 3, then DOMAINP and DOMAINCHRS specify the DNS name of the domain. The DNS names of the LDAP servers in the domain will be returned. If DOMAINTYPE = 4, then DOMAINP and DOMAINCHRS specify the site name and the DNS name of the site and domain to which the LDAP server belongs. The first node will be taken as the site name. For example, ustr.na.uis.unisys.com would mean site ustr of domain na.uis.unisys.com. The DNS names of the LDAP servers in the site will be returned. If DOMAINTYPE = 5, then usage is similar to DOMAINTYPE=3 except that only Microsoft Active Directory LDAP servers will be listed. If DOMAINTYPE = 6, then usage is similar to DOMAINTYPE=4 except that only Microsoft Active Directory LDAP servers will be listed. If DOMAINTYPE = 7, then usage is similar to DOMAINTYPE=5 except that only the primary Microsoft Active Directory LDAP server of the domain will be listed. SERVERS NSERVERS The DNS names and several attributes of the servers found are returned in this array, which will be resized if necessary. The values in this array are structured as a sequence of elements, each with an eight-byte header and a variable number of bytes of data. The header for each element consists of a two-byte priority followed by a two-byte weight followed by a two-byte port number followed by a twobyte length. The length is the length in bytes of the variable length data that follows, which contains the DNS name of the server. The number of servers found

54 LDAP_SET_DIRENTRY LDAP_SET_DIRENTRY establishes a directory context for subsequent LDAP_SEARCH, LDAP_ADD, LDAP_DELETE, LDAP_MODIFY, LDAP_MODIFYDN, or LDAP_COMPARE commands. It specifies either a directory entry or, in the case of some LDAP_SEARCH and LDAP_MODIFYDN commands, a node in the tree of directory entries. Note: The default directory context (the default before LDAP_SET_DIRENTRY is invoked) is the root of the directory tree. Declaration PROCEDURE LDAP_SET_DIRENTRY(ENTRYP,ENTRYCHRS); VALUE ENTRYP, ENTRYCHRS; POINTER ENTRYP; INTEGER ENTRYCHRS; LIBRARY LDAPSUPPORT; Parameters ENTRYP ENTRYCHRS Specifies the directory context. The syntax is that of an LDAP Distinguished Name. An example of a Distinguished Name is cn=trprogl,cn=computers,dc=na,dc=uis,dc=unisys,dc=com This syntax specifies the Active Directory entry for computer trprogl in domain na.uis.unisys.com. Number of characters in the string provided in ENTRYP. Note: ENTRYCHRS=0 specifies the root of the directory tree

55 LDAP_SET_NEWNAME LDAP_SET_NEWNAME establishes the new name or the new location for a subsequent LDAP_MODIFYDN. LDAP_MODIFYDN changes the leftmost (least significant) component of the name of an entry in the directory, or it moves a subtree of entries to a new location in the directory. Declaration PROCEDURE LDAP_SET_NEWNAME(NAMEP,NAMECHRS,SUPERIOR); VALUE NAMEP, NAMECHRS, SUPERIOR; POINTER NAMEP; INTEGER NAMECHRS; BOOLEAN SUPERIOR; LIBRARY LDAPSUPPORT; Parameters NAMEP NAMECHRS SUPERIOR Specifies the new name component or the new location. The syntax is that of an LDAP Distinguished Name. If SUPERIOR=FALSE, then NAMEP and NAMECHRS specify the new name component. The name component must have only one node, and is referred to as a Relative Distinguished Name. If SUPERIOR=TRUE, then NAMEP and NAMECHRS specify the new location in the directory. Boolean switch to indicate usage of NAMEP and NAMECHRS

56 LDAP_SETUP_CCS LDAP_SETUP_CCS establishes the coded character set (CCS) that will be used. Data sent to the LDAP server will be translated from this CCS to UTF-8. Data received from the LDAP server will be translated from UTF-8 to this CCS. The default CCS (when LDAP_SETUP_CCS is not invoked) is the HostCCS from SYSOPS. Notes: UTF-8 is an algorithmic transformation of UCS2. If CENTRALSUPPORT has no translation between the HostCCS and UCS2, then LDAPSUPPORT will display a warning at initialization and will switch the default CCS to ASERIESEBCDIC. Declaration INTEGER PROCEDURE LDAP_SETUP_CCS(CCS,ERRTEXT,ERRTEXTCHRS); VALUE REFERENCE INTEGER CCS; ERRTEXTCHRS; CCS, ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT; Parameters CCS The desired coded character set. This must be an EBCDIC-based CCS. If CENTRALSUPPORT has no translation between this CCS and UCS2, error 272 (LDAP_NO_TRANSLATION) will be reported. Note: For definitions of ERRTEXT and ERRTEXTCHRS, please refer to Common Features: LDAP Result Code Handling at the beginning of this section

57 LDAP_TRACE_SETUP LDAP_TRACE_SETUP initiates or terminates debug tracing, and specifies the filekind for the destination of the debug trace file. Note: Each invocation of LDAP_TRACE_SETUP starts a new trace file. Declaration PROCEDURE LDAP_TRACE_SETUP(OPTIONSV,KINDV); VALUE OPTIONSV, KINDV; INTEGER OPTIONSV, KINDV; LIBRARY LDAPSUPPORT; Parameters OPTIONSV KINDV A bit mask with one bit for each available debug trace option. [0:1] = LDAP_TRACE_RAWF When set, all LDAP data sent and received are traced in HEX and then translated to text. The text translation will assume ASCII representation within LDAP data. [1:1] = LDAP_TRACE_SEARCH_RESULTSF When set, LDAP search results are shown in an organized manner. [2:1] = LDAP_TRACE_SERVER_LOOKUPF When set, the results of DNS lookups (which are used to find LDAP servers for specified domain names) are traced. A file KIND statement with the following possible values: VALUE(PRINTER) The trace data is written to a KIND=PRINTER file. VALUE(REMOTE) The trace data is written to a KIND=REMOTE file. VALUE(DISK) or VALUE(PACK) The trace data is written to a KIND=DISK file. The TITLE of the file will be LDAP_TRACE/<mix number>/<n>, where <n> begins at 1 and increments for each trace to disk from a particular library instance

58 LDAP_UNBIND The function of the Unbind operation is to terminate a protocol session. The LDAPSUPPORT library provides this operation with a procedure titled LDAP_UNBIND. LDAP_UNBIND closes the LDAP session established by an earlier LDAP_BIND. Note that it is not necessary to invoke LDAP_BIND. If a stack goes away without invoking LDAP_UNBIND, the LDAP session will be closed implicitly. Declaration PROCEDURE LDAP_UNBIND; LIBRARY LDAPSUPPORT;

59 Entry Points for COBOL, C, and Pascal A set of LDAPSUPPORT entry points are available that are appropriate for use from COBOL, C, and Pascal. To use the COBOL and C entry points, include one of the following files in your program: For C programs: *SYMBOL/CC/LIBRARY/INCLUDE/LDAP/H *SYMBOL/CC/LIBRARY/INCLUDE/ LDAP.H For COBOL programs: *SYMBOL/LDAP/INCLUDE/COBOL85 For more information about these INCLUDE files, refer to Using the Unisys LDAP Client Library in Section 1. Parameter Transformations The COBOL and C entry points are cover functions that provide the following parameter transformations: In all cases where the Algol entry point has a POINTER/INTEGER pair to specify input string data start and length, the cover function has an EBCDIC ARRAY [*]/INTEGER pair. The start of the data is index zero in the EBCDIC ARRAY. Note that the feature of passing a negative value as the length to imply null-terminated data is especially useful from C. All ERRTEXT/ERRTEXTCHRS parameter pairs are deleted. Instead, the error text is stored in LDAPSUPPORT for later retrieval by LDAP_DESCRIBEERROR_C or LDAP_DISPLAYERROR_C. LDAP_DESCRIBEERROR_C and LDAP_DISPLAYERROR_C do not have ERR, ERRTEXTP and ERRTEXTCHRS parameters. Instead, the values from the most recent invocation of one of the _C cover functions are used. In all cases where the Algol entry point has an EBCDIC ARRAY [0]/INTEGER pair to return string data, the cover function has an EBCDIC ARRAY [*]/INTEGER/INTEGER triple, where both integers are by reference. The data is stored in the EBCDIC ARRAY, starting at index zero. Upon procedure invocation, the first integer must be set to the maximum length (in bytes) of data to be returned. Upon procedure exit, the first integer will contain the length (in bytes) of data actually returned, and the second integer will contain the length (in bytes) of data available. If the second integer is greater than the first, this indicates that data was truncated. Procedure LDAP_GETDATA_C may be used to retrieve the truncated data. In all cases where the Algol entry point has an EBCDIC ARRAY [0] parameter (without a string length integer parameter) to return string data, the cover function has an EBCDIC ARRAY [*]/INTEGER/INTEGER triple, which functions as described in the previous paragraph

60 List of _C Entry Points The names of the COBOL and C entry points are derived by appending _C to the corresponding Algol entry point. Refer to Entry Points for Algol earlier in this section for the declarations and parameters for these entry points. For reference purposes, the _C cover functions are named as follows: LDAP_ADD_C LDAP_ATTR_LIST_ADD_ATTR_C LDAP_ATTR_LIST_ADD_MODIFICATION_C LDAP_ATTR_LIST_ADD_V_C LDAP_ATTR_LIST_INIT_C LDAP_BIND_C LDAP_COMPARE_C LDAP_DELETE_C LDAP_DESCRIBEERROR_C LDAP_DISPLAYERROR_C LDAP_FIND_SITE_C LDAP_MODIFY_C LDAP_MODIFYDN_C LDAP_REFERENCE_C LDAP_SEARCH_ADD_ATTR_C LDAP_SEARCH_ADD_BOOLEAN_C LDAP_SEARCH_ADD_FILTER_C LDAP_SEARCH_C LDAP_SEARCH_CONTINUE_C LDAP_SEARCH_EXPRESSION_C LDAP_SEARCH_INIT_C

61 LDAP_SEARCH_RESPONSE_C LDAP_SERVER_LOOKUP_C LDAP_SET_DIRENTRY_C LDAP_SET_NEWNAME_C LDAP_SETUP_CCS_C LDAP_TRACE_SETUP_C LDAP_UNBIND_C There is an additional entry point for COBOL and C programs, called LDAP_GETDATA_C, that does not have an equivalent entry point in the Algol Include file. Its declaration and parameters are listed below

62 LDAP_GETDATA_C LDAP_GETDATA_C may be used to retrieve string data produced by the previous _C cover function that returned string data. Note: Each _C cover function saves the entire string data, regardless of whether or not it needed to be truncated in order to be returned by the cover function itself. Declaration PROCEDURE LDAP_GETDATA_C(D,INX,DCHRS); VALUE REFERENCE INX; DCHRS; EBCDIC ARRAY D[*]; INTEGER INX, Parameters DCHRS; LIBRARY LDAPSUPPORT; D INX Used to return data, starting at index zero. The byte index in the stored data where the data to be returned starts. DCHRS On invocation, DCHRS represents the maximum amount of data to return. On exit, this is the number of bytes of data actually returned. Note: This number will be less than the requested amount of data only if the end of the stored data is reached

63 Section 3 Result Codes This section lists the enumerated result codes by their LDAPSUPPORT mnemonic equivalents, along with result codes that are an extension to standard LDAP. Result Codes Based on Standard LDAP Result codes 0 through 90 listed in Table 3 1 are defined by RFC Most of these result codes are based on problem indications from X.511 data types, as follows: Result codes 16 through 21 indicate an attribute problem. Result codes 32, 33, 34, and 36 indicate a name problem. Result codes 48 through 50 indicate a security problem. Result codes 51 through 54 indicate a service problem. Result codes 64 through 69 and 71 indicate an update problem. All the result codes listed in Table 3 1 except for success, comparefalse and comparetrue should be treated as meaning the operation could not be completed in its entirety. Refer to RFC 2251, section , for additional information about LDAP standard handling of select result codes. To use these result codes in your application, refer to Common Features: LDAP Result Code Handling at the beginning of Section 2. Note: The portion of the variable name following LDAP_RC_ is the RFC 2251 name of the enumeration. In general, RFC 2251 does not define the semantics of the enumerations other than by giving them these names

64 Result Codes Table 3 1. Result Codes Based on Standard LDAP Value LDAPSUPPORT Library Constant 0 LDAP_RC_success 1 LDAP_RC_operationsError 2 LDAP_RC_protocolError 3 LDAP_RC_timeLimitExceeded 4 LDAP_RC_sizeLimitExceeded 5 LDAP_RC_compareFalse 6 LDAP_RC_compareTrue 7 LDAP_RC_authMethodNotSupported 8 LDAP_RC_strongAuthRequired 9 RFC 2251 reserves this value 10 LDAP_RC_referral 11 LDAP_RC_adminLimitExceeded 12 LDAP_RC_unavailableCriticalExtension 13 LDAP_RC_confidentialityRequired 14 LDAP_RC_saslBindInProgress 16 LDAP_RC_noSuchAttribute 17 LDAP_RC_undefinedAttributeType 18 LDAP_RC_inappropriateMatching 19 LDAP_RC_constraintViolation 20 LDAP_RC_attributeOrValueExists 21 LDAP_RC_invalidAttributeSyntax RFC 2251 does not use these values 32 LDAP_RC_noSuchObject 33 LDAP_RC_aliasProblem 34 LDAP_RC_invalidDNSyntax 35 RFC 2251 reserves this value for undefined isleaf 36 LDAP_RC_aliasDereferencingProblem RFC 2251 does not use these values 48 LDAP_RC_inappropriateAuthentication

65 Result Codes Table 3 1. Result Codes Based on Standard LDAP Value LDAPSUPPORT Library Constant 49 LDAP_RC_invalidCredentials 50 LDAP_RC_insufficientAccessRights 51 LDAP_RC_busy 52 LDAP_RC_unavailable 53 LDAP_RC_unwillingToPerform 54 LDAP_RC_loopDetect RFC 2251 does not use these values 64 LDAP_RC_namingViolation 65 LDAP_RC_objectClassViolation 66 LDAP_RC_notAllowedOnNonLeaf 67 LDAP_RC_notAllowedOnRDN 68 LDAP_RC_entryAlreadyExists 69 LDAP_RC_objectClassModsProhibited 70 RFC 2251 reserves this value for CLDAP 71 LDAP_RC_affectsMultipleDSAs RFC 2251 does not use these values 80 LDAP_RC_other RFC 2251 reserves these values for APIs

66 Result Codes Result Codes That Supplement Standard LDAP The additional result codes listed in Table 3 2 are extensions to the LDAP error reporting ability that are unique to the ClearPath LDAPSUPPORT library. Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 100 LDAP_OPENOFFERFAILED The attempt to open a TCP/IP connection to the LDAP server failed. The open offer failed. TCP/IP is not running on the local MCP system or has configuration problems. 101 LDAP_CLOSEDDURINGOPEN The most likely cause of this error is that the server selected is not accepting TCP/IP connections on the LDAP port (port 389). The attempt to open a TCP/IP connection to the LDAP server failed. The open offer succeeded but an error occurred during connection establishment. 102 LDAP_OPENTIMEOUT The attempt to open a TCP/IP connection to the LDAP server failed. The open offer succeeded but connection establishment timed out. (LDAPSUPPORT waits 20 seconds before abandoning the connection attempt and issuing this error.) The selected LDAP server is not running or is running very slowly or there are network problems. 103 LDAP_WRITEERROR A TCP/IP write to the LDAP server failed. 104 LDAP_READERROR A TCP/IP read from the LDAP server failed. Note: Active Directory (the Microsoft LDAP server) responds to some error conditions by shutting down the TCP/IP circuit rather than by returning an LDAP result code, resulting in this error. 105 LDAP_BADFORMAT Data returned by the LDAP server was improperly formatted. A message envelope was improperly formatted in such a way that the LDAP message boundary within the TCP/IP data stream could not be determined

67 Result Codes Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 106 LDAP_ASNDATASHORT Data returned by the LDAP server was improperly formatted. An ASN.1 length field indicated a length that extended beyond the end of the LDAP message. 107 LDAP_WRONGASNTAG Data returned by the LDAP server was improperly formatted. An ASN.1 tag was encountered which does not match the expected ASN.1 tag, based on LDAP syntax. 108 LDAP_ASNLENGTHFIELDBAD Data returned by the LDAP server was improperly formatted. An ASN.1 length field is improperly formatted. 109 Not used. 110 LDAP_ASNDATABAD Data returned by the LDAP server was improperly formatted. An ASN.1 integer has more than 8 digits. 111 LDAP_WRONGMESSAGEID The message ID in the response from the LDAP server does not match the message ID that was in the corresponding request to the LDAP server. 112 LDAP_UNEXPECTEDRESPONSE The type of response received from the LDAP server does not correspond to the type of request sent to the LDAP server. 113 LDAP_NOSUCHRESPONSE The value of parameter N of LDAP_SEARCH_RESPONSE is not between 1 and the value returned by NFOUND of LDAP_SEARCH. 114 LDAP_SESSIONCLOSED A request to issue an LDAP command occurred when no LDAP session was open. LDAP commands may only be issued after a successful LDAP_BIND and before the corresponding LDAP_UNBIND. 115 LDAP_DISCONNECTION The LDAP server has issued a "Notice of Disconnection." When an LDAP server chooses to shut down the TCP/IP circuit in response to an error condition, the LDAP server may (but is not required to) issue this message before shutting down the TCP/IP circuit. 116 LDAP_NOFILTER LDAP_SEARCH has been invoked without first setting up a search filter

68 Result Codes Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 117 LDAP_INCOMPLETEFILTER LDAP_SEARCH has been invoked with an incomplete search filter. There are multiple terms in the current search filter, which must be combined with LDAP_SEARCH_ADD_BOOLEAN before invoking LDAP_SEARCH. 118 LDAP_NOATTRIBUTE LDAP_COMPARE has been invoked without first setting up the attribute name and attribute value pair for the compare. 119 LDAP_INVALIDATTRIBUTE LDAP_COMPARE has been invoked without properly setting up the attribute name and attribute value pair for the compare. Use this sequence to set up the compare: LDAP_ATTR_LIST_INIT; LDAP_ATTR_LIST_ADD_V; LDAP_ATTR_LIST_ADD_ATTR 120 LDAP_BADPARAM An LDAPSUPPORT entry point has been invoked with an illegal value passed to one of its parameters. 121 LDAP_UDPSEARCHONLY Only the LDAP Search command can be issued over UDP. 122 LDAP_SESSIONOPEN LDAP_BIND has been invoked when an LDAP session was already open. 123 LDAP_NONETLOGON The LDAP request (issued by LDAP_FIND_SITE) for the NetLogon attribute did not return the NetLogon attribute. 124 LDAP_BADNETLOGON The NetLogon attribute data returned by the Active Directory server could not be parsed. 125 LDAP_SITEUNKNOWN Active Directory was unable to determine the site of the MCP system. 126 LDAP_NOSUCHREFERENCE The value of parameter N of LDAP_ REFERENCE is not between 1 and the value returned by NREFS of LDAP_SEARCH. 127 LDAP_ASYNCINPROCESS An asynchronous search is in process. LDAP_SEARCH_CONTINUE must be invoked until it returns LDAP_SEARCH_DONE in parameter WHAT before other LDAP requests are issued. 128 LDAP_UDPSYNCONLY An asynchronous search over UDP has been requested. Only synchronous search is allowed over UDP. 129 LDAP_ASYNCNOTINPROCESS No asynchronous search is in process

69 Result Codes Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 130 LDAP_FALLBACK_V2 This error code is a warning. It indicates that LDAP version V2 (RFC 1777) is being used. LDAP version V2 is a subset of LDAP version V Not used. 150 LDAP_MISSINGLEFTPAREN Missing left parenthesis. May occur while parsing search expressions. 151 LDAP_MISSINGRIGHTPAREN Missing right parenthesis. May occur while parsing search expressions. 152 LDAP_TOOFEWTERMS Too few terms. May occur while parsing search expressions. 153 LDAP_SYNTAXERROR Syntax error. May occur while parsing search expressions. 154 LDAP_ATTREXPECTED Attribute description expected. May occur while parsing search expressions. 155 LDAP_VALUEEXPECTED Attribute value expected. May occur while parsing search expressions. 156 LDAP_NOEXTENSIBLE Extensible matching rule not supported. May occur while parsing search expressions. 157 LDAP_MISSINGOPERATOR Missing operator. May occur while parsing search expressions Not used. 200 LDAP_GSS_LIBMISSING An attempt to link to GSSAPISUPPORT failed. Check the installation of GSSAPISUPPORT. 201 LDAP_GSS_STRTOOID The GSSAPI entry point GSS_STR_TO_OID returned an error. Note: This error should not occur, and would indicate a problem in GSSAPISUPPORT

70 Result Codes Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 202 LDAP_GSS_IMPORTNAME The GSSAPI entry point GSS_IMPORT_NAME returned an error. Note: This error should not occur, and would indicate a problem in GSSAPISUPPORT. 203 LDAP_GSS_AUTHENTICATE Kerberos authentication failed. Possible reasons include the following: The user name and password supplied may be incorrect. KERBEROSSUPPORT may be improperly configured. The system SECOPTs may be improperly configured. The Kerberos authentication server may have problems. Note: See Troubleshooting for Failed Kerberos Authentication later in this section for suggestions on locating the problem. 204 LDAP_GSS_INITCONTEXT There was an error obtaining Kerberos credentials to be sent to the LDAP server during SASL authentication. The most likely cause of this error is that the Kerberos authentication server is not configured to provide Kerberos credentials to the selected LDAP server. 205 LDAP_GSS_WRAPERR There was an error encrypting data to be sent to the LDAP server during SASL authentication. One cause of this error is not having the KRD run-time key (for example, 481-KRD-KRD) installed on the MCP system. 206 LDAP_GSS_UNWRAPERR There was an error decrypting data returned by the LDAP server during SASL authentication Not used. 220 LDAP_SASL_INCOMPLETE The LDAP server failed to complete all the steps of SASL authentication. 221 LDAP_SASL_SECURITY The LDAP server will not accept unencrypted LDAP data Not used. 250 LDAP_DNS_DATABAD The DNS data returned by the DNS server had incorrect syntax

71 Result Codes Table 3 2. Result Codes That Supplement LDAP Value LDAPSUPPORT Library Variable (Integer Constant) Description of Likely Error Condition 251 LDAP_DNS_UNKNOWNNAME The name provided in the DNS request was unknown to DNS. 252 LDAP_DNS_NODATA DNS error: No data of the requested type was found. 253 LDAP_DNS_TIMEOUT The DNS request timed out. 254 LDAP_DNS_ILLEGALNAMESYNTAX Illegal DNS name syntax. 255 LDAP_DNS_NOSERVERSDEFINED RESOLVERSUPPORT has no DNS servers configured. 256 LDAP_DNS_NOSERVERSFOUND RESOLVERSUPPORT was unable to contact a DNS server. 257 LDAP_DNS_OTHER Any RESOLVERSUPPORT error not covered by error codes 255 and Not used. 270 LDAP_UPD_ERROR An error occurred sending or receiving UDP data or setting up to use UDP. 271 Not used. 272 LDAP_NO_TRANSLATION No translation is available for the specified character set

72 Result Codes Troubleshooting for Failed Kerberos Authentication If 203 (LDAP_GSS_AUTHENTICATE) was returned as the error code, check the following conditions: User names are case sensitive in Kerberos, except in some Microsoft extensions. Depending on the configuration of your MCP system, you may or may not experience case sensitive user names when authenticating in a Microsoft Active Directory domain. Passwords in Kerberos are case sensitive. Ensure that passwords are using the proper case. Depending on the default realm specification in the KERBEROSSUPPORT configuration, it may be necessary to include a realm in the user name. For more information on debugging Kerberos problems, refer to the Kerberos documentation

73 Section 4 Usage Examples and Sample Code This section provides algorithms and some sample code for the LDAP operations provided by the Unisys LDAPSUPPORT client library. Performing a Search To perform a search, your program should first set up a filter, which is a specification of what entries the search should return. The search operation will return a list of responses, one for each directory entry that satisfied the filter criteria. Optionally, your application can set up a list of the names of attributes to return from each directory entry that satisfies the filter criteria. If no such list is set up, the server will return all user attributes and no operational attributes. Use the following algorithm to set up a search operation in your program: 1. Invoke LDAP_SEARCH_INIT to null the filter and attributes specifications. 2. Set up the filter in one of two ways: For a simple filter, invoke LDAP_SEARCH_ADD_FILTER once. For a search using boolean combinations of simple filters, invoke LDAP_SEARCH_ADD_FILTER for each simple filter and LDAP_SEARCH_ADD_BOOLEAN to combine terms. Terms and operators are added to the left side of the expression, in a manner often referred to as reverse Polish. Note: Sample code to set up a filter as described in this step appears at the end of this algorithm. 3. If desired, set up the list of attributes. Invoke LDAP_SEARCH_ADD_ATTR for each attribute needed. 4. Invoke LDAP_SET_DIRENTRY to name the base object for the search. 5. Invoke LDAP_SEARCH. 6. For each response, invoke LDAP_SEARCH_RESPONSE to get the data

74 Usage Examples and Sample Code Sample Search Filter If there is a need to find all users named Bob in Pennsylvania, or all users named Sue in New Jersey, or all users named Sam in New York, this search could be expressed as (state = pa AND firstname = bob) OR (state = nj AND firstname = sue) OR (state = ny AND firstname = sam) Using LDAPSUPPORT syntax, the search filter would be encoded as LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, firstname, sam ); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, state, ny ); LDAP_SEARCH_ADD_BOOLEAN(LDAP_FILTER_AND,2); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, firstname, sue ); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, state, nj ); LDAP_SEARCH_ADD_BOOLEAN(LDAP_FILTER_AND,2); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, firstname, bob ); LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_EQL, state, pa ); LDAP_SEARCH_ADD_BOOLEAN(LDAP_FILTER_AND,2); LDAP_SEARCH_ADD_BOOLEAN(LDAP_FILTER_OR,3); Adding a Directory Entry Your program should first set up a list of attributes and their values that will be used by the server to initialize the new directory entry. Use the following algorithm to set up and add a directory entry. 1. Invoke LDAP_ATTR_LIST_INIT to null the attributes list specification. 2. For each attribute, execute the following: a. Invoke LDAP_ATTR_LIST_ADD_V one or more times to specify the values for the attribute. b. Invoke LDAP_ATTR_LIST_ADD_ATTR to specify the name of the attribute. For example, to specify firstname to be joe and friends to be sue and sam, set up attributes as follows: LDAP_ATTR_LIST_ADD_V_S("joe");

75 Usage Examples and Sample Code LDAP_ATTR_LIST_ADD_ATTR_S("firstname"); LDAP_ATTR_LIST_ADD_V_S("sue"); LDAP_ATTR_LIST_ADD_V_S("sam"); LDAP_ATTR_LIST_ADD_ATTR_S("friends"); 3. Invoke LDAP_SET_DIRENTRY to name the object to be added. 4. Invoke LDAP_ADD

76 Usage Examples and Sample Code Modifying a Directory Entry Your program must first set up a list of attributes, values, and actions that will be used by the server to modify the directory entry. Use the following algorithm to set up and modify a directory entry. 1. Invoke LDAP_ATTR_LIST_INIT to null the attributes list specification. 2. For each attribute that will be modified: a. Invoke LDAP_ATTR_LIST_ADD_V one or more times to specify the values for the attribute. b. Invoke LDAP_ATTR_LIST_ADD_MODIFICATION to specify the name of the attribute and the action. For example, to add harry and tom to friends : LDAP_ATTR_LIST_ADD_V_S( harry ); LDAP_ATTR_LIST_ADD_V_S( tom ); LDAP_ATTR_LIST_ADD_MODIFICATION_S(LDAP_C_ADD, friends ); 3. Invoke LDAP_SET_DIRENTRY to name the object to be modified. 4. Invoke LDAP_MODIFY. Deleting a Directory Entry The following algorithm will delete an entry from the directory. 1. Invoke LDAP_SET_DIRENTRY to name the object to be deleted. 2. Invoke LDAP_DELETE

77 Usage Examples and Sample Code Sample Search Query RFC 2255 includes sample syntaxes to retrieve various attributes on an LDAP server located at the University of Michigan. The sample Algol code below demonstrates use of the LDAPSUPPORT client library to perform the RFC 2255 example. BEGIN $ INCLUDE *SYMBOL/LDAP/INCLUDE/ALGOL EBCDIC ARRAY ERRTEXT[0:100]; INTEGER RSLT,ERRTEXTCHRS,NFOUND,NREFS; LDAP_TRACE_SETUP(0 & 0 LDAP_TRACE_RAWF & 1 LDAP_TRACE_SEARCH_RESULTSF, VALUE(REMOTE)); RSLT := LDAP_BIND_S(LDAP_EXPLICIT_SERVER, ldap.itd.umich.edu, LDAP_BIND_ANONYMOUS_ANYVERSION,,, ERRTEXT,ERRTEXTCHRS); LDAP_DISPLAYERROR(RSLT,ERRTEXT[0],ERRTEXTCHRS); LDAP_SEARCH_INIT;

78 Usage Examples and Sample Code LDAP_SEARCH_ADD_FILTER_S(LDAP_FILTER_PRESENT, objectclass, ); LDAP_SET_DIRENTRY_S( o=university of Michigan,c=US ); RSLT := LDAP_SEARCH(LDAP_C_BASEOBJECT, LDAP_C_DEREFALWAYS, 0, 0, FALSE, FALSE, NFOUND, NREFS, ERRTEXT,ERRTEXTCHRS); LDAP_DISPLAYERROR(RSLT,ERRTEXT[0],ERRTEXTCHRS); LDAP_UNBIND; END

79 Appendix A LDAP Constants and Values Table A 1. LDAP Constants and Values Constant Name Value LDAP_ACTIVE_DIRECTORY_DOMAIN 5 LDAP_ACTIVE_DIRECTORY_DOMAIN_PRIMARY 7 LDAP_ACTIVE_DIRECTORY_SITE 6 LDAP_BIND_ANONYMOUS 1 LDAP_BIND_ANONYMOUS_ANYVERSION 11 LDAP_BIND_CLEARTEXT 2 LDAP_BIND_CLEARTEXT_ANYVERSION 12 LDAP_BIND_CREDENTIALS 3 LDAP_C_ADD 0 LDAP_C_BASEOBJECT 0 LDAP_C_DELETE 1 LDAP_C_DEREFALWAYS 3 LDAP_C_DEREFFINDINGBASEOBJ 2 LDAP_C_DEREFINSEARCHING 1 LDAP_C_NEVERDEREFALIASES 0 LDAP_C_REPLACE 2 LDAP_C_SINGLELEVEL 1 LDAP_C_WHOLESUBTREE 2 LDAP_EXPLICIT_SERVER 1 LDAP_EXPLICIT_SERVER_UDP 2 LDAP_FILTER_AND 18 LDAP_FILTER_APPROX 13 LDAP_FILTER_COMBINE_SUBSTR 22 LDAP_FILTER_EQL A 1

80 LDAP Constants and Values Table A 1. LDAP Constants and Values Constant Name Value LDAP_FILTER_EQL_BINARY 21 LDAP_FILTER_GEQ 11 LDAP_FILTER_LEQ 12 LDAP_FILTER_NOT 20 LDAP_FILTER_OR 19 LDAP_FILTER_PRESENT 14 LDAP_FILTER_SUBSTR_ANY 16 LDAP_FILTER_SUBSTR_FINAL 17 LDAP_FILTER_SUBSTR_INITIAL 15 LDAP_SEARCH_DONE 3 LDAP_SEARCH_GOTREFERENCE 2 LDAP_SEARCH_GOTRESPONSE 1 LDAP_SEARCH_RESPONSE_ATTR 2 LDAP_SEARCH_RESPONSE_OBJECT 1 LDAP_SEARCH_RESPONSE_STOPPER 0 LDAP_SEARCH_RESPONSE_V 3 LDAP_SEARCH_RESPONSE_V_RAW 4 LDAP_STANDARD_DOMAIN 3 LDAP_STANDARD_SITE 4 A

81 Index A Add operation, 2-3 adding attribute names, 2-4, 2-6 directory entries, 2-3, 2-7, 4-2 ADJOIN screen, 1-5 ALGOL support, 1-4 algorithm samples, 4-1 attribute name providing, 2-4, 2-6 authentication models, 1-2 B Bind operation, 2-8 boolean search, 2-27 C C cover functions, 2-46 C support, 1-5 client-side implementation, 1-3 COBOL support, 1-5, 2-43 coded character sets, 2-40 common features of entry points, 2-1 comparing attributes on a directory entry, 2-12 constants cross-reference, A-1 constructing search filters, 2-25, 2-27, 2-32 continuing a search, 2-29 D debug tracing, 2-41 declarating the LDAPSUPPORT library, 1-3 Delete operation, 2-13 deleting a directory entry, 4-4 determining the local site name, 2-16 directory entry adding, 2-3, 2-4, 2-6, 2-7, 4-2 deleting, 2-13, 4-4 modifying, 2-7, 2-17, 4-4 specifying, 2-38 Directory services, 1-2 DISPLAY feature, 2-15 DNS local site name, 2-16 server lookups, 2-36 domain names, 2-36 E editing a directory entry, 2-17, 4-4 entry points to LDAPSUPPORT, 2-1 enumerated result codes, 3-1 ERRTEXT and ERRTEXTCHRS parameters, 2-1 establishing coded character set, 2-40 directory context, 2-38 protocol session, 2-8 example search query, 4-5 F filters for search, 2-25, 2-27, 2-32 finding LDAP servers, 2-36 local site name, 2-16 H human-readable text message, 2-14, 2-15 I implementation on Unisys ClearPath servers, Index 1

82 Index scope, 1-3 Include files, 1-4, 1-5 initializing search specifications, 2-33 Initiating a protocol session, 2-8 internet resources for LDAP information, 1-2 interpreting LDAP result codes, 2-14, 2-15 IP subnet masks, 2-16 J Join Active Directory Domain, 1-5 K Kerberos domain authentication, 1-5 L LDAP operations Add, 2-3 Bind, 2-8 Delete, 2-13 Modify, 2-17 ModifyDN, 2-18 Search, 2-21 Unbind, 2-42 LDAP result codes interpreting, 2-14, 2-15 LDAP session closing, 2-42 establishing, 2-8 multiple, 1-6 LDAP_ADD, 2-3, 2-4, 2-6, 2-7 LDAP_ATTR_LIST_ADD_ATTR, 2-4, 2-6, 2-12 LDAP_ATTR_LIST_ADD_MODIFICATION, 2-6 LDAP_ATTR_LIST_ADD_V, 2-3, 2-4, 2-5, 2-6, 2-12, 2-17 LDAP_ATTR_LIST_INIT, 2-3, 2-7, 2-12, 2-17 LDAP_BIND, 2-8 LDAP_COMPARE, 2-12 LDAP_DELETE, 2-13 LDAP_DESCRIBEERROR, 2-14 LDAP_DISPLAYEERROR, 2-15 LDAP_FIND_SITE, 2-16 LDAP_GETDATA_C, 2-46 LDAP_MODIFY, 2-7, 2-17 LDAP_MODIFYDN, 2-18, 2-39 LDAP_REFERENCE, 2-20 LDAP_SEARCH, 2-21 LDAP_SEARCH_ADD_ATTR, 2-24 LDAP_SEARCH_ADD_BOOLEAN, 2-25 LDAP_SEARCH_ADD_FILTER, 2-27 LDAP_SEARCH_CONTINUE, 2-29 LDAP_SEARCH_EXPRESSION, 2-32 LDAP_SEARCH_INIT, 2-33 LDAP_SEARCH_RESPONSE, 2-34 LDAP_SERVER_LOOKUP, 2-36 LDAP_SET_DIRENTRY, 2-3, 2-17, 2-38 LDAP_SET_NEWNAME, 2-18, 2-39 LDAP_SETUP_CCS, 2-40 LDAP_TRACE_SETUP, 2-41 LDAP_UNBIND, 2-8, 2-42 library declaration, 1-3 entry points, 2-1 specifications, 1-4 list of attributes, 2-4, 2-6 local site name finding, 2-16 M MCP environment library, 1-3 Modify operation, 2-17 ModifyDN operation, 2-18 modifying a directory entry, 2-7, 2-17, 4-4 moving a node, 2-18, 2-39 multiple LDAP sessions, 1-6 N node, specifying, 2-38 nulling search specifications, 2-33 O operations Add, 2-3 Bind, 2-8 Delete, 2-13 Modify, 2-17 ModifyDN, 2-18 Search, 2-21 Unbind, 2-42 Overview of LDAP, 1-1 Index

83 Index P parameter usage overview, 2-2 Pascal support, 2-43 performing a search, 4-1 pointer parameters, 2-2 protocol session closing, 2-42 establishing, 2-8 multiple, 1-6 R references from a search operation, 2-20 removing a directory entry, 2-13 renaming a node, 2-18, 2-39 result codes extensions, 3-4 handling, 2-1 interpreting, 2-14, 2-15 standard LDAP, 3-1 results of a search, 2-34 retrieving string data, 2-46 RFC 2255 example, 4-5 RFCs, 1-2 supported authentication models, 1-2 T terminating an LDAP session, 2-42 text message human-readable, 2-14, 2-15 tracing, initiating and terminating, 2-41 U Unbind operation, 2-42 UTF-8, 2-40 X X.500 protocol, 1-1 S sample search query, 4-5 sample syntax for common operations, 4-1 scope of implementation, 1-3 search attributes, 2-24 filters, 2-25, 2-27, 2-32 nulling specifications, 2-33 references, 2-20 results, 2-34 sample algorithm, 4-1 Search operation, 2-21 Security services, 1-2 selecting a character set, 2-40 session closing, 2-42 establishing, 2-8 multiple, 1-6 setting a new name or node, 2-39 specified domain names, 2-36 string data retrieving, 2-46 string search filters, Index 3

84 Index Index

85

86 2008 Unisys Corporation. All rights reserved. * *