rfc1823.txt

最近的中文RFC文档

组织：中国互动出版网（http://www.china-pub.com/）
RFC文档中文翻译计划（http://www.china-pub.com/compters/emook/aboutemook.htm）
E-mail：[e-mail]
译者：牧云（qiaoqli   [e-mail]）
译文发布时间：2001-11-24
版权：本中文翻译文档版权归中国互动出版网所有。可以用于非商业用途自由转载，但必须
保留本文档的翻译及版权信息。


Network Working Group                                           T. Howes
Request for Comments: 1823                                        M. Smith
Category: Informational                                University of  Michigan
August 1995


                     LDAP应用程序接口
（RFC1823——The LDAP Application Program Interface）

备忘录
该备忘录为Internet社区提供信息，它未指明是任何类型的网络标准。该备忘录的发布
不受任何限制。
目录
1.  摘要	2
2.  LDAP模型的观点	2
3.  LDAP API的使用	2
4.  调用LDAP操作	3
4.1.  打开一个联接	3
4.2.  绑定到目录	4
4.3.  关闭连接	5
4.4.  查询	5
4.5.  读取条目	7
4.6.  子条目列表	7
4.7.  修改条目	7
4.8.  修改条目的RDN	8
4.9.  增加条目	9
4.10.  删除条目	10
5.  取消操作	10
6.  结果处理	10
7.  出错处理	11
8.  对查询结果的处理	13
8.1.  条目结果的处理	14
8.2.  对属性结果的处理	14
8.3.  获得属性值	15
8.4.  目录项DN分析处理	16
9.  安全考虑	17
10.  鸣谢	17
11.  参考书目	17
12.  作者地址	18
13.  附： 一个简单的LDAP API代码	18

1.  摘要
   该文档为轻量级目录访问协议（LDAP）定义了一个基于C语言的应用程序接口。该LDAP 
API 功能强大，且易于使用。为了适应应用的大量变化，它采用了兼容的LDAP同步和异
步接口。该文档给出了LDAP模型的基本观点，以及一个应用程序怎样通过这些接口获得
LDAP的信息。这些应用程序接口调用在本文里都有很详细的描述，并且，文档末尾附带有
部分API使用的实例代码。
2.  LDAP模型的观点
   LDAP——轻量级目录访问协议。其描述参见[2]和[7]。它能为X500目录[1]，或独立的
服务（stand-alone service）提供轻量级的访问。在任何模式下，LDAP都是基于客户-服务器
模型的。在客户-服务器模型中，客户通过TCP联接与LDAP服务器相连，并且在此联接上
发送请求和接收响应。
   LDAP信息模型基于包含对象信息（例如，一个人就是一个对象）的条目。条目包含各
种属性，属性由属性类型和属性值两部分组成。其中，一条属性类型可以包含多个属性值。
每个属性都有一套语法，语法规定了属性允许值的类型（例如，一幅jpeg照片的类型为：
ASCII characters）以及在目录操作期间这些值是怎样运作的（例如，在进行值的比较时）。
   条目以树的结构进行组织，通常按行政、地域，以及组织分界限进行划分。每个条目拥
有一个区别于其它兄弟条目的名字——相对区别名（RDN），相对区别名包含了一个或多个
区别属性值，以此区别条目。条目至少有一个属性值属于RDN。例如，Babs Jensen可以被
命名为"Barbara Jensen"，这一值取自普通名属性值。条目全球唯一的名字被称为区别名或
DN。DN由树状结构的根结点到条目的所有结点的RDN组成。例如，如果Babs在密切根
大学（University of Michigan）工作，以他为条目的DN就可能是"cn=Barbara Jensen, 
o=University of Michigan,c=US"。这种用于LDAP的格式的定义参见[4]。
   查询和恢复信息，修改信息，增加及删除条目这些操作都以身份鉴定为前提。下面将讨
