ClearPath Enterprise Servers

(1)

Lightweight Directory Access Protocol (LDAP)

Programming Guide

ClearPath MCP 12.0

(2)

(3)

imagine it. done.

ClearPath Enterprise Servers

Lightweight Directory Access Protocol (LDAP)

Programming Guide

ClearPath MCP 12.0

(4)

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.

(5)

Lightweight Directory

Access Protocol (LDAP)

Programming Guide ClearPath MCP 12.0 Directory Access Protocol (LDAP) Programming Guide ClearPath MCP 12.0 4310 9438–001 4310 9438–001

(6)

(7)

Section 1. LDAP and the Unisys LDAP Client Library

Documentation Updates ... 1–1 About This Guide ... 1–1 Overview of LDAP ... 1–1 Learning More About LDAP ... 1–2 Unisys Implementation of LDAP... 1–3 Library File Name and Location ... 1–3 Implementation Scope ... 1–3 Using the Unisys LDAP Client Library ... 1–4 Library Specifications... 1–4 Include Files for Library Declaration ... 1–4 Other Uses for the LDAP Client Library ... 1–5 Invoking Multiple LDAP Sessions ... 1–6

Section 2. LDAP Entry Points

Common Features ... 2–1 LDAP Result Code Handling... 2–1 Parameter Usage ... 2–2 Entry Points for Algol ... 2–2 LDAP_ADD ... 2–3 LDAP_ATTR_LIST_ADD_ATTR... 2–4 LDAP_ATTR_LIST_ADD_MODIFICATION ... 2–5 LDAP_ATTR_LIST_ADD_V ... 2–6 LDAP_ATTR_LIST_INIT ... 2–7 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_MODIFY... 2–17 LDAP_MODIFYDN ... 2–18 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

(8)

LDAP_SEARCH_RESPONSE ...2–34 LDAP_SERVER_LOOKUP ...2–36 LDAP_SET_DIRENTRY...2–38 LDAP_SET_NEWNAME ...2–39 LDAP_SETUP_CCS ...2–40 LDAP_TRACE_SETUP ...2–41 LDAP_UNBIND...2–42 Entry Points for COBOL, C, and Pascal ...2–43 Parameter Transformations...2–43 List of _C Entry Points...2–44 LDAP_GETDATA_C ...2–46

Section 3. Result Codes

Result Codes Based on Standard LDAP...3–1 Result Codes That Supplement Standard LDAP ...3–4 Troubleshooting for Failed Kerberos Authentication...3–10

Section 4. Usage Examples and Sample Code

Performing a Search ...4–1 Adding a Directory Entry...4–2 Modifying a Directory Entry ...4–4 Deleting a Directory Entry ...4–4 Sample Search Query ...4–5

Appendix A. LDAP Constants and Values

(9)

Tables

3–1. Result Codes Based on Standard LDAP ... 3–2 3–2. Result Codes That Supplement LDAP ... 3–4 A–1. LDAP Constants and Values ... A–1

(10)

(11)

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)

18561280. To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site:

http://www.support.unisys.com/all/ple/18561280

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 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 10646” • RFC 1510: “The Kerberos Network Authentication Service (V5)”

• RFC 2743: “The Generic Security Service Application Program Interface Version 2, Update 1”

(13)

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 2251.

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 2254. 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)

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)

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)

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}

(17)

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_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 = [15:16] 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 1.

