<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
	<!ENTITY rfc793	PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.0793.xml'>
	<!ENTITY rfc2119	PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
	<!ENTITY rfc2717	PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2717.xml'>
	<!ENTITY rfc3986	PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
	 <!ENTITY rfc4422 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4422.xml'>
	 <!ENTITY rfc4511 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4511.xml'>
	 <!ENTITY rfc4513 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4513.xml'>
	 <!ENTITY rfc4516 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4516.xml'>

]>
<?xml-stylesheet type='text/xsl' href='http://www.greenbytes.de/tech/webdav/rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="2" ?>
<?rfc tocindent="no" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<rfc category="info" ipr="full3978" docName="draft-chu-ldap-ldapi-00.txt">
	<front>
		<title abbrev="LDAP Over IPC">Using LDAP Over IPC Mechanisms</title>
		<author initials="H.C." fullname="Howard Chu" surname="Chu">
			<organization>Symas Corp.</organization>
			<address>
				<postal>
					<street>18740 Oxnard Street, Suite 313A</street>
					<city>Tarzana</city>
					<region>California</region>
					<code>91356</code>
					<country>USA</country>
				</postal>
				<phone>+1 818 757-7087</phone>
				<email>hyc@symas.com</email>
			</address>
		</author>
		<date year="2007" month="February"/>
		<abstract>
			<t>When both the LDAP client and server reside on the same
machine, communication efficiency can be greatly improved using host-
specific IPC mechanisms instead of a TCP session. Such mechanisms can
also implicitly provide the client's identity to the server for
extremely lightweight authentication.
			This document describes the implementation of
LDAP over Unix IPC that has been in use in OpenLDAP since January 2000,
including the URL format used to specify an IPC session.
</t>
		</abstract>
	</front>

	<middle>

		<section title="Introduction">
			<t>While LDAP is a distributed access protocol, it is
common for clients to be deployed on the same machine that hosts the
server. Many applications are built on a tight integration of the
client code and a co-resident server. In these tightly integrated
deployments, where no actual network traffic is involved in the
communication, the use of TCP/IP is overkill. Systems like Unix
offer native IPC mechanisms that still provide the stream-oriented
semantics of a TCP session, but with much greater efficiency.
</t>
			<t>Since January 2000, OpenLDAP releases have provided
the option to establish LDAP sessions over Unix Domain sockets as
well as over TCP/IP. Such sessions are inherently as secure as TCP
loopback sessions, but they consume fewer system resources, are
much faster to establish and tear down, and they also provide
secure identification of the client without requiring any additional
passwords or other credentials.
</t>
		</section>

		<section title="Conventions">
			<t>Imperative keywords defined in <xref target="RFC2119"/> are used
in this document, and carry the meanings described there.</t>
		</section>

		<section title="Motivation">
			<t>Many LDAP sessions consist of just one or two requests.
Connection setup and teardown can become a significant portion of the time
needed to process these sessions. Also under heavy load, the constraints
of the 2MSL limit in TCP become a bottleneck. For example, a modest
single processor dual-core AMD64 server running OpenLDAP
can handle over 32,000 authentication requests per second on 100Mbps ethernet,
with one connection per request.
Connected over a host's loopback interface, the rate is much higher, but
connections get completely throttled in under one second, because all of
the host's port numbers have been used up and are in TIME_WAIT state. So
even when the TCP processing overhead is insignificant, the constraints
imposed in <xref target="RFC0793"/> create an artificial limit on the
server's performance. No such constraints exist when using IPC mechanisms
instead of TCP.
			</t>
		</section>
		<section title="User-Visible Specification">
			<t>The only change clients need to implement to use
this feature is to use a special URL scheme instead of an ldap:// URL
when specifying the target server. Likewise, the server needs to include
this URL in the list of addresses on which it will listen.</t>
			<section title="URL Scheme">
			<t>The "ldapi:" URL scheme is used to denote an LDAP over IPC