论：怎样使用API，以及LDAPL API调用的详细说明。
3.  LDAP API的使用
   一个应用调用LDAP API一般有以下四步：

   o    打开一个到LDAP 服务器的联接。 ldap_open()函数调用返回一个联接句柄，允许
立即建立多联接。

   o    认证LDAP服务器和/或X.500 DSA。函数ldap_bind()友好地支持各种认证方式。

   o   执行其它LDAP操作并获得其值。ldap_search()及其同类函数返回的值能被
ldap_result2error(), ldap_first_entry(), ldap_next_entry()等函数解析。

   o    关闭联接。ldap_unbind()函数调用关闭此联接。

   操作能同步或异步执行。同步调用的函数以_s结尾。例如，调用ldap_search_s()实现同
步查询，调用ldap_search()实现异步查询。所有同步操作返回一个操作结果的指示（例如，
操作成功返回LDAP_SUCCESS，操作失败返回错误代码）。异步操作返回操作初始化信息
id。id能被用于随后的ldap_result()函数调用，以获得操作的结果。通过调用ldap_abandon()
可以丢弃异步操作。
   结果和错误被返回到一个称作LDAPMessage的不透明结构中。
LDAP操作为这一结构提供语法分析，逐步分析返回的目录项或属性等。此外，LDAP操作
还解释出现的错误。下面，将详细描述这些LDAP操作。
4.  调用LDAP操作
   这一部分详细描述了LDAP API的调用。所有调用依赖一个连接句柄，即指向一个包含
所有连接信息的LDAP结构的指针。通常结果将返回到一个LDAPMessage结构中。部分结
构将在下面说明。
4.1.  打开一个联接
   ldap_open() 函数打开一个到LDAP服务器的联接。

              typedef struct ldap {
                      /* ... 隐含参数 ... */
                      int     ld_deref;
                      int     ld_timelimit;
                      int     ld_sizelimit;
                      int     ld_errno;
                      char    *ld_matched;
                      char    *ld_error;
                      /* ...隐含参数... */
              } LDAP;

              LDAP *ldap_open( char *hostname, int portno );

      参数:

      host：  需要联接的LDAP服务器的一个分离空间的主机名列表或者是代表服务器IP
地址的分离的字符串。有序列表中的主机都处于准备被联接状态，直到其中有
一个被成功联接上为止。

      port： 含用于联接的TCP端口号。缺省的LDAP端口能够从常量LDAP_PORT中获
得。

   ldap_open() 返回一个联结句柄, 即一个指向LDAP结构的指针。为随后的绑定到目录服
务器提供参数值。如果打开操作失败，返回NULL。 在其它操作执行之前，必须完成ldap_bind
操作（即绑定到目录服务器），关于ldap_bind的说明在后面会提到。
   调用程序将不考虑LDAP结构域的顺序。可能结构中的某些域在国内图书馆会被采用。
以上的域在下面其它函数调用的描述中会有所提及。
4.2.  绑定到目录
   ldap_bind()及同类函数用于绑定到目录。

           int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

           int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

           int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );

           int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );

           int ldap_kerberos_bind( LDAP *ld, char *dn );

           int ldap_kerberos_bind_s( LDAP *ld, char *dn );

   参数：

   ld     连接句柄；

   dn     进行绑定操作的用户dn；

   cred   认证的证件；

   method  LDAP_AUTH_SIMPLE，LDAP_AUTH_KRBV41，或LDAP_AUTH_ LDAPKRBV42
中的一种，包含用于认证的方式。

   passwd  为ldap_simple_bind()系列专有，用于与目录项中的userPassword属性值作比较。  

   这里有关于bind调用的三种类型，提供简单的认证，kerberos 认证，以及普通事务。由
于第四版本的Kerberos认证使用了通用的ldap_bind() ，忽略了证书部分，因此系统假定存
在有效的认证依据，并且能被用于恢复特定的服务依据。
   与该事务一致的版本的名字以_s结尾。这些事务返回bind操作的结果。如果操作成功，
