git.sur5r.net Git - openldap/blob - doc/drafts/draft-chu-ldap-ldapi-xx.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
   3         <!ENTITY rfc793 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.0793.xml'>
   4         <!ENTITY rfc2119        PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
   5         <!ENTITY rfc2717        PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2717.xml'>
   6         <!ENTITY rfc3986        PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
   7          <!ENTITY rfc4422 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4422.xml'>
   8          <!ENTITY rfc4511 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4511.xml'>
   9          <!ENTITY rfc4513 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4513.xml'>
  10          <!ENTITY rfc4516 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4516.xml'>
  11
  12 ]>
  13 <?xml-stylesheet type='text/xsl' href='http://www.greenbytes.de/tech/webdav/rfc2629.xslt' ?>
  14 <?rfc toc="yes" ?>
  15 <?rfc tocdepth="2" ?>
  16 <?rfc tocindent="no" ?>
  17 <?rfc symrefs="yes" ?>
  18 <?rfc sortrefs="yes"?>
  19 <?rfc iprnotified="no" ?>
  20 <?rfc strict="yes" ?>
  21 <rfc category="info" ipr="full3978" docName="draft-chu-ldap-ldapi-00.txt">
  22         <front>
  23                 <title abbrev="LDAP Over IPC">Using LDAP Over IPC Mechanisms</title>
  24                 <author initials="H.C." fullname="Howard Chu" surname="Chu">
  25                         <organization>Symas Corp.</organization>
  26                         <address>
  27                                 <postal>
  28                                         <street>18740 Oxnard Street, Suite 313A</street>
  29                                         <city>Tarzana</city>
  30                                         <region>California</region>
  31                                         <code>91356</code>
  32                                         <country>USA</country>
  33                                 </postal>
  34                                 <phone>+1 818 757-7087</phone>
  35                                 <email>hyc@symas.com</email>
  36                         </address>
  37                 </author>
  38                 <date year="2007" month="February"/>
  39                 <abstract>
  40                         <t>When both the LDAP client and server reside on the same
  41 machine, communication efficiency can be greatly improved using host-
  42 specific IPC mechanisms instead of a TCP session. Such mechanisms can
  43 also implicitly provide the client's identity to the server for
  44 extremely lightweight authentication.
  45                         This document describes the implementation of
  46 LDAP over Unix IPC that has been in use in OpenLDAP since January 2000,
  47 including the URL format used to specify an IPC session.
  48 </t>
  49                 </abstract>
  50         </front>
  51
  52         <middle>
  53
  54                 <section title="Introduction">
  55                         <t>While LDAP is a distributed access protocol, it is
  56 common for clients to be deployed on the same machine that hosts the
  57 server. Many applications are built on a tight integration of the
  58 client code and a co-resident server. In these tightly integrated
  59 deployments, where no actual network traffic is involved in the
  60 communication, the use of TCP/IP is overkill. Systems like Unix
  61 offer native IPC mechanisms that still provide the stream-oriented
  62 semantics of a TCP session, but with much greater efficiency.
  63 </t>
  64                         <t>Since January 2000, OpenLDAP releases have provided
  65 the option to establish LDAP sessions over Unix Domain sockets as
  66 well as over TCP/IP. Such sessions are inherently as secure as TCP
  67 loopback sessions, but they consume fewer system resources, are
  68 much faster to establish and tear down, and they also provide
  69 secure identification of the client without requiring any additional
  70 passwords or other credentials.
  71 </t>
  72                 </section>
  73
  74                 <section title="Conventions">
  75                         <t>Imperative keywords defined in <xref target="RFC2119"/> are used
  76 in this document, and carry the meanings described there.</t>
  77                 </section>
  78
  79                 <section title="Motivation">
  80                         <t>Many LDAP sessions consist of just one or two requests.
  81 Connection setup and teardown can become a significant portion of the time
  82 needed to process these sessions. Also under heavy load, the constraints
  83 of the 2MSL limit in TCP become a bottleneck. For example, a modest
  84 single processor dual-core AMD64 server running OpenLDAP
  85 can handle over 32,000 authentication requests per second on 100Mbps ethernet,
  86 with one connection per request.
  87 Connected over a host's loopback interface, the rate is much higher, but
  88 connections get completely throttled in under one second, because all of
  89 the host's port numbers have been used up and are in TIME_WAIT state. So
  90 even when the TCP processing overhead is insignificant, the constraints
  91 imposed in <xref target="RFC0793"/> create an artificial limit on the
  92 server's performance. No such constraints exist when using IPC mechanisms
  93 instead of TCP.
  94                         </t>
  95                 </section>
  96                 <section title="User-Visible Specification">
  97                         <t>The only change clients need to implement to use
  98 this feature is to use a special URL scheme instead of an ldap:// URL
  99 when specifying the target server. Likewise, the server needs to include
 100 this URL in the list of addresses on which it will listen.</t>
 101                         <section title="URL Scheme">
 102                         <t>The "ldapi:" URL scheme is used to denote an LDAP over IPC
 103 session. The address portion of the URL is the name of a Unix Domain socket,
 104 which is usually a fully qualified Unix filesystem pathname. Slashes in
 105 the pathname must be percent-encoded as described in section 2.1 of
 106 <xref target="RFC3986"/> since they do not represent URL path delimiters
 107 in this usage. E.g., for a socket named "/var/run/ldapi" the server URL
 108 would be "ldapi://%26var%26run%26ldapi/". In all other respects, an
 109 ldapi URL conforms to <xref target="RFC4516"/>.
 110                         </t>
 111                         <t>If no specific address is supplied, a default address MAY
 112 be used implicitly. In OpenLDAP the default address is a compile-time
 113 constant and its value is chosen by whoever built the software.</t>
 114                         </section>
 115                 </section>
 116                 <section title="Implementation Details">
 117                         <t>The basic transport uses a stream-oriented Unix Domain socket.
 118 The semantics of communication over such a socket are essentially identical
 119 to using a TCP session. Aside from the actual connection establishment, no
 120 special considerations are needed in the client, libraries, or server.</t>
 121                         <section title="Client Authentication">
 122                         <t>Since their introduction in 4.2 BSD Unix, Unix Domain sockets
 123 have also allowed passing credentials from one process to another. Modern
 124 systems may provide a server with easier means of obtaining the client's
 125 identity. The OpenLDAP implementation exploits multiple methods to acquire
 126 the client's identity. The discussion that follows is necessarily
 127 platform-specific.</t>
 128                         <t>The OpenLDAP library provides a getpeereid() function to
 129 encapsulate all of the mechanisms used to acquire the identity.</t>
 130                         <t>On FreeBSD and MacOSX the native getpeereid() is used.</t>
 131                         <t>On modern Solaris systems the getpeerucred() system call
 132                         is used.</t>
 133                         <t>On systems like Linux that support the SO_PEERCRED option to
 134                         getsockopt(), that option is used.</t>
 135                         <t>On Unix systems lacking these explicit methods, descriptor
 136                         passing is used. In this case, the client must send a message
 137                         containing the descriptor as its very first action immediately
 138                         after the socket is connected. The descriptor is attached to
 139                         an LDAP Abandon Request <xref target="RFC4511"/>
 140                         with message ID zero, whose parameter
 141                         is also message ID zero. This request is a pure no-op, and
 142                         will be harmlessly ignored by any server that doesn't implement
 143                         the protocol.</t>
 144                         <t>For security reasons, the passed descriptor must be tightly
 145                         controlled. The client creates a pipe and sends the pipe
 146                         descriptor in the message. The server receives the descriptor
 147                         and does an fstat() on it to determine the client's identity.
 148                         The received descriptor MUST be a pipe, and its permission
 149                         bits MUST only allow access to its owner. The owner uid and
 150                         gid are then used as the client's identity.</t>
 151                         <t>Note that these mechanisms are merely used to make the
 152 client's identity available to the server. The server will not actually
 153 use the identity information unless the client performs a SASL Bind <xref target="RFC4513"/>
 154 using the EXTERNAL mechanism. I.e., as with any normal LDAP session, the
 155 session remains in the anonymous state until the client issues a Bind
 156 request.</t>
 157                         </section>
 158                         <section title="Other Platforms">
 159                         <t>It is possible to implement the corresponding functionality
 160 on Microsoft Windows-based systems using Named Pipes, but thus far there
 161 has been no demand for it, so the implementation has not been written.
 162 These are brief notes on the steps required for an implementation.</t>
 163                         <t>The Pipe should be created in byte-read mode,
 164 and the client must specify SECURITY_IMPERSONATION access when it opens
 165 the pipe. The server can then retrieve the client's identity using the
 166 GetNamedPipeHandleState() function.</t>
 167                         <t>Since Windows socket handles are not interchangeable with
 168 IPC handles, an alternate event handler would have to be provided instead
 169 of using Winsock's select() function.</t>
 170                         </section>
 171                 </section>
 172                 <section title="Security Considerations">
 173                 <t>This document describes a mechanism for accessing an LDAP
 174 server that is co-resident with the client machine. As such, it is
 175 inherently immune to security issues associated with using
 176 LDAP across a network. The mechanism also provides a means for
 177 a client to authenticate itself to the server without exposing any
 178 sensitive passwords. The security of this authentication is equal to
 179 the security of the host machine.
 180                 </t>
 181                 </section>
 182         </middle>
 183
 184         <back>
 185                 <references title="Normative References">
 186                         &rfc2119;
 187                         &rfc2717;
 188                         &rfc3986;
 189                         &rfc4511;
 190                         &rfc4513;
 191                         &rfc4516;
 192                 </references>
 193                 <references title="Informative References">
 194                         &rfc793;
 195                 </references>
 196
 197                 <section title="IANA Considerations">
 198                         <t>This document satisfies the requirements of
 199 <xref target="RFC2717"/> for registration of a new URL scheme.
 200                         </t>
 201
 202                 </section>
 203         </back>
 204 </rfc>