session. The address portion of the URL is the name of a Unix Domain socket,
which is usually a fully qualified Unix filesystem pathname. Slashes in
the pathname must be percent-encoded as described in section 2.1 of
<xref target="RFC3986"/> since they do not represent URL path delimiters
in this usage. E.g., for a socket named "/var/run/ldapi" the server URL
would be "ldapi://%26var%26run%26ldapi/". In all other respects, an
ldapi URL conforms to <xref target="RFC4516"/>.
			</t>
			<t>If no specific address is supplied, a default address MAY
be used implicitly. In OpenLDAP the default address is a compile-time
constant and its value is chosen by whoever built the software.</t>
			</section>
		</section>
		<section title="Implementation Details">
			<t>The basic transport uses a stream-oriented Unix Domain socket.
The semantics of communication over such a socket are essentially identical
to using a TCP session. Aside from the actual connection establishment, no
special considerations are needed in the client, libraries, or server.</t>
			<section title="Client Authentication">
			<t>Since their introduction in 4.2 BSD Unix, Unix Domain sockets
have also allowed passing credentials from one process to another. Modern
systems may provide a server with easier means of obtaining the client's
identity. The OpenLDAP implementation exploits multiple methods to acquire
the client's identity. The discussion that follows is necessarily
platform-specific.</t>
			<t>The OpenLDAP library provides a getpeereid() function to
encapsulate all of the mechanisms used to acquire the identity.</t>
			<t>On FreeBSD and MacOSX the native getpeereid() is used.</t>
			<t>On modern Solaris systems the getpeerucred() system call
			is used.</t>
			<t>On systems like Linux that support the SO_PEERCRED option to
			getsockopt(), that option is used.</t>
			<t>On Unix systems lacking these explicit methods, descriptor
			passing is used. In this case, the client must send a message
			containing the descriptor as its very first action immediately
			after the socket is connected. The descriptor is attached to
			an LDAP Abandon Request <xref target="RFC4511"/>
			with message ID zero, whose parameter
			is also message ID zero. This request is a pure no-op, and
			will be harmlessly ignored by any server that doesn't implement
			the protocol.</t>
			<t>For security reasons, the passed descriptor must be tightly
			controlled. The client creates a pipe and sends the pipe
			descriptor in the message. The server receives the descriptor
			and does an fstat() on it to determine the client's identity.
			The received descriptor MUST be a pipe, and its permission
			bits MUST only allow access to its owner. The owner uid and
			gid are then used as the client's identity.</t>
			<t>Note that these mechanisms are merely used to make the
client's identity available to the server. The server will not actually
use the identity information unless the client performs a SASL Bind <xref target="RFC4513"/>
using the EXTERNAL mechanism. I.e., as with any normal LDAP session, the
session remains in the anonymous state until the client issues a Bind
request.</t>
			</section>
			<section title="Other Platforms">
			<t>It is possible to implement the corresponding functionality
on Microsoft Windows-based systems using Named Pipes, but thus far there
has been no demand for it, so the implementation has not been written.
These are brief notes on the steps required for an implementation.</t>
			<t>The Pipe should be created in byte-read mode,
and the client must specify SECURITY_IMPERSONATION access when it opens
the pipe. The server can then retrieve the client's identity using the
GetNamedPipeHandleState() function.</t>
			<t>Since Windows socket handles are not interchangeable with
IPC handles, an alternate event handler would have to be provided instead
of using Winsock's select() function.</t>
			</section>
		</section>
		<section title="Security Considerations">
		<t>This document describes a mechanism for accessing an LDAP
server that is co-resident with the client machine. As such, it is
inherently immune to security issues associated with using
LDAP across a network. The mechanism also provides a means for
a client to authenticate itself to the server without exposing any
sensitive passwords. The security of this authentication is equal to
the security of the host machine.
		</t>
		</section>
	</middle>

	<back>
		<references title="Normative References">
			&rfc2119;
			&rfc2717;
			&rfc3986;
			&rfc4511;
			&rfc4513;
			&rfc4516;
		</references>
		<references title="Informative References">
			&rfc793;
		</references>

		<section title="IANA Considerations">
			<t>This document satisfies the requirements of
<xref target="RFC2717"/> for registration of a new URL scheme.
			</t>

		</section>
	</back>
</rfc>
