1 2 3 4Network Working Group H. Chu 5Internet-Draft Symas Corp. 6Intended status: Informational February 28, 2007 7Expires: September 1, 2007 8 9 10 Using LDAP Over IPC Mechanisms 11 draft-chu-ldap-ldapi-00.txt 12 13Status of this Memo 14 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 24 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 29 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 32 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 35 36 This Internet-Draft will expire on September 1, 2007. 37 38Copyright Notice 39 40 Copyright (C) The IETF Trust (2007). 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55Chu Expires September 1, 2007 [Page 1] 56 57Internet-Draft LDAP Over IPC February 2007 58 59 60Abstract 61 62 When both the LDAP client and server reside on the same machine, 63 communication efficiency can be greatly improved using host- specific 64 IPC mechanisms instead of a TCP session. Such mechanisms can also 65 implicitly provide the client's identity to the server for extremely 66 lightweight authentication. This document describes the 67 implementation of LDAP over Unix IPC that has been in use in OpenLDAP 68 since January 2000, including the URL format used to specify an IPC 69 session. 70 71 72Table of Contents 73 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . 3 75 2. Conventions . . . . . . . . . . . . . . . . . . . . . 4 76 3. Motivation . . . . . . . . . . . . . . . . . . . . . . 5 77 4. User-Visible Specification . . . . . . . . . . . . . . 6 78 4.1. URL Scheme . . . . . . . . . . . . . . . . . . . . . . 6 79 5. Implementation Details . . . . . . . . . . . . . . . . 7 80 5.1. Client Authentication . . . . . . . . . . . . . . . . 7 81 5.2. Other Platforms . . . . . . . . . . . . . . . . . . . 8 82 6. Security Considerations . . . . . . . . . . . . . . . 9 83 7. References . . . . . . . . . . . . . . . . . . . . . . 10 84 7.1. Normative References . . . . . . . . . . . . . . . . . 10 85 7.2. Informative References . . . . . . . . . . . . . . . . 10 86 Appendix A. IANA Considerations . . . . . . . . . . . . . . . . . 11 87 Author's Address . . . . . . . . . . . . . . . . . . . 12 88 Intellectual Property and Copyright Statements . . . . 13 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111Chu Expires September 1, 2007 [Page 2] 112 113Internet-Draft LDAP Over IPC February 2007 114 115 1161. Introduction 117 118 While LDAP is a distributed access protocol, it is common for clients 119 to be deployed on the same machine that hosts the server. Many 120 applications are built on a tight integration of the client code and 121 a co-resident server. In these tightly integrated deployments, where 122 no actual network traffic is involved in the communication, the use 123 of TCP/IP is overkill. Systems like Unix offer native IPC mechanisms 124 that still provide the stream-oriented semantics of a TCP session, 125 but with much greater efficiency. 126 127 Since January 2000, OpenLDAP releases have provided the option to 128 establish LDAP sessions over Unix Domain sockets as well as over 129 TCP/IP. Such sessions are inherently as secure as TCP loopback 130 sessions, but they consume fewer system resources, are much faster to 131 establish and tear down, and they also provide secure identification 132 of the client without requiring any additional passwords or other 133 credentials. 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167Chu Expires September 1, 2007 [Page 3] 168 169Internet-Draft LDAP Over IPC February 2007 170 171 1722. Conventions 173 174 Imperative keywords defined in [RFC2119] are used in this document, 175 and carry the meanings described there. 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223Chu Expires September 1, 2007 [Page 4] 224 225Internet-Draft LDAP Over IPC February 2007 226 227 2283. Motivation 229 230 Many LDAP sessions consist of just one or two requests. Connection 231 setup and teardown can become a significant portion of the time 232 needed to process these sessions. Also under heavy load, the 233 constraints of the 2MSL limit in TCP become a bottleneck. For 234 example, a modest single processor dual-core AMD64 server running 235 OpenLDAP can handle over 32,000 authentication requests per second on 236 100Mbps ethernet, with one connection per request. Connected over a 237 host's loopback interface, the rate is much higher, but connections 238 get completely throttled in under one second, because all of the 239 host's port numbers have been used up and are in TIME_WAIT state. So 240 even when the TCP processing overhead is insignificant, the 241 constraints imposed in [RFC0793] create an artificial limit on the 242 server's performance. No such constraints exist when using IPC 243 mechanisms instead of TCP. 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279Chu Expires September 1, 2007 [Page 5] 280 281Internet-Draft LDAP Over IPC February 2007 282 283 2844. User-Visible Specification 285 286 The only change clients need to implement to use this feature is to 287 use a special URL scheme instead of an ldap:// URL when specifying 288 the target server. Likewise, the server needs to include this URL in 289 the list of addresses on which it will listen. 290 2914.1. URL Scheme 292 293 The "ldapi:" URL scheme is used to denote an LDAP over IPC session. 294 The address portion of the URL is the name of a Unix Domain socket, 295 which is usually a fully qualified Unix filesystem pathname. Slashes 296 in the pathname must be percent-encoded as described in section 2.1 297 of [RFC3986] since they do not represent URL path delimiters in this 298 usage. E.g., for a socket named "/var/run/ldapi" the server URL 299 would be "ldapi://%26var%26run%26ldapi/". In all other respects, an 300 ldapi URL conforms to [RFC4516]. 301 302 If no specific address is supplied, a default address MAY be used 303 implicitly. In OpenLDAP the default address is a compile-time 304 constant and its value is chosen by whoever built the software. 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335Chu Expires September 1, 2007 [Page 6] 336 337Internet-Draft LDAP Over IPC February 2007 338 339 3405. Implementation Details 341 342 The basic transport uses a stream-oriented Unix Domain socket. The 343 semantics of communication over such a socket are essentially 344 identical to using a TCP session. Aside from the actual connection 345 establishment, no special considerations are needed in the client, 346 libraries, or server. 347 3485.1. Client Authentication 349 350 Since their introduction in 4.2 BSD Unix, Unix Domain sockets have 351 also allowed passing credentials from one process to another. Modern 352 systems may provide a server with easier means of obtaining the 353 client's identity. The OpenLDAP implementation exploits multiple 354 methods to acquire the client's identity. The discussion that 355 follows is necessarily platform-specific. 356 357 The OpenLDAP library provides a getpeereid() function to encapsulate 358 all of the mechanisms used to acquire the identity. 359 360 On FreeBSD and MacOSX the native getpeereid() is used. 361 362 On modern Solaris systems the getpeerucred() system call is used. 363 364 On systems like Linux that support the SO_PEERCRED option to 365 getsockopt(), that option is used. 366 367 On Unix systems lacking these explicit methods, descriptor passing is 368 used. In this case, the client must send a message containing the 369 descriptor as its very first action immediately after the socket is 370 connected. The descriptor is attached to an LDAP Abandon Request 371 [RFC4511] with message ID zero, whose parameter is also message ID 372 zero. This request is a pure no-op, and will be harmlessly ignored 373 by any server that doesn't implement the protocol. 374 375 For security reasons, the passed descriptor must be tightly 376 controlled. The client creates a pipe and sends the pipe descriptor 377 in the message. The server receives the descriptor and does an 378 fstat() on it to determine the client's identity. The received 379 descriptor MUST be a pipe, and its permission bits MUST only allow 380 access to its owner. The owner uid and gid are then used as the 381 client's identity. 382 383 Note that these mechanisms are merely used to make the client's 384 identity available to the server. The server will not actually use 385 the identity information unless the client performs a SASL Bind 386 [RFC4513] using the EXTERNAL mechanism. I.e., as with any normal 387 LDAP session, the session remains in the anonymous state until the 388 389 390 391Chu Expires September 1, 2007 [Page 7] 392 393Internet-Draft LDAP Over IPC February 2007 394 395 396 client issues a Bind request. 397 3985.2. Other Platforms 399 400 It is possible to implement the corresponding functionality on 401 Microsoft Windows-based systems using Named Pipes, but thus far there 402 has been no demand for it, so the implementation has not been 403 written. These are brief notes on the steps required for an 404 implementation. 405 406 The Pipe should be created in byte-read mode, and the client must 407 specify SECURITY_IMPERSONATION access when it opens the pipe. The 408 server can then retrieve the client's identity using the 409 GetNamedPipeHandleState() function. 410 411 Since Windows socket handles are not interchangeable with IPC 412 handles, an alternate event handler would have to be provided instead 413 of using Winsock's select() function. 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447Chu Expires September 1, 2007 [Page 8] 448 449Internet-Draft LDAP Over IPC February 2007 450 451 4526. Security Considerations 453 454 This document describes a mechanism for accessing an LDAP server that 455 is co-resident with the client machine. As such, it is inherently 456 immune to security issues associated with using LDAP across a 457 network. The mechanism also provides a means for a client to 458 authenticate itself to the server without exposing any sensitive 459 passwords. The security of this authentication is equal to the 460 security of the host machine. 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503Chu Expires September 1, 2007 [Page 9] 504 505Internet-Draft LDAP Over IPC February 2007 506 507 5087. References 509 5107.1. Normative References 511 512 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 513 Requirement Levels", BCP 14, RFC 2119, March 1997. 514 515 [RFC2717] Petke, R. and I. King, "Registration Procedures for URL 516 Scheme Names", BCP 35, RFC 2717, November 1999. 517 518 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 519 Resource Identifier (URI): Generic Syntax", STD 66, 520 RFC 3986, January 2005. 521 522 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 523 (LDAP): The Protocol", RFC 4511, June 2006. 524 525 [RFC4513] Harrison, R., "Lightweight Directory Access Protocol 526 (LDAP): Authentication Methods and Security Mechanisms", 527 RFC 4513, June 2006. 528 529 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 530 Protocol (LDAP): Uniform Resource Locator", RFC 4516, 531 June 2006. 532 5337.2. Informative References 534 535 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 536 RFC 793, September 1981. 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559Chu Expires September 1, 2007 [Page 10] 560 561Internet-Draft LDAP Over IPC February 2007 562 563 564Appendix A. IANA Considerations 565 566 This document satisfies the requirements of [RFC2717] for 567 registration of a new URL scheme. 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615Chu Expires September 1, 2007 [Page 11] 616 617Internet-Draft LDAP Over IPC February 2007 618 619 620Author's Address 621 622 Howard Chu 623 Symas Corp. 624 18740 Oxnard Street, Suite 313A 625 Tarzana, California 91356 626 USA 627 628 Phone: +1 818 757-7087 629 Email: hyc@symas.com 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671Chu Expires September 1, 2007 [Page 12] 672 673Internet-Draft LDAP Over IPC February 2007 674 675 676Full Copyright Statement 677 678 Copyright (C) The IETF Trust (2007). 679 680 This document is subject to the rights, licenses and restrictions 681 contained in BCP 78, and except as set forth therein, the authors 682 retain all their rights. 683 684 This document and the information contained herein are provided on an 685 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 686 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 687 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 688 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 689 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 690 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 691 692 693Intellectual Property 694 695 The IETF takes no position regarding the validity or scope of any 696 Intellectual Property Rights or other rights that might be claimed to 697 pertain to the implementation or use of the technology described in 698 this document or the extent to which any license under such rights 699 might or might not be available; nor does it represent that it has 700 made any independent effort to identify any such rights. Information 701 on the procedures with respect to rights in RFC documents can be 702 found in BCP 78 and BCP 79. 703 704 Copies of IPR disclosures made to the IETF Secretariat and any 705 assurances of licenses to be made available, or the result of an 706 attempt made to obtain a general license or permission for the use of 707 such proprietary rights by implementers or users of this 708 specification can be obtained from the IETF on-line IPR repository at 709 http://www.ietf.org/ipr. 710 711 The IETF invites any interested party to bring to its attention any 712 copyrights, patents or patent applications, or other proprietary 713 rights that may cover technology that may be required to implement 714 this standard. Please address the information to the IETF at 715 ietf-ipr@ietf.org. 716 717 718Acknowledgment 719 720 Funding for the RFC Editor function is provided by the IETF 721 Administrative Support Activity (IASA). 722 723 724 725 726 727Chu Expires September 1, 2007 [Page 13] 728 729