idnits 2.17.1 draft-ietf-oncrpc-rpcbind-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 16 longer pages, the longest (page 2) being 65 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 109 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 252 has weird spacing: '...ned int r_n...' == Line 312 has weird spacing: '...ist_ptr rmti...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '4' is defined on line 741, but no explicit reference was found in the text -- Unexpected draft version: The latest known version of draft-ietf-oncrpc-rpcv2 is -01, but you're referring to -02. -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' Summary: 9 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Stephen X. Nahm 3 June 16, 1996 Sun Microsystems 5 Binding Protocols for ONC RPC Version 2 7 draft-ietf-oncrpc-rpcbind-00.txt 9 ABSTRACT 11 This document describes the binding protocols used in conjunction with the 12 ONC Remote Procedure Call (ONC RPC Version 2) protocols. 14 STATUS OF THIS MEMO 16 This document is an Internet-Draft. Internet-Drafts are working documents 17 of the Internet Engineering Task Force (IETF), its areas, and its working 18 groups. Note that other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months. 22 This Internet-Draft expires on December 16, 1996. Internet-Drafts may be 23 updated, replaced, or obsoleted by other documents at any time. It is not 24 appropriate to use Internet-Drafts as reference material or to cite them 25 other than as "work in progress." 27 To learn the current status of any Internet-Draft, please check the 28 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 29 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au 30 (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). 32 Distribution of this memo is unlimited. 34 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 36 CONTENTS 38 1. Introduction 39 2. RPCBIND Program Protocol 40 2.1 RPCBIND Protocol Specification (in RPC Language) 41 2.2 RPCBIND Operation 42 2.2.1 RPCBIND Version 3 43 2.2.2 RPCBIND, Version 4 44 3. Port Mapper Program Protocol 45 3.1 Port Mapper Protocol Specification (in RPC Language) 46 3.2 Port Mapper Operation 47 4. Security Considerations 48 5. References 49 6. AUTHOR'S ADDRESS 50 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 52 1. Introduction 54 This document specifies the binding protocols used in conjunction with ONC 55 RPC Version 2. As a prerequisite, the reader is expected to be familiar 56 with [1] and [2] which describe the ONC RPC Version 2 and XDR (External 57 Data Representation) protocols. 59 An RPC service is identified by its RPC program number, version number, and 60 the transport address where it may be reached. The transport address, in 61 turn, consists of a network address and a transport selector. In the case 62 of a service available over TCP/IP or UDP/IP, the network address will be 63 an IP address, and the transport selector will be a TCP or UDP port number. 65 A client program needs to know the RPC program number, version number, and 66 the transport address corresponding to a service in order to utilize the 67 service. Of these, the RPC program number and version number are usually 68 built into the client program, as part of the service definition. The 69 network address component of the transport address is usually available in 70 a name service, or is given as a parameter to the client program. The 71 transport selector (ie., the TCP or UDP port) is usually determined 72 dynamically, and varies with each invocation of the service. Server 73 programs allocate a transport address, and register it with a well-known 74 lookup service (well-known because it uses a fixed transport selector, and 75 resides at the same network address as the server). Client programs 76 consult the lookup service in order to obtain the server's transport 77 address. 79 Such a lookup service is very desirable because the range of well-known 80 transport selectors is very small for some transports and the number of 81 services is potentially very large. By running only the lookup service on 82 a well-known transport selector, the transport addresses of other remote 83 programs can be ascertained by querying the lookup service. 85 This document describes three versions of a lookup service, all of which 86 use the same RPC program number (100000, decimal). They all use port 111 87 over TCP and UDP transports. Versions 3 and 4 are described in Section 2 88 ("RPCBIND Program Protocol"). Version 2 is described in Section 3 ("Port 89 Mapper Program Protocol"). 91 The distinguishing characteristic of RPCBIND (versions 3 and 4) is that 92 this protocol uses a transport-independent format for the transport 93 address, known as the universal address format. An address in universal 94 address format is an ASCII string representation of the transport dependent 95 address. For example, the universal address format for a TCP/IP transport 96 address is the dotted-decimal representation [3] of the address extended 97 with the port number. If the IP address is "192.0.0.1" and the port number 98 is "111", then the universal address is "192.0.0.1.0.111". 100 String representation of addresses corresponding to a transport are defined 101 by the addressing authority for the transport. The RPCBIND protocol can be 102 used for binding ONC RPC clients and servers over any transport. 104 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 106 The Port Mapper (version 2), on the other hand, is an older protocol that 107 is specific to TCP and UDP. It handles TCP and UDP ports directly. 109 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 111 2. RPCBIND Program Protocol 113 The RPCBIND program maps RPC program and version numbers to universal 114 addresses, thus making dynamic binding of remote programs possible. 116 The RPCBIND program is bound to a well-known address of each supported 117 transport, and other programs register their dynamically allocated 118 transport address with it. The RPCBIND program then makes those addresses 119 publicly available. 121 The RPCBIND program also aids in broadcast RPC. A given RPC program will 122 usually have different transport address bindings on different machines, so 123 there is no way to directly broadcast to all of these programs. The RPCBIND 124 program, however, does have a well-known address. So, to broadcast to a 125 given program, the client actually sends its message to the RPCBIND program 126 located at the broadcast address. Each instance of the RPCBIND program that 127 picks up the broadcast then calls the local service specified by the 128 client. When the RPCBIND program gets the reply from the local service, it 129 sends the reply back to the client. 131 2.1 RPCBIND Protocol Specification (in RPC Language) 133 /* 134 * rpcb_prot.x 135 * rpcbind protocol, versions 3 and 4, in RPC Language 136 */ 138 /* 139 * rpcbind address for TCP/UDP 140 */ 141 const RPCB_PORT = 111; 143 /* 144 * A mapping of (program, version, network ID) to address 145 * 146 * The network identifier (r_netid): 147 * This is a string that represents a local identification for a network. 148 * This is defined by a system administrator based on local conventions, 149 * and cannot be depended on to have the same value on every system. 150 * The RPC program owner identifier (r_owner): 151 * This is a string that represents a user who "owns" the RPC program 152 * represented by the rpcb structure. This is usually the user who started 153 * the server that supplies this RPC program. rpcbind allows only the 154 * program owner to unregister the RPC program (some implementations also 155 * allow the user represented by the string "superuser" to unregister any 156 * RPC program). 157 */ 158 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 160 struct rpcb { 161 unsigned int r_prog; /* program number */ 162 unsigned int r_vers; /* version number */ 163 string r_netid<>; /* network id */ 164 string r_addr<>; /* universal address */ 165 string r_owner<>; /* owner of this service */ 166 }; 168 struct rpcblist { 169 rpcb rpcb_map; 170 struct rpcblist *rpcb_next; 171 }; 173 typedef rpcblist *rpcblist_ptr; /* results of RPCBPROC_DUMP */ 175 /* 176 * Arguments of remote calls 177 */ 178 struct rpcb_rmtcallargs { 179 unsigned int prog; /* program number */ 180 unsigned int vers; /* version number */ 181 unsigned int proc; /* procedure number */ 182 opaque args<>; /* argument */ 183 }; 185 /* 186 * Results of the remote call 187 */ 188 struct rpcb_rmtcallres { 189 string addr<>; /* remote universal address */ 190 opaque results<>; /* result */ 191 }; 193 /* 194 * rpcb_entry contains a merged address of a service on a particular 195 * transport, plus associated netconfig information. A list of rpcb_entry 196 * items is returned by RPCBPROC_GETADDRLIST. The meanings and values used 197 * for the r_nc_* fields are given below. 198 * 199 * The network identifier (r_nc_netid): 200 * This is a string that represents a local identification for a network. 201 * This is defined by a system administrator based on local conventions, 202 * and cannot be depended on to have the same value on every system. 203 * 204 * Transport semantics (r_nc_semantics): 205 * This represents the type of transport, and has the following values: 206 * NC_TPI_CLTS (1) Connectionless 207 * NC_TPI_COTS (2) Connection oriented 208 * NC_TPI_COTS_ORD (3) Connection oriented with graceful close 209 * NC_TPI_RAW (4) Raw transport 210 * 211 * Protocol family (r_nc_protofmly): 212 * This identifies the family to which the protocol belongs. The 213 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 215 * following values are defined: 216 * NC_NOPROTOFMLY "-" 217 * NC_LOOPBACK "loopback" 218 * NC_INET "inet" 219 * NC_IMPLINK "implink" 220 * NC_PUP "pup" 221 * NC_CHAOS "chaos" 222 * NC_NS "ns" 223 * NC_NBS "nbs" 224 * NC_ECMA "ecma" 225 * NC_DATAKIT "datakit" 226 * NC_CCITT "ccitt" 227 * NC_SNA "sna" 228 * NC_DECNET "decnet" 229 * NC_DLI "dli" 230 * NC_LAT "lat" 231 * NC_HYLINK "hylink" 232 * NC_APPLETALK "appletalk" 233 * NC_NIT "nit" 234 * NC_IEEE802 "ieee802" 235 * NC_OSI "osi" 236 * NC_X25 "x25" 237 * NC_OSINET "osinet" 238 * NC_GOSIP "gosip" 239 * 240 * Protocol name (r_nc_proto): 241 * This identifies a protocol within a family. The following are 242 * currently defined: 243 * NC_NOPROTO "-" 244 * NC_TCP "tcp" 245 * NC_UDP "udp" 246 * NC_ICMP "icmp" 247 */ 249 struct rpcb_entry { 250 string r_maddr<>; /* merged address of service */ 251 string r_nc_netid<>; /* netid field */ 252 unsigned int r_nc_semantics; /* semantics of transport */ 253 string r_nc_protofmly<>; /* protocol family */ 254 string r_nc_proto<>; /* protocol name */ 255 }; 257 /* 258 * A list of addresses supported by a service. 259 */ 260 struct rpcb_entry_list { 261 rpcb_entry rpcb_entry_map; 262 struct rpcb_entry_list *rpcb_entry_next; 263 }; 265 typedef rpcb_entry_list *rpcb_entry_list_ptr; 266 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 268 /* 269 * rpcbind statistics 270 */ 271 const rpcb_highproc_2 = RPCBPROC_CALLIT; 272 const rpcb_highproc_3 = RPCBPROC_TADDR2UADDR; 273 const rpcb_highproc_4 = RPCBPROC_GETSTAT; 275 const RPCBSTAT_HIGHPROC = 13; /* # of procs in rpcbind V4 plus one */ 276 const RPCBVERS_STAT = 3; /* provide only for rpcbind V2, V3 and V4 */ 277 const RPCBVERS_4_STAT = 2; 278 const RPCBVERS_3_STAT = 1; 279 const RPCBVERS_2_STAT = 0; 281 /* Link list of all the stats about getport and getaddr */ 282 struct rpcbs_addrlist { 283 unsigned int prog; 284 unsigned int vers; 285 int success; 286 int failure; 287 string netid<>; 288 struct rpcbs_addrlist *next; 289 }; 291 /* Link list of all the stats about rmtcall */ 292 struct rpcbs_rmtcalllist { 293 unsigned int prog; 294 unsigned int vers; 295 unsigned int proc; 296 int success; 297 int failure; 298 int indirect; /* whether callit or indirect */ 299 string netid<>; 300 struct rpcbs_rmtcalllist *next; 301 }; 303 typedef int rpcbs_proc[RPCBSTAT_HIGHPROC]; 304 typedef rpcbs_addrlist *rpcbs_addrlist_ptr; 305 typedef rpcbs_rmtcalllist *rpcbs_rmtcalllist_ptr; 307 struct rpcb_stat { 308 rpcbs_proc info; 309 int setinfo; 310 int unsetinfo; 311 rpcbs_addrlist_ptr addrinfo; 312 rpcbs_rmtcalllist_ptr rmtinfo; 313 }; 315 /* 316 * One rpcb_stat structure is returned for each version of rpcbind 317 * being monitored. 318 */ 320 typedef rpcb_stat rpcb_stat_byvers[RPCBVERS_STAT]; 321 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 323 /* 324 * netbuf structure, used to store the transport specific form of 325 * a universal transport address. 326 */ 327 struct netbuf { 328 unsigned int maxlen; 329 opaque buf<>; 330 }; 332 /* 333 * rpcbind procedures 334 */ 335 program RPCBPROG { 336 version RPCBVERS { 337 bool 338 RPCBPROC_SET(rpcb) = 1; 340 bool 341 RPCBPROC_UNSET(rpcb) = 2; 343 string 344 RPCBPROC_GETADDR(rpcb) = 3; 346 rpcblist_ptr 347 RPCBPROC_DUMP(void) = 4; 349 rpcb_rmtcallres 350 RPCBPROC_CALLIT(rpcb_rmtcallargs) = 5; 352 unsigned int 353 RPCBPROC_GETTIME(void) = 6; 355 netbuf 356 RPCBPROC_UADDR2TADDR(string) = 7; 358 string 359 RPCBPROC_TADDR2UADDR(netbuf) = 8; 360 } = 3; 362 version RPCBVERS4 { 363 bool 364 RPCBPROC_SET(rpcb) = 1; 366 bool 367 RPCBPROC_UNSET(rpcb) = 2; 369 string 370 RPCBPROC_GETADDR(rpcb) = 3; 372 rpcblist_ptr 373 RPCBPROC_DUMP(void) = 4; 374 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 376 /* 377 * NOTE: RPCBPROC_BCAST has the same functionality as CALLIT; 378 * the new name is intended to indicate that this 379 * procedure should be used for broadcast RPC, and 380 * RPCBPROC_INDIRECT should be used for indirect calls. 381 */ 382 rpcb_rmtcallres 383 RPCBPROC_BCAST(rpcb_rmtcallargs) = RPCBPROC_CALLIT; 385 unsigned int 386 RPCBPROC_GETTIME(void) = 6; 388 netbuf 389 RPCBPROC_UADDR2TADDR(string) = 7; 391 string 392 RPCBPROC_TADDR2UADDR(netbuf) = 8; 394 string 395 RPCBPROC_GETVERSADDR(rpcb) = 9; 397 rpcb_rmtcallres 398 RPCBPROC_INDIRECT(rpcb_rmtcallargs) = 10; 400 rpcb_entry_list_ptr 401 RPCBPROC_GETADDRLIST(rpcb) = 11; 403 rpcb_stat_byvers 404 RPCBPROC_GETSTAT(void) = 12; 405 } = 4; 406 } = 100000; 408 2.2 RPCBIND Operation 410 RPCBIND is contacted by way of an assigned address specific to the 411 transport being used. For TCP/IP and UDP/IP, for example, it is port 412 number 111. Each transport has such an assigned, well-known address. The 413 following is a description of each of the procedures supported by RPCBIND. 415 2.2.1 RPCBIND Version 3 417 RPCBPROC_SET: 419 When a program first becomes available on a machine, it registers itself 420 with RPCBIND running on the same machine. The program passes its program 421 number "r_prog", version number "r_vers", network identifier "r_netid", 422 universal address "r_addr", and the owner of the service "r_owner". The 423 procedure returns a boolean response whose value is TRUE if the procedure 424 successfully established the mapping and FALSE otherwise. The procedure 425 refuses to establish a mapping if one already exists for the ordered set 426 ("r_prog", "r_vers", "r_netid"). Note that neither "r_netid" nor "r_addr" 427 can be NULL, and that "r_netid" should be a valid network identifier on the 428 machine making the call. 430 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 432 RPCBPROC_UNSET: 434 When a program becomes unavailable, it should unregister itself with the 435 RPCBIND program on the same machine. The parameters and results have 436 meanings identical to those of RPCBPROC_SET. The mapping of the ("r_prog", 437 "r_vers", "r_netid") tuple with "r_addr" is deleted. If "r_netid" is NULL, 438 all mappings specified by the ordered set ("r_prog", "r_vers", *) and the 439 corresponding universal addresses are deleted. Only the owner of the 440 service or the super-user is allowed to unset a service. 442 RPCBPROC_GETADDR: 444 Given a program number "r_prog", version number "r_vers", and network 445 identifier "r_netid", this procedure returns the universal address on 446 which the program is awaiting call requests. The "r_netid" field of the 447 argument is ignored and the "r_netid" is inferred from the network 448 identifier of the transport on which the request came in. 450 RPCBPROC_DUMP: 452 This procedure lists all entries in RPCBIND's database. The procedure 453 takes no parameters and returns a list of program, version, network 454 identifier, and universal addresses. 456 RPCBPROC_CALLIT: 458 This procedure allows a caller to call another remote procedure on the same 459 machine without knowing the remote procedure's universal address. It is 460 intended for supporting broadcasts to arbitrary remote programs via 461 RPCBIND's universal address. The parameters "prog", "vers", "proc", and 462 args are the program number, version number, procedure number, and 463 parameters of the remote procedure. 465 Note - This procedure only sends a response if the procedure was 466 successfully executed and is silent (no response) otherwise. 468 The procedure returns the remote program's universal address, and the 469 results of the remote procedure. 471 RPCBPROC_GETTIME: 473 This procedure returns the local time on its own machine in seconds since 474 the midnight of the First day of January, 1970. 476 RPCBPROC_UADDR2TADDR: 478 This procedure converts universal addresses to transport specific 479 addresses. 481 RPCBPROC_TADDR2UADDR: 483 This procedure converts transport specific addresses to universal 484 addresses. 486 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 488 2.2.2 RPCBIND, Version 4 490 Version 4 of the RPCBIND protocol includes all of the above procedures, and 491 adds several additional ones. 493 RPCBPROC_BCAST: 495 This procedure is identical to the version 3 RPCBPROC_CALLIT procedure. 496 The new name indicates that the procedure should be used for broadcast RPCs 497 only. RPCBPROC_INDIRECT, defined below, should be used for indirect RPC 498 calls. 500 RPCBPROC_GETVERSADDR: 502 This procedure is similar to RPCBPROC_GETADDR. The difference is the 503 "r_vers" field of the rpcb structure can be used to specify the version of 504 interest. If that version is not registered, no address is returned. 506 RPCBPROC_INDIRECT: 508 Similar to RPCBPROC_CALLIT. Instead of being silent about errors (such as 509 the program not being registered on the system), this procedure returns an 510 indication of the error. This procedure should not be used for broadcast 511 RPC. It is intended to be used with indirect RPC calls only. 513 RPCBPROC_GETADDRLIST: 515 This procedure returns a list of addresses for the given rpcb entry. The 516 client may be able use the results to determine alternate transports that 517 it can use to communicate with the server. 519 RPCBPROC_GETSTAT: 521 This procedure returns statistics on the activity of the RPCBIND server. 522 The information lists the number and kind of requests the server has 523 received. 525 Note - All procedures except RPCBPROC_SET and RPCBPROC_UNSET can be called 526 by clients running on a machine other than a machine on which RPCBIND is 527 running. RPCBIND only accepts RPCBPROC_SET and RPCBPROC_UNSET requests by 528 clients running on the same machine as the RPCBIND program. 530 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 532 3. Port Mapper Program Protocol 534 The port mapper program maps RPC program and version numbers to transport- 535 specific port numbers. This program makes dynamic binding of remote 536 programs possible. The port mapper protocol differs from the newer RPCBIND 537 protocols in that it is transport specific in its address handling. 539 3.1 Port Mapper Protocol Specification (in RPC Language) 541 const PMAP_PORT = 111; /* portmapper port number */ 543 /* 544 * A mapping of (program, version, protocol) to port number: 545 */ 546 struct pmap { 547 unsigned int pm_prog; 548 unsigned int pm_vers; 549 unsigned int pm_prot; 550 unsigned int pm_port; 551 }; 553 /* 554 * Supported values for the "pm_prot" field: 555 */ 556 const PMAP_IPPROTO_TCP = 6; /* protocol number for TCP/IP */ 557 const PMAP_IPPROTO_UDP = 17; /* protocol number for UDP/IP */ 559 /* 560 * A list of mappings: 561 */ 562 struct pmaplist { 563 pmap pml_map; 564 pmaplist *pml_next; 565 }; 566 typedef pmaplist *pmaplist_ptr; 568 /* 569 * Arguments to callit: 570 */ 571 struct rmtcallargs { 572 unsigned int prog; 573 unsigned int vers; 574 unsigned int proc; 575 opaque args<>; 576 }; 578 /* 579 * Results of callit: 580 */ 581 struct rmtcallres { 582 unsigned int port; 583 opaque res<>; 584 }; 585 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 587 /* 588 * Port mapper procedures: 589 */ 590 program PMAP_PROG { 591 version PMAP_VERS { 592 void 593 PMAPPROC_NULL(void) = 0; 595 bool 596 PMAPPROC_SET(pmap) = 1; 598 bool 599 PMAPPROC_UNSET(pmap) = 2; 601 unsigned int 602 PMAPPROC_GETPORT(pmap) = 3; 604 pmaplist_ptr 605 PMAPPROC_DUMP(void) = 4; 607 rmtcallres 608 PMAPPROC_CALLIT(rmtcallargs)= 5; 609 } = 2; 610 } = 100000; 612 3.2 Port Mapper Operation 614 The portmapper program currently supports two protocols (UDP and TCP). The 615 portmapper is contacted by talking to it on assigned port number 111 616 (ONCRPC) on either of these protocols. 618 The following is a description of each of the portmapper procedures: 620 PMAPPROC_NULL: 622 This procedure does no work. By convention, procedure zero of any protocol 623 takes no parameters and returns no results. 625 PMAPPROC_SET: 627 When a program first becomes available on a machine, it registers itself 628 with the port mapper program on the same machine. The program passes its 629 program number "pm_prog", version number "pm_vers", transport protocol 630 number "pm_prot", and the port "pm_port" on which it awaits service 631 request. The procedure returns a boolean reply whose value is "TRUE" if 632 the procedure successfully established the mapping and "FALSE" otherwise. 633 The procedure refuses to establish a mapping if one already exists for the 634 tuple "(pm_prog, pm_vers, pm_prot)". 636 PMAPPROC_UNSET: 638 When a program becomes unavailable, it should unregister itself with the 639 port mapper program on the same machine. The parameters and results have 640 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 642 meanings identical to those of "PMAPPROC_SET". The protocol and port 643 number fields of the argument are ignored. 645 PMAPPROC_GETPORT: 647 Given a program number "pm_prog", version number "pm_vers", and transport 648 protocol number "pm_prot", this procedure returns the port number on which 649 the program is awaiting call requests. A port value of zeros means the 650 program has not been registered. The "pm_port" field of the argument is 651 ignored. 653 PMAPPROC_DUMP: 655 This procedure enumerates all entries in the port mapper's database. The 656 procedure takes no parameters and returns a list of program, version, 657 protocol, and port values. 659 PMAPPROC_CALLIT: 661 This procedure allows a client to call another remote procedure on the same 662 machine without knowing the remote procedure's port number. It is intended 663 for supporting broadcasts to arbitrary remote programs via the well-known 664 port mapper's port. The parameters "prog", "vers", "proc", and the bytes 665 of "args" are the program number, version number, procedure number, and 666 parameters of the remote procedure. Note: 668 (1) This procedure only sends a reply if the procedure was successfully 669 executed and is silent (no reply) otherwise. 671 (2) The port mapper communicates with the remote program using UDP only. 673 The procedure returns the remote program's port number, and the reply is 674 the reply of the remote procedure. 676 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 678 4. Security Considerations 680 Additional information about vulnerabilities of certain implementations of 681 the rpcbind and Port Mapper protocols can be found in "Firewalls and 682 Internet Security"[4]. 684 4.1 Address Registration and Unregistration 686 The rpcbind protocol specifies that the RPCBPROC_SET and RPCBPROC_UNSET 687 procedures only be accepted from the same machine on which rpcbind is 688 running. The intention is that only the local owner of the service be 689 allowed to unset the registration for the RPC program. Some 690 implementations extend this requirement by only allowing RPCBPROC_SET and 691 RPCBPROC_UNSET procedures to be invoked over a secure machine-local 692 transport through which the identity of the owner can be directly verified 693 by rpcbind. 695 The Port Mapper protocol does not specify that the PMAPPROC_SET and 696 PMAPPROC_UNSET procedures are only accepted from the local machine, and 697 many early implementions of the port mapper service accepted these requests 698 from any machine on the network. As a result, any user would be able to 699 unregister an RPC program on such systems, and register potentially 700 spurious information about the service in its place. 702 Systems supporting the Port Mapper protocol are encouraged to restrict 703 registration and unregistration requests to the local system. 704 Implementations should be careful to also disallow portmapper requests 705 which are made through the PMAPPROC_CALLIT procedure, as these operations 706 will appear to originate from the local system. 708 Where possible, portmapper implementation should further restrict 709 PMAPPROC_SET and PMAPPROC_UNSET operations to a secure machine-local 710 transport, as described above for rpcbind. Although the Port Mapper 711 protocol does not include an "owner" field in the PMAPPROC_SET and 712 PMAPPROC_UNSET arguments, an implementation using such a secure machine- 713 local transport which conveys the caller's identity can record this 714 identity in its internal registration records, and allow only the same user 715 to unregister the service. 717 4.2 RPCBPROC_CALLIT, RPCBPROC_INDIRECT, and PMAPPROC_CALLIT 719 The procedures listed in this section's header implement two types of 720 special RPC operations: Broadcast RPC and Indirect RPC. Both use rpcbind 721 or the portmapper to forward a request from a remote caller to an RPC 722 program on the local system. As a result, the request appears to originate 723 from the local system. RPC programs that provide sensitive services should 724 examine the address of the caller to determine whether the request 725 originated from rpcbind or portmapper, in which case the request should be 726 handled as though it came from a remote system. 728 INTERNET-DRAFT Binding Protocols for ONC RPC Version 2 16-June-96 730 5. References 732 [1] "Remote Procedure Call Protocol Version 2", 733 draft-ietf-oncrpc-rpcv2-02.txt, 1996. 735 [2] "XDR: External Data Representation Standard", 736 draft-ietf-oncrpc-xdr-01.txt, 1994. 738 [3] "Requirements for Internet Hosts -- Application and Support", STD-3, 739 October 1989. 741 [4] Cheswick, W.R., and Bellovin, S.M., "Firewalls and Internet Security," 742 Addison-Wesley, 1994. 744 6. AUTHOR'S ADDRESS 746 Stephen X. Nahm 747 Sun Microsystems, Inc. 748 2550 Garcia Avenue 749 Mountain View, CA 94043 751 Phone: +1 (415) 786-5086 753 E-mail: sxn@sun.com