(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 ERRTEXTCHRS;

INTEGER ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT;

Note:_{For definitions of ERRTEXT and ERRTEXTCHRS, please refer to “Common}

(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 The name of the specified attribute.

(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.

If no attribute values were specified, the attribute and all its values will be deleted.

(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 The name of the attribute value. It will be translated from EBCDIC to UTF-8.

(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 ERRTEXTCHRS; POINTER HOSTP, NAMEP, PASSWORDP; INTEGER HOSTTYPE,

(25)

HOSTCHRS,

AUTHENTICATIONTYPE, NAMECHRS,

PASSWORDCHRS, ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT;

Parameters

HOSTTYPE 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

HOSTP 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 Number of characters in the DNS name supplied in HOSTP.

AUTHENTICATIONTYPE 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 (un-authenticated) 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.

NAMEP Specifies a user name for authentication. Note the following exceptions:

(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 craig@NA.UIS.UNISYS.COM would be appropriate. If the MCP system's default realm was

NA.UIS.UNISYS.COM, then craig would be sufficient. NAMECHRS Number of characters in the user name supplied in NAMEP.

PASSWORDP Specifies a password for authentication. Note the following exception: If AUTHENTICATIONTYPE=1, then PASSWORDP, and

PASSWORDCHRS will be ignored.

PASSWORDCHRS Number of characters in the password supplied in PASSWORDP.

(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 ERRTEXTCHRS;

(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 ERRTEXTCHRS;

(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 DESCRIPTIONCHRS; INTEGER ERR, ERRTEXTCHRS, DESCRIPTIONCHRS; POINTER ERRTEXTP;

EBCDIC ARRAY DESCRIPTION[0]; LIBRARY LDAPSUPPORT;

Parameters

ERR Passes the INTEGER result returned by an LDAP entry point.

ERRTEXTP ERRTEXTCHRS

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.

DESCRIPTION The human readable text message is stored in this array. The array will be resized if necessary.

(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; LIBRARY LDAPSUPPORT; Parameters

ERR Pass the INTEGER result returned by an LDAP entry point.

ERRTEXTP ERRTEXTCHRS

Pass the error text returned by the LDAP entry point. If the LDAP entry point did not have error text parameters (for example,

(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 DOMAINP; INTEGER DOMAINCHRS, SITECHRS, ERRTEXTCHRS; EBCDIC ARRAY SITE[0], ERRTEXT[0]; LIBRARY LDAPSUPPORT;

Parameters

DOMAINP The DNS name of the domain.

DOMAINCHRS Number of characters in the domain name provided in DOMAINP.

SITE The site name is stored in this array. The array will be resized if necessary.

SITECHRS The number of characters in the site name is stored in this variable.

(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 ERRTEXTCHRS;

(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 DELETEOLDRDN;

REFERENCE ERRTEXTCHRS; BOOLEAN DELETEOLDRDN; INTEGER 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}

(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 The number of the reference. Must be between 1 and the value returned by NREFS of LDAP_SEARCH.

REF The reference is stored in this array. The array will be resized if necessary.

Note:_{LDAP references are formatted as LDAP URL. See RFC 2255.}

(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 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

DEREFALIASES An integer value that indicates how alias objects are to be handled in searching. Possible values are

(39)

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.

SIZELIMIT 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 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.

NFOUND 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).

NREFS 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.

(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

(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 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.

(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

(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.

(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.

ATTRCHRS Number of characters in the attribute name provided in ATTRP. VALUEP The specified value.

Note:_{This parameter is ignored when TYPE = LDAP_FILTER_PRESENT.}

(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 FALSE = Do not return search data. Discard it and continue. TRUE = Return search data.

REFERENCES FALSE = Do not return search references. Discard them and continue. TRUE = Return search references.

WHAT 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 FALSE = Translated attribute values are not included in RESULTS. TRUE = Attribute values translated to EBCDIC are included in RESULTS.

RAW 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.

REF The reference is stored in this array, which will be resized if necessary.

Note:_{LDAP references are formatted as LDAP URL. See RFC 2255.}

REFCHRS The length of the text stored in REF is stored in this variable.

(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 2254. Refer to RFC 2254 for the syntax.

Declaration

INTEGER PROCEDURE LDAP_SEARCH_EXPRESSION(EXPP,EXPCHRS,

ERRTEXT,ERRTEXTCHRS); VALUE EXPP, EXPCHRS; REFERENCE ERRTEXTCHRS; POINTER EXPP; INTEGER EXPCHRS, ERRTEXTCHRS; EBCDIC ARRAY ERRTEXT[0]; LIBRARY LDAPSUPPORT;

Parameters

EXPP The string search filter as defined by RFC 2254.

EXPCHRS Number of characters in the string provided in EXPP.

(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, RAW; LIBRARY LDAPSUPPORT; Parameters

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 FALSE = Translated attribute values are not included in RESULTS. TRUE = Attribute values translated to EBCDIC are included in RESULTS.

RAW 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 NSERVERS; INTEGER DOMAINCHRS, DOMAINTYPE, NSERVERS; POINTER DOMAINP; EBCDIC ARRAY SERVERS[0]; LIBRARY LDAPSUPPORT;

Parameters

DOMAINTYPE 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 DOMAINP DOMAINCHRS

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 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 byte “weight” followed by a byte port number followed by a two-byte length.

The length is the length in bytes of the variable length data that follows, which contains the DNS name of the server.

(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 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.

ENTRYCHRS Number of characters in the string provided in ENTRYP.

(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

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.

(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 CCS;

REFERENCE ERRTEXTCHRS; INTEGER 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.

(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 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.

KINDV 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 INX; REFERENCE DCHRS; EBCDIC ARRAY D[*]; INTEGER INX, DCHRS; LIBRARY LDAPSUPPORT; Parameters

D Used to return data, starting at index zero.

INX 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)

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 2251. 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 4.1.10, 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)

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 22–31 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

37–47 RFC 2251 does not use these values

(65)

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

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

80 LDAP_RC_other

(66)

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