source4/ldap_server/devdocs/rfc2307.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                          L. Howard
   8 Request for Comments: 2307                        Independent Consultant
   9 Category: Experimental                                        March 1998
  10
  11
  12       An Approach for Using LDAP as a Network Information Service
  13
  14 Status of this Memo
  15
  16    This memo defines an Experimental Protocol for the Internet
  17    community.  It does not specify an Internet standard of any kind.
  18    Discussion and suggestions for improvement are requested.
  19    Distribution of this memo is unlimited.
  20
  21 Copyright Notice
  22
  23    Copyright (C) The Internet Society (1998).  All Rights Reserved.
  24
  25 Abstract
  26
  27    This document describes an experimental mechanism for mapping
  28    entities related to TCP/IP and the UNIX system into X.500 [X500]
  29    entries so that they may be resolved with the Lightweight Directory
  30    Access Protocol [RFC2251]. A set of attribute types and object
  31    classes are proposed, along with specific guidelines for interpreting
  32    them.
  33
  34    The intention is to assist the deployment of LDAP as an
  35    organizational nameservice. No proposed solutions are intended as
  36    standards for the Internet. Rather, it is hoped that a general
  37    consensus will emerge as to the appropriate solution to such
  38    problems, leading eventually to the adoption of standards. The
  39    proposed mechanism has already been implemented with some success.
  40
  41 1. Background and Motivation
  42
  43    The UNIX (R) operating system, and its derivatives (specifically,
  44    those which support TCP/IP and conform to the X/Open Single UNIX
  45    specification [XOPEN]) require a means of looking up entities, by
  46    matching them against search criteria or by enumeration. (Other
  47    operating systems that support TCP/IP may provide some means of
  48    resolving some of these entities. This schema is applicable to those
  49    environments also.)
  50
  51    These entities include users, groups, IP services (which map names to
  52    IP ports and protocols, and vice versa), IP protocols (which map
  53    names to IP protocol numbers and vice versa), RPCs (which map names
  54    to ONC Remote Procedure Call [RFC1057] numbers and vice versa), NIS
  55
  56
  57
  58 Howard                        Experimental                      [Page 1]
  59 \f
  60 RFC 2307      Using LDAP as a Network Information Service     March 1998
  61
  62
  63    netgroups, booting information (boot parameters and MAC address
  64    mappings), filesystem mounts, IP hosts and networks, and RFC822 mail
  65    aliases.
  66
  67    Resolution requests are made through a set of C functions, provided
  68    in the UNIX system's C library. For example, the UNIX system utility
  69    "ls", which enumerates the contents of a filesystem directory, uses
  70    the C library function getpwuid() in order to map user IDs to login
  71    names. Once the request is made, it is resolved using a "nameservice"
  72    which is supported by the client library. The nameservice may be, at
  73    its simplest, a collection of files in the local filesystem which are
  74    opened and searched by the C library. Other common nameservices
  75    include the Network Information Service (NIS) and the Domain Name
  76    System (DNS). (The latter is typically used for resolving hosts,
  77    services and networks.) Both these nameservices have the advantage of
  78    being distributed and thus permitting a common set of entities to be
  79    shared amongst many clients.
  80
  81    LDAP is a distributed, hierarchical directory service access protocol
  82    which is used to access repositories of users and other network-
  83    related entities. Because LDAP is often not tightly integrated with
  84    the host operating system, information such as users may need to be
  85    kept both in LDAP and in an operating system supported nameservice
  86    such as NIS. By using LDAP as the the primary means of resolving
  87    these entities, these redundancy issues are minimized and the
  88    scalability of LDAP can be exploited. (By comparison, NIS services
  89    based on flat files do not have the scalability or extensibility of
  90    LDAP or X.500.)
  91
  92    The object classes and attributes defined below are suitable for
  93    representing the aforementioned entities in a form compatible with
  94    LDAP and X.500 directory services.
  95
  96 2. General Issues
  97
  98 2.1. Terminology
  99
 100    The key words "MUST", "SHOULD", and "MAY" used in this document are
 101    to be interpreted as described in [RFC2119].
 102
 103    For the purposes of this document, the term "nameservice" refers to a
 104    service, such as NIS or flat files, that is used by the operating
 105    system to resolve entities within a single, local naming context.
 106    Contrast this with a "directory service" such as LDAP, which supports
 107    extensible schema and multiple naming contexts.
 108
 109
 110
 111
 112
 113
 114 Howard                        Experimental                      [Page 2]
 115 \f
 116 RFC 2307      Using LDAP as a Network Information Service     March 1998
 117
 118
 119    The term "NIS-related entities" broadly refers to entities which are
 120    typically resolved using the Network Information Service. (NIS was
 121    previously known as YP.) Deploying LDAP for resolving these entities
 122    does not imply that NIS be used, as a gateway or otherwise. In
 123    particular, the host and network classes are generically applicable,
 124    and may be implemented on any system that wishes to use LDAP or X.500
 125    for host and network resolution.
 126
 127    The "DUA" (directory user agent) refers to the LDAP client querying
 128    these entities, such as an LDAP to NIS gateway or the C library.  The
 129    "client" refers to the application which ultimately makes use of the
 130    information returned by the resolution. It is irrelevant whether the
 131    DUA and the client reside within the same address space. The act of
 132    the DUA making this information to the client is termed
 133    "republishing".
 134
 135    To avoid confusion, the term "login name" refers to the user's login
 136    name (being the value of the uid attribute) and the term "user ID"
 137    refers to he user's integer identification number (being the value of
 138    the uidNumber attribute).
 139
 140    The phrases "resolving an entity" and "resolution of entities" refer
 141    respectively to enumerating NIS-related entities of a given type, and
 142    matching them against a given search criterion. One or more entities
 143    are returned as a result of successful "resolutions" (a "match"
 144    operation will only return one entity).
 145
 146    The use of the term UNIX does not confer upon this schema the
 147    endorsement of owners of the UNIX trademark. Where necessary, the
 148    term "TCP/IP entity" is used to refer to protocols, services, hosts,
 149    and networks, and the term "UNIX entity" to its complement. (The
 150    former category does not mandate the host operating system supporting
 151    the interfaces required for resolving UNIX entities.)
 152
 153    The OIDs defined below are derived from iso(1) org(3) dod(6)
 154    internet(1) directory(1) nisSchema(1).
 155
 156 2.2. Attributes
 157
 158    The attributes and classes defined in this document are summarized
 159    below.
 160
 161    The following attributes are defined in this document:
 162
 163            uidNumber
 164            gidNumber
 165            gecos
 166            homeDirectory
 167
 168
 169
 170 Howard                        Experimental                      [Page 3]
 171 \f
 172 RFC 2307      Using LDAP as a Network Information Service     March 1998
 173
 174
 175            loginShell
 176            shadowLastChange
 177            shadowMin
 178            shadowMax
 179            shadowWarning
 180            shadowInactive
 181            shadowExpire
 182            shadowFlag
 183            memberUid
 184            memberNisNetgroup
 185            nisNetgroupTriple
 186            ipServicePort
 187            ipServiceProtocol
 188            ipProtocolNumber
 189            oncRpcNumber
 190            ipHostNumber
 191            ipNetworkNumber
 192            ipNetmaskNumber
 193            macAddress
 194            bootParameter
 195            bootFile
 196            nisMapName
 197            nisMapEntry
 198
 199    Additionally, some of the attributes defined in [RFC2256] are
 200    required.
 201
 202 2.3. Object classes
 203
 204    The following object classes are defined in this document:
 205
 206            posixAccount
 207            shadowAccount
 208            posixGroup
 209            ipService
 210            ipProtocol
 211            oncRpc
 212            ipHost
 213            ipNetwork
 214            nisNetgroup
 215            nisMap
 216            nisObject
 217            ieee802Device
 218            bootableDevice
 219
 220    Additionally, some of the classes defined in [RFC2256] are required.
 221
 222
 223
 224
 225
 226 Howard                        Experimental                      [Page 4]
 227 \f
 228 RFC 2307      Using LDAP as a Network Information Service     March 1998
 229
 230
 231 2.4. Syntax definitions
 232
 233    The following syntax definitions [RFC2252] are used by this schema.
 234    The nisNetgroupTripleSyntax represents NIS netgroup triples:
 235
 236            ( nisSchema.0.0 NAME 'nisNetgroupTripleSyntax'
 237              DESC 'NIS netgroup triple' )
 238
 239    Values in this syntax are represented by the following:
 240
 241         nisnetgrouptriple = "(" hostname "," username "," domainname ")"
 242         hostname          = "" / "-" / keystring
 243         username          = "" / "-" / keystring
 244         domainname        = "" / "-" / keystring
 245
 246    X.500 servers may use the following representation of the above
 247    syntax:
 248
 249         nisNetgroupTripleSyntax ::= SEQUENCE {
 250          hostname  [0] IA5String OPTIONAL,
 251          username  [1] IA5String OPTIONAL,
 252          domainname  [2] IA5String OPTIONAL
 253         }
 254
 255    The bootParameterSyntax syntax represents boot parameters:
 256
 257            ( nisSchema.0.1 NAME 'bootParameterSyntax'
 258              DESC 'Boot parameter' )
 259
 260    where:
 261
 262         bootparameter     = key "=" server ":" path
 263         key               = keystring
 264         server            = keystring
 265         path              = keystring
 266
 267    X.500 servers may use the following representation of the above
 268    syntax:
 269
 270         bootParameterSyntax ::= SEQUENCE {
 271          key     IA5String,
 272          server  IA5String,
 273          path    IA5String
 274         }
 275
 276    Values adhering to these syntaxes are encoded as strings by LDAP
 277    servers.
 278
 279
 280
 281
 282 Howard                        Experimental                      [Page 5]
 283 \f
 284 RFC 2307      Using LDAP as a Network Information Service     March 1998
 285
 286
 287 3. Attribute definitions
 288
 289    This section contains attribute definitions to be implemented by DUAs
 290    supporting this schema.
 291
 292         ( nisSchema.1.0 NAME 'uidNumber'
 293           DESC 'An integer uniquely identifying a user in an
 294                 administrative domain'
 295           EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE )
 296
 297         ( nisSchema.1.1 NAME 'gidNumber'
 298           DESC 'An integer uniquely identifying a group in an
 299                 administrative domain'
 300           EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE )
 301
 302         ( nisSchema.1.2 NAME 'gecos'
 303           DESC 'The GECOS field; the common name'
 304           EQUALITY caseIgnoreIA5Match
 305           SUBSTRINGS caseIgnoreIA5SubstringsMatch
 306           SYNTAX 'IA5String' SINGLE-VALUE )
 307
 308         ( nisSchema.1.3 NAME 'homeDirectory'
 309           DESC 'The absolute path to the home directory'
 310           EQUALITY caseExactIA5Match
 311           SYNTAX 'IA5String' SINGLE-VALUE )
 312
 313         ( nisSchema.1.4 NAME 'loginShell'
 314           DESC 'The path to the login shell'
 315           EQUALITY caseExactIA5Match
 316           SYNTAX 'IA5String' SINGLE-VALUE )
 317
 318         ( nisSchema.1.5 NAME 'shadowLastChange'
 319           EQUALITY integerMatch
 320           SYNTAX 'INTEGER' SINGLE-VALUE )
 321
 322         ( nisSchema.1.6 NAME 'shadowMin'
 323           EQUALITY integerMatch
 324           SYNTAX 'INTEGER' SINGLE-VALUE )
 325
 326         ( nisSchema.1.7 NAME 'shadowMax'
 327           EQUALITY integerMatch
 328           SYNTAX 'INTEGER' SINGLE-VALUE )
 329
 330         ( nisSchema.1.8 NAME 'shadowWarning'
 331           EQUALITY integerMatch
 332           SYNTAX 'INTEGER' SINGLE-VALUE )
 333
 334         ( nisSchema.1.9 NAME 'shadowInactive'
 335
 336
 337
 338 Howard                        Experimental                      [Page 6]
 339 \f
 340 RFC 2307      Using LDAP as a Network Information Service     March 1998
 341
 342
 343           EQUALITY integerMatch
 344           SYNTAX 'INTEGER' SINGLE-VALUE )
 345
 346         ( nisSchema.1.10 NAME 'shadowExpire'
 347           EQUALITY integerMatch
 348           SYNTAX 'INTEGER' SINGLE-VALUE )
 349
 350         ( nisSchema.1.11 NAME 'shadowFlag'
 351           EQUALITY integerMatch
 352           SYNTAX 'INTEGER' SINGLE-VALUE )
 353
 354         ( nisSchema.1.12 NAME 'memberUid'
 355           EQUALITY caseExactIA5Match
 356           SUBSTRINGS caseExactIA5SubstringsMatch
 357           SYNTAX 'IA5String' )
 358
 359         ( nisSchema.1.13 NAME 'memberNisNetgroup'
 360           EQUALITY caseExactIA5Match
 361           SUBSTRINGS caseExactIA5SubstringsMatch
 362           SYNTAX 'IA5String' )
 363
 364         ( nisSchema.1.14 NAME 'nisNetgroupTriple'
 365           DESC 'Netgroup triple'
 366           SYNTAX 'nisNetgroupTripleSyntax' )
 367
 368         ( nisSchema.1.15 NAME 'ipServicePort'
 369           EQUALITY integerMatch
 370           SYNTAX 'INTEGER' SINGLE-VALUE )
 371
 372         ( nisSchema.1.16 NAME 'ipServiceProtocol'
 373           SUP name )
 374
 375         ( nisSchema.1.17 NAME 'ipProtocolNumber'
 376           EQUALITY integerMatch
 377           SYNTAX 'INTEGER' SINGLE-VALUE )
 378
 379         ( nisSchema.1.18 NAME 'oncRpcNumber'
 380           EQUALITY integerMatch
 381           SYNTAX 'INTEGER' SINGLE-VALUE )
 382
 383         ( nisSchema.1.19 NAME 'ipHostNumber'
 384           DESC 'IP address as a dotted decimal, eg. 192.168.1.1,
 385                 omitting leading zeros'
 386           EQUALITY caseIgnoreIA5Match
 387           SYNTAX 'IA5String{128}' )
 388
 389         ( nisSchema.1.20 NAME 'ipNetworkNumber'
 390           DESC 'IP network as a dotted decimal, eg. 192.168,
 391
 392
 393
 394 Howard                        Experimental                      [Page 7]
 395 \f
 396 RFC 2307      Using LDAP as a Network Information Service     March 1998
 397
 398
 399                 omitting leading zeros'
 400           EQUALITY caseIgnoreIA5Match
 401           SYNTAX 'IA5String{128}' SINGLE-VALUE )
 402
 403         ( nisSchema.1.21 NAME 'ipNetmaskNumber'
 404           DESC 'IP netmask as a dotted decimal, eg. 255.255.255.0,
 405                 omitting leading zeros'
 406           EQUALITY caseIgnoreIA5Match
 407           SYNTAX 'IA5String{128}' SINGLE-VALUE )
 408
 409         ( nisSchema.1.22 NAME 'macAddress'
 410           DESC 'MAC address in maximal, colon separated hex
 411                 notation, eg. 00:00:92:90:ee:e2'
 412           EQUALITY caseIgnoreIA5Match
 413           SYNTAX 'IA5String{128}' )
 414
 415         ( nisSchema.1.23 NAME 'bootParameter'
 416           DESC 'rpc.bootparamd parameter'
 417           SYNTAX 'bootParameterSyntax' )
 418
 419         ( nisSchema.1.24 NAME 'bootFile'
 420           DESC 'Boot image name'
 421           EQUALITY caseExactIA5Match
 422           SYNTAX 'IA5String' )
 423
 424         ( nisSchema.1.26 NAME 'nisMapName'
 425           SUP name )
 426
 427         ( nisSchema.1.27 NAME 'nisMapEntry'
 428           EQUALITY caseExactIA5Match
 429           SUBSTRINGS caseExactIA5SubstringsMatch
 430           SYNTAX 'IA5String{1024}' SINGLE-VALUE )
 431
 432 4. Class definitions
 433
 434    This section contains class definitions to be implemented by DUAs
 435    supporting the schema.
 436
 437    The rfc822MailGroup object class MAY be used to represent a mail
 438    group for the purpose of alias expansion. Several alternative schemes
 439    for mail routing and delivery using LDAP directories, which are
 440    outside the scope of this document.
 441
 442         ( nisSchema.2.0 NAME 'posixAccount' SUP top AUXILIARY
 443           DESC 'Abstraction of an account with POSIX attributes'
 444           MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
 445           MAY ( userPassword $ loginShell $ gecos $ description ) )
 446
 447
 448
 449
 450 Howard                        Experimental                      [Page 8]
 451 \f
 452 RFC 2307      Using LDAP as a Network Information Service     March 1998
 453
 454
 455         ( nisSchema.2.1 NAME 'shadowAccount' SUP top AUXILIARY
 456           DESC 'Additional attributes for shadow passwords'
 457           MUST uid
 458           MAY ( userPassword $ shadowLastChange $ shadowMin
 459                 shadowMax $ shadowWarning $ shadowInactive $
 460                 shadowExpire $ shadowFlag $ description ) )
 461
 462         ( nisSchema.2.2 NAME 'posixGroup' SUP top STRUCTURAL
 463           DESC 'Abstraction of a group of accounts'
 464           MUST ( cn $ gidNumber )
 465           MAY ( userPassword $ memberUid $ description ) )
 466
 467         ( nisSchema.2.3 NAME 'ipService' SUP top STRUCTURAL
 468           DESC 'Abstraction an Internet Protocol service.
 469                 Maps an IP port and protocol (such as tcp or udp)
 470                 to one or more names; the distinguished value of
 471                 the cn attribute denotes the service's canonical
 472                 name'
 473           MUST ( cn $ ipServicePort $ ipServiceProtocol )
 474           MAY ( description ) )
 475
 476         ( nisSchema.2.4 NAME 'ipProtocol' SUP top STRUCTURAL
 477           DESC 'Abstraction of an IP protocol. Maps a protocol number
 478                 to one or more names. The distinguished value of the cn
 479                 attribute denotes the protocol's canonical name'
 480           MUST ( cn $ ipProtocolNumber $ description )
 481           MAY description )
 482
 483         ( nisSchema.2.5 NAME 'oncRpc' SUP top STRUCTURAL
 484           DESC 'Abstraction of an Open Network Computing (ONC)
 485                [RFC1057] Remote Procedure Call (RPC) binding.
 486                This class maps an ONC RPC number to a name.
 487                The distinguished value of the cn attribute denotes
 488                the RPC service's canonical name'
 489           MUST ( cn $ oncRpcNumber $ description )
 490           MAY description )
 491
 492         ( nisSchema.2.6 NAME 'ipHost' SUP top AUXILIARY
 493
 494           DESC 'Abstraction of a host, an IP device. The distinguished
 495                 value of the cn attribute denotes the host's canonical
 496                 name. Device SHOULD be used as a structural class'
 497           MUST ( cn $ ipHostNumber )
 498           MAY ( l $ description $ manager ) )
 499
 500         ( nisSchema.2.7 NAME 'ipNetwork' SUP top STRUCTURAL
 501           DESC 'Abstraction of a network. The distinguished value of
 502                 the cn attribute denotes the network's canonical name'
 503
 504
 505
 506 Howard                        Experimental                      [Page 9]
 507 \f
 508 RFC 2307      Using LDAP as a Network Information Service     March 1998
 509
 510
 511           MUST ( cn $ ipNetworkNumber )
 512           MAY ( ipNetmaskNumber $ l $ description $ manager ) )
 513
 514         ( nisSchema.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL
 515           DESC 'Abstraction of a netgroup. May refer to other netgroups'
 516           MUST cn
 517           MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) )
 518
 519         ( nisSchema.2.09 NAME 'nisMap' SUP top STRUCTURAL
 520           DESC 'A generic abstraction of a NIS map'
 521           MUST nisMapName
 522           MAY description )
 523
 524         ( nisSchema.2.10 NAME 'nisObject' SUP top STRUCTURAL
 525           DESC 'An entry in a NIS map'
 526           MUST ( cn $ nisMapEntry $ nisMapName )
 527           MAY description )
 528
 529         ( nisSchema.2.11 NAME 'ieee802Device' SUP top AUXILIARY
 530           DESC 'A device with a MAC address; device SHOULD be
 531                 used as a structural class'
 532           MAY macAddress )
 533
 534         ( nisSchema.2.12 NAME 'bootableDevice' SUP top AUXILIARY
 535           DESC 'A device with boot parameters; device SHOULD be
 536                 used as a structural class'
 537           MAY ( bootFile $ bootParameter ) )
 538
 539 5. Implementation details
 540
 541 5.1. Suggested resolution methods
 542
 543    The preferred means of directing a client application (one using the
 544    shared services of the C library) to use LDAP as its information
 545    source for the functions listed in 5.2 is to modify the source code
 546    to directly query LDAP. As the source to commercial C libraries and
 547    applications is rarely available to the end-user, one could emulate a
 548    supported nameservice (such as NIS). (This is also an appropriate
 549    opportunity to perform caching of entries across process address
 550    spaces.) In the case of NIS, reference implementations are widely
 551    available and the RPC interface is well known.
 552
 553    The means by which the operating system is directed to use LDAP is
 554    implementation dependent. For example, some operating systems and C
 555    libraries support end-user extensible resolvers using dynamically
 556    loadable libraries and a nameservice "switch". The means in which the
 557    DUA locates LDAP servers is also implementation dependent.
 558
 559
 560
 561
 562 Howard                        Experimental                     [Page 10]
 563 \f
 564 RFC 2307      Using LDAP as a Network Information Service     March 1998
 565
 566
 567 5.2. Affected library functions
 568
 569    The following functions are typically found in the C libraries of
 570    most UNIX and POSIX compliant systems. An LDAP search filter
 571    [RFC2254] which may be used to satisfy the function call is included
 572    alongside each function name. Parameters are denoted by %s and %d for
 573    string and integer arguments, respectively. Long lines are broken.
 574
 575         getpwnam()              (&(objectClass=posixAccount)(uid=%s))
 576         getpwuid()              (&(objectClass=posixAccount)
 577                                 (uidNumber=%d))
 578         getpwent()              (objectClass=posixAccount)
 579
 580         getspnam()              (&(objectClass=shadowAccount)(uid=%s))
 581         getspent()              (objectClass=shadowAccount)
 582
 583         getgrnam()              (&(objectClass=posixGroup)(cn=%s))
 584         getgrgid()              (&(objectClass=posixGroup)
 585                                 (gidNumber=%d))
 586         getgrent()              (objectClass=posixGroup)
 587
 588         getservbyname()         (&(objectClass=ipService)
 589                                 (cn=%s)(ipServiceProtocol=%s))
 590         getservbyport()         (&(objectClass=ipService)
 591                                 (ipServicePort=%d)
 592                                 (ipServiceProtocol=%s))
 593         getservent()            (objectClass=ipService)
 594
 595         getrpcbyname()          (&(objectClass=oncRpc)(cn=%s))
 596         getrpcbynumber()        (&(objectClass=oncRpc)(oncRpcNumber=%d))
 597         getrpcent()             (objectClass=oncRpc)
 598
 599         getprotobyname()        (&(objectClass=ipProtocol)(cn=%s))
 600         getprotobynumber()      (&(objectClass=ipProtocol)
 601                                 (ipProtocolNumber=%d))
 602         getprotoent()           (objectClass=ipProtocol)
 603
 604         gethostbyname()         (&(objectClass=ipHost)(cn=%s))
 605         gethostbyaddr()         (&(objectClass=ipHost)(ipHostNumber=%s))
 606         gethostent()            (objectClass=ipHost)
 607
 608         getnetbyname()          (&(objectClass=ipNetwork)(cn=%s))
 609         getnetbyaddr()          (&(objectClass=ipNetwork)
 610                                 (ipNetworkNumber=%s))
 611         getnetent()             (objectClass=ipNetwork)
 612
 613         setnetgrent()           (&(objectClass=nisNetgroup)(cn=%s))
 614
 615
 616
 617
 618 Howard                        Experimental                     [Page 11]
 619 \f
 620 RFC 2307      Using LDAP as a Network Information Service     March 1998
 621
 622
 623 5.3. Interpreting user and group entries
 624
 625    User and group resolution is initiated by the functions prefixed by
 626    getpw and getgr respectively. The uid attribute contains the user's
 627    login name. The cn attribute, in posixGroup entries, contains the
 628    group's name.
 629
 630    The account object class provides a convenient structural class for
 631    posixAccount, and SHOULD be used where additional attributes are not
 632    required.
 633
 634    It is suggested that uid and cn are used as the RDN attribute type
 635    for posixAccount and posixGroup entries, respectively.
 636
 637    An account's GECOS field is preferably determined by a value of the
 638    gecos attribute. If no gecos attribute exists, the value of the cn
 639    attribute MUST be used. (The existence of the gecos attribute allows
 640    information embedded in the GECOS field, such as a user's telephone
 641    number, to be returned to the client without overloading the cn
 642    attribute. It also accommodates directories where the common name
 643    does not contain the user's full name.)
 644
 645    An entry of class posixAccount, posixGroup, or shadowAccount without
 646    a userPassword attribute MUST NOT be used for authentication. The
 647    client should be returned a non-matchable password such as "x".
 648
 649    userPassword values MUST be represented by following syntax:
 650
 651         passwordvalue          = schemeprefix encryptedpassword
 652         schemeprefix           = "{" scheme "}"
 653         scheme                 = "crypt" / "md5" / "sha" / altscheme
 654         altscheme              = "x-" keystring
 655         encryptedpassword      = encrypted password
 656
 657    The encrypted password contains of a plaintext key hashed using the
 658    algorithm scheme.
 659
 660    userPassword values which do not adhere to this syntax MUST NOT be
 661    used for authentication. The DUA MUST iterate through the values of
 662    the attribute until a value matching the above syntax is found. Only
 663    if encryptedpassword is an empty string does the user have no
 664    password. DUAs are not required to consider encryption schemes which
 665    the client will not recognize; in most cases, it may be sufficient to
 666    consider only "crypt".
 667
 668    Below is an example of a userPassword attribute:
 669
 670                     userPassword: {crypt}X5/DBrWPOQQaI
 671
 672
 673
 674 Howard                        Experimental                     [Page 12]
 675 \f
 676 RFC 2307      Using LDAP as a Network Information Service     March 1998
 677
 678
 679    A future standard may specify LDAP v3 attribute descriptions to
 680    represent hashed userPasswords, as noted below. This schema MUST NOT
 681    be used with LDAP v2 DUAs and DSAs.
 682
 683         attributetype           = attributename sep attributeoption
 684         attributename           = "userPassword"
 685         sep                     = ";"
 686         attributeoption         = schemeclass "-" scheme
 687         schemeclass             = "hash" / altschemeclass
 688         scheme                  = "crypt" / "md5" / "sha" / altscheme
 689         altschemeclass          = "x-" keystring
 690         altscheme               = keystring
 691
 692
 693    Below is an example of a userPassword attribute, represented with an
 694    LDAP v3 attribute description:
 695
 696            userPassword;hash-crypt: X5/DBrWPOQQaI
 697
 698
 699    A DUA MAY utilise the attributes in the shadowAccount class to
 700    provide shadow password service (getspnam() and getspent()). In such
 701    cases, the DUA MUST NOT make use of the userPassword attribute for
 702    getpwnam() et al, and MUST return a non-matchable password (such as
 703    "x") to the client instead.
 704
 705 5.4. Interpreting hosts and networks
 706
 707    The ipHostNumber and ipNetworkNumber attributes are defined in
 708    preference to dNSRecord (defined in [RFC1279]), in order to simplify
 709    the DUA's role in interpreting entries in the directory. A dNSRecord
 710    expresses a complete resource record, including time to live and
 711    class data, which is extraneous to this schema.
 712
 713    Additionally, the ipHost and ipNetwork classes permit a host or
 714    network (respectively) and all its aliases to be represented by a
 715    single entry in the directory. This is not necessarily possible if a
 716    DNS resource record is mapped directly to an LDAP entry.
 717    Implementations that wish to use LDAP to master DNS zone information
 718    are not precluded from doing so, and may simply avoid the ipHost and
 719    ipNetwork classes.
 720
 721    This document redefines, although not exclusively, the ipNetwork
 722    class defined in [RFC1279], in order to achieve consistent naming
 723    with ipHost. The ipNetworkNumber attribute is also used in the
 724    siteContact object class [ROSE].
 725
 726
 727
 728
 729
 730 Howard                        Experimental                     [Page 13]
 731 \f
 732 RFC 2307      Using LDAP as a Network Information Service     March 1998
 733
 734
 735    The trailing zeros in a network address MUST be omitted. CIDR-style
 736    network addresses (eg. 192.168.1/24) MAY be used.
 737
 738    Hosts with IPv6 addresses MUST be written in their "preferred" form
 739    as defined in section 2.2.1 of [RFC1884], such that all components of
 740    the address are indicated and leading zeros are omitted. This
 741    provides a consistent means of resolving ipHosts by address.
 742
 743 5.5. Interpreting other entities
 744
 745    In general, a one-to-one mapping between entities and LDAP entries is
 746    proposed, in that each entity has exactly one representation in the
 747    DIT. In some cases this is not feasible; for example, a service which
 748    is represented in more than one protocol domain. Consider the
 749    following entry:
 750
 751            dn: cn=domain, dc=aja, dc=com
 752            cn: domain
 753            cn: nameserver
 754            objectClass: top
 755            objectClass: ipService
 756            ipServicePort: 53
 757            ipServiceProtocol: tcp
 758            ipServiceProtocol: udp
 759
 760    This entry MUST map to the following two (2) services entities:
 761
 762            domain  53/tcp  nameserver
 763            domain  53/udp  nameserver
 764
 765    While the above two entities may be represented as separate LDAP
 766    entities, with different distinguished names (such as
 767    cn=domain+ipServiceProtocol=tcp, ... and
 768    cn=domain+ipServiceProtocol=udp, ...) it is convenient to represent
 769    them as a single entry. (If a service is represented in multiple
 770    protocol domains with different ports, then multiple entries are
 771    required; multivalued RDNs may be used to distinguish them.)
 772
 773    With the exception of userPassword values, which are parsed according
 774    to the syntax considered in section 5.2, any empty values (consisting
 775    of a zero length string) are returned by the DUA to the client. The
 776    DUA MUST reject any entries which do not conform to the schema
 777    (missing mandatory attributes). Non-conforming entries SHOULD be
 778    ignored while enumerating entries.
 779
 780    The nisObject object class MAY be used as a generic means of
 781    representing NIS entities. Its use is not encouraged; where support
 782    for entities not described in this schema is desired, an appropriate
 783
 784
 785
 786 Howard                        Experimental                     [Page 14]
 787 \f
 788 RFC 2307      Using LDAP as a Network Information Service     March 1998
 789
 790
 791    schema should be devised. Implementors are strongly advised to
 792    support end-user extensible mappings between NIS entities and object
 793    classes. (Where the nisObject class is used, the nisMapName attribute
 794    may be used as a RDN.)
 795
 796 5.6. Canonicalizing entries with multi-valued naming attributes
 797
 798    For entities such as hosts, services, networks, protocols, and RPCs,
 799    where there may be one or more aliases, the respective entry's
 800    relative distinguished name SHOULD be used to determine the canonical
 801    name.  Any other values for the same attribute are used as aliases.
 802    For example, the service described in section 5.5 has the canonical
 803    name "domain" and exactly one alias, "nameserver".
 804
 805    The schema in this document generally only defines one attribute per
 806    class which is suitable for distinguishing an entity (excluding any
 807    attributes with integer syntax; it is assumed that entries will be
 808    distinguished on name). Usually, this is the common name (cn)
 809    attribute.  This aids the DUA in determining the canonical name of an
 810    entity, as it can examine the value of the relative distinguished
 811    name. Aliases are thus any values of the distinguishing attribute
 812    (such as cn) which do not match the canonical name of the entity.
 813
 814    In the event that a different attribute is used to distinguish the
 815    entry, as may be the case where these object classes are used as
 816    auxiliary classes, the entry's canonical name may not be present in
 817    the RDN. In this case, the DUA MUST choose one of the non-
 818    distinguished values to represent the entity's canonical name. As the
 819    directory server guarantees no ordering of attribute values, it may
 820    not be possible to distinguish an entry deterministically. This
 821    ambiguity SHOULD NOT be resolved by mapping one directory entry into
 822    multiple entities.
 823
 824 6. Implementation focus
 825
 826    A NIS server which uses LDAP instead of local files has been
 827    developed which supports the schema defined in this document.
 828
 829    A reference implementation of the C library resolution code has been
 830    written for the Free Software Foundation. It may support other C
 831    libraries which support the Name Service Switch (NSS) or the
 832    Information Retrieval Service (IRS).
 833
 834    The author has made available a freely distributable set of scripts
 835    which parses local databases such as /etc/passwd and /etc/hosts into
 836    a form suitable for loading into an LDAP server.
 837
 838
 839
 840
 841
 842 Howard                        Experimental                     [Page 15]
 843 \f
 844 RFC 2307      Using LDAP as a Network Information Service     March 1998
 845
 846
 847 7. Security Considerations
 848
 849    The entirety of related security considerations are outside the scope
 850    of this document. It is noted that making passwords encrypted with a
 851    widely understood hash function (such as crypt()) available to non-
 852    privileged users is dangerous because it exposes them to dictionary
 853    and brute-force attacks.  This is proposed only for compatibility
 854    with existing UNIX system implementations. Sites where security is
 855    critical SHOULD consider using a strong authentication service for
 856    user authentication.
 857
 858    Alternatively, the encrypted password could be made available only to
 859    a subset of privileged DUAs, which would provide "shadow" password
 860    service to client applications. This may be difficult to enforce.
 861
 862    Because the schema represents operating system-level entities, access
 863    to these entities SHOULD be granted on a discretionary basis. (There
 864    is little point in restricting access to data which will be
 865    republished without restriction, however.) It is particularly
 866    important that only administrators can modify entries defined in this
 867    schema, with the exception of allowing a principal to change their
 868    password (which may be done on behalf of the user by a client bound
 869    as a superior principal, such that password restrictions may be
 870    enforced). For example, if a user were allowed to change the value of
 871    their uidNumber attribute, they could subvert security by
 872    equivalencing their account with the superuser account.
 873
 874    A subtree of the DIT which is to be republished by a DUA (such as a
 875    NIS gateway) SHOULD be within the same administrative domain that the
 876    republishing DUA represents. (For example, principals outside an
 877    organization, while conceivably part of the DIT, should not be
 878    considered with the same degree of authority as those within the
 879    organization.)
 880
 881    Finally, care should be exercised with integer attributes of a
 882    sensitive nature (particularly the uidNumber and gidNumber
 883    attributes) which contain zero-length values. DUAs MAY treat such
 884    values as corresponding to the "nobody" or "nogroup" user and group,
 885    respectively.
 886
 887 8. Acknowledgements
 888
 889    Thanks to Leif Hedstrom of Netscape Communications Corporation,
 890    Michael Grant and Rosanna Lee of Sun Microsystems Inc., Ed Reed of
 891    Novell Inc., and Mark Wahl of Critical Angle Inc. for their valuable
 892    contributions to the development of this schema. Thanks to Andrew
 893    Josey of The Open Group for clarifying the use of the UNIX trademark,
 894    and to Tim Howes and Peter J. Cherny for their support.
 895
 896
 897
 898 Howard                        Experimental                     [Page 16]
 899 \f
 900 RFC 2307      Using LDAP as a Network Information Service     March 1998
 901
 902
 903    UNIX is a registered trademark of The Open Group.
 904
 905 9. References
 906
 907    [RFC1057]
 908         Sun Microsystems, Inc., "RPC: Remote Procedure Call: Protocol
 909         Specification Version 2", RFC 1057, June 1988.
 910
 911    [RFC1279]
 912         Kille, S., "X.500 and Domains", RFC 1279, November 1991.
 913
 914    [RFC1884]
 915         Hinden, R., and S. Deering, "IP Version 6 Addressing
 916         Architecture", RFC 1884, December 1995.
 917
 918    [RFC2119]
 919         Bradner, S., "Key Words for use in RFCs to Indicate Requirement
 920         Levels", BCP 14, RFC 2119, March 1997.
 921
 922    [RFC2251]
 923         Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
 924         Protocol (v3)", RFC 2251, December 1997.
 925
 926    [RFC2252]
 927         Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
 928         Directory Access Protocol (v3): Attribute Syntax Definitions",
 929         RFC 2252, December 1997.
 930
 931    [RFC2254]
 932         Howes, T., "The String Representation of LDAP Search Filters",
 933         RFC 2254, December 1997.
 934
 935    [RFC2256]
 936         Wahl, M., "A Summary of the X.500(96) User Schema for use with
 937         LDAPv3", RFC 2256, December 1997.
 938
 939    [ROSE]
 940         M. T. Rose, "The Little Black Book: Mail Bonding with OSI
 941         Directory Services", ISBN 0-13-683210-5, Prentice-Hall, Inc.,
 942         1992.
 943
 944    [X500]
 945         "Information Processing Systems - Open Systems Interconnection -
 946         The Directory: Overview of Concepts, Models and Service",
 947         ISO/IEC JTC 1/SC21, International Standard 9594-1, 1988.
 948
 949
 950
 951
 952
 953
 954 Howard                        Experimental                     [Page 17]
 955 \f
 956 RFC 2307      Using LDAP as a Network Information Service     March 1998
 957
 958
 959    [XOPEN]
 960         ISO/IEC 9945-1:1990, Information Technology - Portable Operating
 961         Systems Interface (POSIX) - Part 1: Systems Application
 962         Programming Interface (API) [C Language]
 963
 964 10. Author's Address
 965
 966    Luke Howard
 967    PO Box 59
 968    Central Park Vic 3145
 969    Australia
 970
 971    EMail: lukeh@xedoc.com
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010 Howard                        Experimental                     [Page 18]
1011 \f
1012 RFC 2307      Using LDAP as a Network Information Service     March 1998
1013
1014
1015 A. Example entries
1016
1017    The examples described in this section are provided to illustrate the
1018    schema described in this memo. They are not meant to be exhaustive.
1019
1020    The following entry is an example of the posixAccount class:
1021
1022            dn: uid=lester, dc=aja, dc=com
1023            objectClass: top
1024            objectClass: account
1025            objectClass: posixAccount
1026            uid: lester
1027            cn: Lester the Nightfly
1028            userPassword: {crypt}X5/DBrWPOQQaI
1029            gecos: Lester
1030            loginShell: /bin/csh
1031            uidNumber: 10
1032            gidNumber: 10
1033            homeDirectory: /home/lester
1034
1035
1036    This corresponds the UNIX system password file entry:
1037
1038         lester:X5/DBrWPOQQaI:10:10:Lester:/home/lester:/bin/sh
1039
1040    The following entry is an example of the ipHost class:
1041
1042            dn: cn=peg.aja.com, dc=aja, dc=com
1043            objectClass: top
1044            objectClass: device
1045            objectClass: ipHost
1046            objectClass: bootableDevice
1047            objectClass: ieee802Device
1048            cn: peg.aja.com
1049            cn: www.aja.com
1050            ipHostNumber: 10.0.0.1
1051            macAddress: 00:00:92:90:ee:e2
1052            bootFile: mach
1053            bootParameter: root=fs:/nfsroot/peg
1054            bootParameter: swap=fs:/nfsswap/peg
1055            bootParameter: dump=fs:/nfsdump/peg
1056
1057    This entry represents the host canonically peg.aja.com, also known as
1058    www.aja.com. The Ethernet address and four boot parameters are also
1059    specified.
1060
1061
1062
1063
1064
1065
1066 Howard                        Experimental                     [Page 19]
1067 \f
1068 RFC 2307      Using LDAP as a Network Information Service     March 1998
1069
1070
1071    An example of the nisNetgroup class:
1072
1073            dn: cn=nightfly, dc=aja, dc=com
1074            objectClass: top
1075            objectClass: nisNetgroup
1076            cn: nightfly
1077            nisNetgroupTriple: (charlemagne,peg,dunes.aja.com)
1078            nisNetgroupTriple: (lester,-,)
1079            memberNisNetgroup: kamakiriad
1080
1081    This entry represents the netgroup nightfly, which contains two
1082    triples (the user charlemagne, the host peg, and the domain
1083    dunes.aja.com; and, the user lester, no host, and any domain) and one
1084    netgroup (kamakiriad).
1085
1086    Finally, an example of the nisObject class:
1087
1088            dn: nisMapName=tracks, dc=dunes, dc=aja, dc=com
1089            objectClass: top
1090            objectClass: nisMap
1091            nisMapName: tracks
1092
1093            dn: cn=Maxine, nisMapName=tracks, dc=dunes, dc=aja, dc=com
1094            objectClass: top
1095            objectClass: nisObject
1096            cn: Maxine
1097            nisMapName: tracks
1098            nisMapEntry: Nightfly$4
1099
1100    This entry represents the NIS map tracks, and a single map entry.
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122 Howard                        Experimental                     [Page 20]
1123 \f
1124 RFC 2307      Using LDAP as a Network Information Service     March 1998
1125
1126
1127 Full Copyright Statement
1128
1129    Copyright (C) The Internet Society (1998).  All Rights Reserved.
1130
1131    This document and translations of it may be copied and furnished to
1132    others, and derivative works that comment on or otherwise explain it
1133    or assist in its implementation may be prepared, copied, published
1134    and distributed, in whole or in part, without restriction of any
1135    kind, provided that the above copyright notice and this paragraph are
1136    included on all such copies and derivative works.  However, this
1137    document itself may not be modified in any way, such as by removing
1138    the copyright notice or references to the Internet Society or other
1139    Internet organizations, except as needed for the purpose of
1140    developing Internet standards in which case the procedures for
1141    copyrights defined in the Internet Standards process must be
1142    followed, or as required to translate it into languages other than
1143    English.
1144
1145    The limited permissions granted above are perpetual and will not be
1146    revoked by the Internet Society or its successors or assigns.
1147
1148    This document and the information contained herein is provided on an
1149    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1150    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1151    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1152    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1153    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178 Howard                        Experimental                     [Page 21]
1179 \f