返回LDAP_SUCCESS，否则返回错误代码。下一节将列出可能出现的错误句柄的更多信息
并且对这些信息加以解释。
   与以上事务一致的版本将返回初始化bind操作的信息id。随后调用ldap_result(),用于获
取bind操作的结果。如果出错，返回-1，并在LDAP结构中设置ld_errno域。
   注意，在bind操作成功之前，其它的所有操作都不能成功，其后的bind调用可用于同
一联接之上的重复认证。
4.3.  关闭连接
   ldap_unbind()  用于解除与目录的绑定并关闭连接。

           int ldap_unbind( LDAP *ld );

   参数：

      ld   连接句柄。

   ldap_unbind()  工作在同步模式，解除与目录的绑定，关掉连接，并在返回前释放ld结
构。ldap_unbind()返回LDAP_SUCCESS (如果请求未被送往LDAP服务器，则返回一个LDAP
错误代码)。在调用完ldap_unbind()之后，ld连接句柄失效。
4.4.  查询
   ldap_search() 及同类函数用于查询LDAP目录，返回匹配的目录项的请求值。
这里有三种形式：

           struct timeval {
                   long    tv_sec;
                   long    tv_usec;
           };
           int ldap_search(
                   LDAP    *ld,
                   char    *base,
                   int     scope,
                   char    *filter,
                   char    *attrs[],
                   int     attrsonly
           );
           int ldap_search_s(
                   LDAP            *ld,
                   char            *base,

                   int             scope,
                   char            *filter,
                   char            *attrs[],
                   int             attrsonly,
                   LDAPMessage     **res
           );
           int ldap_search_st(
                   LDAP            *ld,
                   char            *base,
                   int             scope,
                   char            *filter,
                   char            *attrs[],
                   int             attrsonly,
                   struct timeval  *timeout,
                   LDAPMessage     **res
           );

   参数：

   ld        连接句柄；

   base      最基本的 dn 条件值；

scope    为LDAP_SCOPE_BASE， LDAP_SCOPE_ONELEVEL，或LDAP_SCOPE_SUBTREE，
表示查询的范围。

   filter    匹配的字符串，在RFC 1558 [3]中有详细的描述。

   attrs     为NULL时表示返回所有匹配的条目。非空导致所有可用属性将被恢复。

   attrsonly  布尔值。如果为0则返回属性类型以及属性值；非0则只返回属性类型。

   timeout   当调用ldap_search_st()时，它将指出本地查询的时延值。

   res       当同步调用时，该参数将包含函数调用结束时的一个返回值。

   有三个域决定了查询操作的执行。它们分别是：

   ld_sizelimit  限制查询结果的数目。为0时表示没有限制。

   ld_timelimit  限制查询的时间。为0表示没有限制。

   ld_deref     其值为以下任意一个LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
               LDAP_DEREF_FINDING, 或LDAP_DEREF_ALWAYS，指明查询时别名
将怎样被绑定。 值为LDAP_DEREF_SEARCHING表示在查询时将不允
许别名，但对base指定的条目将不受此限制；值为
LDAP_DEREF_FINDING时情况刚好与LDAP_DEREF_SEARCHING相
反。

   ldap_search()进行的是异步查询。它返回初始化查询的id值。该值被随后调用的
ldap_result()函数获得，对其进行语法分析，并进行相应的描述。如果操作失败，返回-1；并
且，LDAP结构中的ld_errno域将被重设。

   通过调用ldap_search_s()或ldap_search_st()进行同步查询。进程将保持一致，除了
ldap_search_st()函数的额外参数将指定查询的时延。两个函数都将直接返回查询的结果：
LDAP_SUCCESS或者错误代码。查询到的条目的返回值将保存在res参数里。该参数对于
调用者来说是不透明的。条目、属性、值等将通过下面介绍的函数获得。保存在参数res中
的结果当不再被使用时，将通过调用ldap_msgfree()函数进行释放，这在后面会有详细介绍。