1 2 3 4 5 6 7Network Working Group R. Srinivasan 8Request for Comments: 1831 Sun Microsystems 9Category: Standards Track August 1995 10 11 12 RPC: Remote Procedure Call Protocol Specification Version 2 13 14Status of this Memo 15 16 This document specifies an Internet standards track protocol for the 17 Internet community, and requests discussion and suggestions for 18 improvements. Please refer to the current edition of the "Internet 19 Official Protocol Standards" (STD 1) for the standardization state 20 and status of this protocol. Distribution of this memo is unlimited. 21 22ABSTRACT 23 24 This document describes the ONC Remote Procedure Call (ONC RPC 25 Version 2) protocol as it is currently deployed and accepted. "ONC" 26 stands for "Open Network Computing". 27 28TABLE OF CONTENTS 29 30 1. INTRODUCTION 2 31 2. TERMINOLOGY 2 32 3. THE RPC MODEL 2 33 4. TRANSPORTS AND SEMANTICS 4 34 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 35 6. AUTHENTICATION 5 36 7. RPC PROTOCOL REQUIREMENTS 5 37 7.1 RPC Programs and Procedures 6 38 7.2 Authentication 7 39 7.3 Program Number Assignment 8 40 7.4 Other Uses of the RPC Protocol 8 41 7.4.1 Batching 8 42 7.4.2 Broadcast Remote Procedure Calls 8 43 8. THE RPC MESSAGE PROTOCOL 9 44 9. AUTHENTICATION PROTOCOLS 12 45 9.1 Null Authentication 13 46 10. RECORD MARKING STANDARD 13 47 11. THE RPC LANGUAGE 13 48 11.1 An Example Service Described in the RPC Language 13 49 11.2 The RPC Language Specification 14 50 11.3 Syntax Notes 15 51 APPENDIX A: SYSTEM AUTHENTICATION 16 52 REFERENCES 17 53 Security Considerations 18 54 Author's Address 18 55 56 57 58Srinivasan Standards Track [Page 1] 59 60RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 61 62 631. INTRODUCTION 64 65 This document specifies version two of the message protocol used in 66 ONC Remote Procedure Call (RPC). The message protocol is specified 67 with the eXternal Data Representation (XDR) language [9]. This 68 document assumes that the reader is familiar with XDR. It does not 69 attempt to justify remote procedure calls systems or describe their 70 use. The paper by Birrell and Nelson [1] is recommended as an 71 excellent background for the remote procedure call concept. 72 732. TERMINOLOGY 74 75 This document discusses clients, calls, servers, replies, services, 76 programs, procedures, and versions. Each remote procedure call has 77 two sides: an active client side that makes the call to a server, 78 which sends back a reply. A network service is a collection of one 79 or more remote programs. A remote program implements one or more 80 remote procedures; the procedures, their parameters, and results are 81 documented in the specific program's protocol specification. A 82 server may support more than one version of a remote program in order 83 to be compatible with changing protocols. 84 85 For example, a network file service may be composed of two programs. 86 One program may deal with high-level applications such as file system 87 access control and locking. The other may deal with low-level file 88 input and output and have procedures like "read" and "write". A 89 client of the network file service would call the procedures 90 associated with the two programs of the service on behalf of the 91 client. 92 93 The terms client and server only apply to a particular transaction; a 94 particular hardware entity (host) or software entity (process or 95 program) could operate in both roles at different times. For 96 example, a program that supplies remote execution service could also 97 be a client of a network file service. 98 993. THE RPC MODEL 100 101 The ONC RPC protocol is based on the remote procedure call model, 102 which is similar to the local procedure call model. In the local 103 case, the caller places arguments to a procedure in some well- 104 specified location (such as a register window). It then transfers 105 control to the procedure, and eventually regains control. At that 106 point, the results of the procedure are extracted from the well- 107 specified location, and the caller continues execution. 108 109 110 111 112 113 114Srinivasan Standards Track [Page 2] 115 116RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 117 118 119 The remote procedure call model is similar. One thread of control 120 logically winds through two processes: the caller's process, and a 121 server's process. The caller process first sends a call message to 122 the server process and waits (blocks) for a reply message. The call 123 message includes the procedure's parameters, and the reply message 124 includes the procedure's results. Once the reply message is 125 received, the results of the procedure are extracted, and caller's 126 execution is resumed. 127 128 On the server side, a process is dormant awaiting the arrival of a 129 call message. When one arrives, the server process extracts the 130 procedure's parameters, computes the results, sends a reply message, 131 and then awaits the next call message. 132 133 In this model, only one of the two processes is active at any given 134 time. However, this model is only given as an example. The ONC RPC 135 protocol makes no restrictions on the concurrency model implemented, 136 and others are possible. For example, an implementation may choose 137 to have RPC calls be asynchronous, so that the client may do useful 138 work while waiting for the reply from the server. Another 139 possibility is to have the server create a separate task to process 140 an incoming call, so that the original server can be free to receive 141 other requests. 142 143 There are a few important ways in which remote procedure calls differ 144 from local procedure calls: 145 146 1. Error handling: failures of the remote server or network must 147 be handled when using remote procedure calls. 148 149 2. Global variables and side-effects: since the server does not 150 have access to the client's address space, hidden arguments cannot 151 be passed as global variables or returned as side effects. 152 153 3. Performance: remote procedures usually operate one or more 154 orders of magnitude slower than local procedure calls. 155 156 4. Authentication: since remote procedure calls can be transported 157 over unsecured networks, authentication may be necessary. 158 Authentication prevents one entity from masquerading as some other 159 entity. 160 161 The conclusion is that even though there are tools to automatically 162 generate client and server libraries for a given service, protocols 163 must still be designed carefully. 164 165 166 167 168 169 170Srinivasan Standards Track [Page 3] 171 172RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 173 174 1754. TRANSPORTS AND SEMANTICS 176 177 The RPC protocol can be implemented on several different transport 178 protocols. The RPC protocol does not care how a message is passed 179 from one process to another, but only with specification and 180 interpretation of messages. However, the application may wish to 181 obtain information about (and perhaps control over) the transport 182 layer through an interface not specified in this document. For 183 example, the transport protocol may impose a restriction on the 184 maximum size of RPC messages, or it may be stream-oriented like TCP 185 with no size limit. The client and server must agree on their 186 transport protocol choices. 187 188 It is important to point out that RPC does not try to implement any 189 kind of reliability and that the application may need to be aware of 190 the type of transport protocol underneath RPC. If it knows it is 191 running on top of a reliable transport such as TCP [6], then most of 192 the work is already done for it. On the other hand, if it is running 193 on top of an unreliable transport such as UDP [7], it must implement 194 its own time-out, retransmission, and duplicate detection policies as 195 the RPC protocol does not provide these services. 196 197 Because of transport independence, the RPC protocol does not attach 198 specific semantics to the remote procedures or their execution 199 requirements. Semantics can be inferred from (but should be 200 explicitly specified by) the underlying transport protocol. For 201 example, consider RPC running on top of an unreliable transport such 202 as UDP. If an application retransmits RPC call messages after time- 203 outs, and does not receive a reply, it cannot infer anything about 204 the number of times the procedure was executed. If it does receive a 205 reply, then it can infer that the procedure was executed at least 206 once. 207 208 A server may wish to remember previously granted requests from a 209 client and not regrant them in order to insure some degree of 210 execute-at-most-once semantics. A server can do this by taking 211 advantage of the transaction ID that is packaged with every RPC 212 message. The main use of this transaction ID is by the client RPC 213 entity in matching replies to calls. However, a client application 214 may choose to reuse its previous transaction ID when retransmitting a 215 call. The server may choose to remember this ID after executing a 216 call and not execute calls with the same ID in order to achieve some 217 degree of execute-at-most-once semantics. The server is not allowed 218 to examine this ID in any other way except as a test for equality. 219 220 On the other hand, if using a "reliable" transport such as TCP, the 221 application can infer from a reply message that the procedure was 222 executed exactly once, but if it receives no reply message, it cannot 223 224 225 226Srinivasan Standards Track [Page 4] 227 228RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 229 230 231 assume that the remote procedure was not executed. Note that even if 232 a connection-oriented protocol like TCP is used, an application still 233 needs time-outs and reconnection to handle server crashes. 234 235 There are other possibilities for transports besides datagram- or 236 connection-oriented protocols. For example, a request-reply protocol 237 such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC 238 uses both TCP and UDP transport protocols. Section 10 (RECORD 239 MARKING STANDARD) describes the mechanism employed by ONC RPC to 240 utilize a connection-oriented, stream-oriented transport such as TCP. 241 2425. BINDING AND RENDEZVOUS INDEPENDENCE 243 244 The act of binding a particular client to a particular service and 245 transport parameters is NOT part of this RPC protocol specification. 246 This important and necessary function is left up to some higher-level 247 software. 248 249 Implementors could think of the RPC protocol as the jump-subroutine 250 instruction ("JSR") of a network; the loader (binder) makes JSR 251 useful, and the loader itself uses JSR to accomplish its task. 252 Likewise, the binding software makes RPC useful, possibly using RPC 253 to accomplish this task. 254 2556. AUTHENTICATION 256 257 The RPC protocol provides the fields necessary for a client to 258 identify itself to a service, and vice-versa, in each call and reply 259 message. Security and access control mechanisms can be built on top 260 of this message authentication. Several different authentication 261 protocols can be supported. A field in the RPC header indicates 262 which protocol is being used. More information on specific 263 authentication protocols is in section 9: "Authentication Protocols". 264 2657. RPC PROTOCOL REQUIREMENTS 266 267 The RPC protocol must provide for the following: 268 269 (1) Unique specification of a procedure to be called. 270 (2) Provisions for matching response messages to request messages. 271 (3) Provisions for authenticating the caller to service and 272 vice-versa. 273 274 275 276 277 278 279 280 281 282Srinivasan Standards Track [Page 5] 283 284RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 285 286 287 Besides these requirements, features that detect the following are 288 worth supporting because of protocol roll-over errors, implementation 289 bugs, user error, and network administration: 290 291 (1) RPC protocol mismatches. 292 (2) Remote program protocol version mismatches. 293 (3) Protocol errors (such as misspecification of a procedure's 294 parameters). 295 (4) Reasons why remote authentication failed. 296 (5) Any other reasons why the desired procedure was not called. 297 2987.1 RPC Programs and Procedures 299 300 The RPC call message has three unsigned integer fields -- remote 301 program number, remote program version number, and remote procedure 302 number -- which uniquely identify the procedure to be called. 303 Program numbers are administered by a central authority 304 (rpc@sun.com). Once implementors have a program number, they can 305 implement their remote program; the first implementation would most 306 likely have the version number 1. Because most new protocols evolve, 307 a version field of the call message identifies which version of the 308 protocol the caller is using. Version numbers enable support of both 309 old and new protocols through the same server process. 310 311 The procedure number identifies the procedure to be called. These 312 numbers are documented in the specific program's protocol 313 specification. For example, a file service's protocol specification 314 may state that its procedure number 5 is "read" and procedure number 315 12 is "write". 316 317 Just as remote program protocols may change over several versions, 318 the actual RPC message protocol could also change. Therefore, the 319 call message also has in it the RPC version number, which is always 320 equal to two for the version of RPC described here. 321 322 The reply message to a request message has enough information to 323 distinguish the following error conditions: 324 325 (1) The remote implementation of RPC does not support protocol 326 version 2. The lowest and highest supported RPC version numbers 327 are returned. 328 329 (2) The remote program is not available on the remote system. 330 331 (3) The remote program does not support the requested version 332 number. The lowest and highest supported remote program version 333 numbers are returned. 334 335 336 337 338Srinivasan Standards Track [Page 6] 339 340RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 341 342 343 (4) The requested procedure number does not exist. (This is 344 usually a client side protocol or programming error.) 345 346 (5) The parameters to the remote procedure appear to be garbage 347 from the server's point of view. (Again, this is usually caused 348 by a disagreement about the protocol between client and service.) 349 3507.2 Authentication 351 352 Provisions for authentication of caller to service and vice-versa are 353 provided as a part of the RPC protocol. The call message has two 354 authentication fields, the credential and verifier. The reply 355 message has one authentication field, the response verifier. The RPC 356 protocol specification defines all three fields to be the following 357 opaque type (in the eXternal Data Representation (XDR) language [9]): 358 359 enum auth_flavor { 360 AUTH_NONE = 0, 361 AUTH_SYS = 1, 362 AUTH_SHORT = 2 363 /* and more to be defined */ 364 }; 365 366 struct opaque_auth { 367 auth_flavor flavor; 368 opaque body<400>; 369 }; 370 371 In other words, any "opaque_auth" structure is an "auth_flavor" 372 enumeration followed by up to 400 bytes which are opaque to 373 (uninterpreted by) the RPC protocol implementation. 374 375 The interpretation and semantics of the data contained within the 376 authentication fields is specified by individual, independent 377 authentication protocol specifications. (Section 9 defines the 378 various authentication protocols.) 379 380 If authentication parameters were rejected, the reply message 381 contains information stating why they were rejected. 382 383 384 385 386 387 388 389 390 391 392 393 394Srinivasan Standards Track [Page 7] 395 396RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 397 398 3997.3 Program Number Assignment 400 401 Program numbers are given out in groups of hexadecimal 20000000 402 (decimal 536870912) according to the following chart: 403 404 0 - 1fffffff defined by rpc@sun.com 405 20000000 - 3fffffff defined by user 406 40000000 - 5fffffff transient 407 60000000 - 7fffffff reserved 408 80000000 - 9fffffff reserved 409 a0000000 - bfffffff reserved 410 c0000000 - dfffffff reserved 411 e0000000 - ffffffff reserved 412 413 The first group is a range of numbers administered by rpc@sun.com and 414 should be identical for all sites. The second range is for 415 applications peculiar to a particular site. This range is intended 416 primarily for debugging new programs. When a site develops an 417 application that might be of general interest, that application 418 should be given an assigned number in the first range. Application 419 developers may apply for blocks of RPC program numbers in the first 420 range by sending electronic mail to "rpc@sun.com". The third group 421 is for applications that generate program numbers dynamically. The 422 final groups are reserved for future use, and should not be used. 423 4247.4 Other Uses of the RPC Protocol 425 426 The intended use of this protocol is for calling remote procedures. 427 Normally, each call message is matched with a reply message. 428 However, the protocol itself is a message-passing protocol with which 429 other (non-procedure call) protocols can be implemented. 430 4317.4.1 Batching 432 433 Batching is useful when a client wishes to send an arbitrarily large 434 sequence of call messages to a server. Batching typically uses 435 reliable byte stream protocols (like TCP) for its transport. In the 436 case of batching, the client never waits for a reply from the server, 437 and the server does not send replies to batch calls. A sequence of 438 batch calls is usually terminated by a legitimate remote procedure 439 call operation in order to flush the pipeline and get positive 440 acknowledgement. 441 4427.4.2 Broadcast Remote Procedure Calls 443 444 In broadcast protocols, the client sends a broadcast call to the 445 network and waits for numerous replies. This requires the use of 446 packet-based protocols (like UDP) as its transport protocol. Servers 447 448 449 450Srinivasan Standards Track [Page 8] 451 452RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 453 454 455 that support broadcast protocols usually respond only when the call 456 is successfully processed and are silent in the face of errors, but 457 this varies with the application. 458 459 The principles of broadcast RPC also apply to multicasting - an RPC 460 request can be sent to a multicast address. 461 4628. THE RPC MESSAGE PROTOCOL 463 464 This section defines the RPC message protocol in the XDR data 465 description language [9]. 466 467 enum msg_type { 468 CALL = 0, 469 REPLY = 1 470 }; 471 472 A reply to a call message can take on two forms: The message was 473 either accepted or rejected. 474 475 enum reply_stat { 476 MSG_ACCEPTED = 0, 477 MSG_DENIED = 1 478 }; 479 480 Given that a call message was accepted, the following is the status 481 of an attempt to call a remote procedure. 482 483 enum accept_stat { 484 SUCCESS = 0, /* RPC executed successfully */ 485 PROG_UNAVAIL = 1, /* remote hasn't exported program */ 486 PROG_MISMATCH = 2, /* remote can't support version # */ 487 PROC_UNAVAIL = 3, /* program can't support procedure */ 488 GARBAGE_ARGS = 4, /* procedure can't decode params */ 489 SYSTEM_ERR = 5 /* errors like memory allocation failure */ 490 }; 491 492 Reasons why a call message was rejected: 493 494 enum reject_stat { 495 RPC_MISMATCH = 0, /* RPC version number != 2 */ 496 AUTH_ERROR = 1 /* remote can't authenticate caller */ 497 }; 498 499 Why authentication failed: 500 501 enum auth_stat { 502 AUTH_OK = 0, /* success */ 503 504 505 506Srinivasan Standards Track [Page 9] 507 508RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 509 510 511 /* 512 * failed at remote end 513 */ 514 AUTH_BADCRED = 1, /* bad credential (seal broken) */ 515 AUTH_REJECTEDCRED = 2, /* client must begin new session */ 516 AUTH_BADVERF = 3, /* bad verifier (seal broken) */ 517 AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ 518 AUTH_TOOWEAK = 5, /* rejected for security reasons */ 519 /* 520 * failed locally 521 */ 522 AUTH_INVALIDRESP = 6, /* bogus response verifier */ 523 AUTH_FAILED = 7 /* reason unknown */ 524 }; 525 526 The RPC message: 527 528 All messages start with a transaction identifier, xid, followed by a 529 two-armed discriminated union. The union's discriminant is a 530 msg_type which switches to one of the two types of the message. The 531 xid of a REPLY message always matches that of the initiating CALL 532 message. NB: The xid field is only used for clients matching reply 533 messages with call messages or for servers detecting retransmissions; 534 the service side cannot treat this id as any type of sequence number. 535 536 struct rpc_msg { 537 unsigned int xid; 538 union switch (msg_type mtype) { 539 case CALL: 540 call_body cbody; 541 case REPLY: 542 reply_body rbody; 543 } body; 544 }; 545 546 Body of an RPC call: 547 548 In version 2 of the RPC protocol specification, rpcvers must be equal 549 to 2. The fields prog, vers, and proc specify the remote program, 550 its version number, and the procedure within the remote program to be 551 called. After these fields are two authentication parameters: cred 552 (authentication credential) and verf (authentication verifier). The 553 two authentication parameters are followed by the parameters to the 554 remote procedure, which are specified by the specific program 555 protocol. 556 557 The purpose of the authentication verifier is to validate the 558 authentication credential. Note that these two items are 559 560 561 562Srinivasan Standards Track [Page 10] 563 564RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 565 566 567 historically separate, but are always used together as one logical 568 entity. 569 570 struct call_body { 571 unsigned int rpcvers; /* must be equal to two (2) */ 572 unsigned int prog; 573 unsigned int vers; 574 unsigned int proc; 575 opaque_auth cred; 576 opaque_auth verf; 577 /* procedure specific parameters start here */ 578 }; 579 580 Body of a reply to an RPC call: 581 582 union reply_body switch (reply_stat stat) { 583 case MSG_ACCEPTED: 584 accepted_reply areply; 585 case MSG_DENIED: 586 rejected_reply rreply; 587 } reply; 588 589 Reply to an RPC call that was accepted by the server: 590 591 There could be an error even though the call was accepted. The first 592 field is an authentication verifier that the server generates in 593 order to validate itself to the client. It is followed by a union 594 whose discriminant is an enum accept_stat. The SUCCESS arm of the 595 union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, 596 GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The 597 PROG_MISMATCH arm specifies the lowest and highest version numbers of 598 the remote program supported by the server. 599 600 struct accepted_reply { 601 opaque_auth verf; 602 union switch (accept_stat stat) { 603 case SUCCESS: 604 opaque results[0]; 605 /* 606 * procedure-specific results start here 607 */ 608 case PROG_MISMATCH: 609 struct { 610 unsigned int low; 611 unsigned int high; 612 } mismatch_info; 613 default: 614 /* 615 616 617 618Srinivasan Standards Track [Page 11] 619 620RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 621 622 623 * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, 624 * GARBAGE_ARGS, and SYSTEM_ERR. 625 */ 626 void; 627 } reply_data; 628 }; 629 630 Reply to an RPC call that was rejected by the server: 631 632 The call can be rejected for two reasons: either the server is not 633 running a compatible version of the RPC protocol (RPC_MISMATCH), or 634 the server rejects the identity of the caller (AUTH_ERROR). In case 635 of an RPC version mismatch, the server returns the lowest and highest 636 supported RPC version numbers. In case of invalid authentication, 637 failure status is returned. 638 639 union rejected_reply switch (reject_stat stat) { 640 case RPC_MISMATCH: 641 struct { 642 unsigned int low; 643 unsigned int high; 644 } mismatch_info; 645 case AUTH_ERROR: 646 auth_stat stat; 647 }; 648 6499. AUTHENTICATION PROTOCOLS 650 651 As previously stated, authentication parameters are opaque, but 652 open-ended to the rest of the RPC protocol. This section defines two 653 standard "flavors" of authentication. Implementors are free to 654 invent new authentication types, with the same rules of flavor number 655 assignment as there is for program number assignment. The "flavor" 656 of a credential or verifier refers to the value of the "flavor" field 657 in the opaque_auth structure. Flavor numbers, like RPC program 658 numbers, are also administered centrally, and developers may assign 659 new flavor numbers by applying through electronic mail to 660 "rpc@sun.com". Credentials and verifiers are represented as variable 661 length opaque data (the "body" field in the opaque_auth structure). 662 663 In this document, two flavors of authentication are described. Of 664 these, Null authentication (described in the next subsection) is 665 mandatory - it must be available in all implementations. System 666 authentication is described in Appendix A. It is strongly 667 recommended that implementors include System authentication in their 668 implementations. Many applications use this style of authentication, 669 and availability of this flavor in an implementation will enhance 670 interoperability. 671 672 673 674Srinivasan Standards Track [Page 12] 675 676RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 677 678 6799.1 Null Authentication 680 681 Often calls must be made where the client does not care about its 682 identity or the server does not care who the client is. In this 683 case, the flavor of the RPC message's credential, verifier, and reply 684 verifier is "AUTH_NONE". Opaque data associated with "AUTH_NONE" is 685 undefined. It is recommended that the length of the opaque data be 686 zero. 687 68810. RECORD MARKING STANDARD 689 690 When RPC messages are passed on top of a byte stream transport 691 protocol (like TCP), it is necessary to delimit one message from 692 another in order to detect and possibly recover from protocol errors. 693 This is called record marking (RM). One RPC message fits into one RM 694 record. 695 696 A record is composed of one or more record fragments. A record 697 fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of 698 fragment data. The bytes encode an unsigned binary number; as with 699 XDR integers, the byte order is from highest to lowest. The number 700 encodes two values -- a boolean which indicates whether the fragment 701 is the last fragment of the record (bit value 1 implies the fragment 702 is the last fragment) and a 31-bit unsigned binary value which is the 703 length in bytes of the fragment's data. The boolean value is the 704 highest-order bit of the header; the length is the 31 low-order bits. 705 (Note that this record specification is NOT in XDR standard form!) 706 70711. THE RPC LANGUAGE 708 709 Just as there was a need to describe the XDR data-types in a formal 710 language, there is also need to describe the procedures that operate 711 on these XDR data-types in a formal language as well. The RPC 712 Language is an extension to the XDR language, with the addition of 713 "program", "procedure", and "version" declarations. The following 714 example is used to describe the essence of the language. 715 71611.1 An Example Service Described in the RPC Language 717 718 Here is an example of the specification of a simple ping program. 719 720 program PING_PROG { 721 /* 722 * Latest and greatest version 723 */ 724 version PING_VERS_PINGBACK { 725 void 726 PINGPROC_NULL(void) = 0; 727 728 729 730Srinivasan Standards Track [Page 13] 731 732RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 733 734 735 /* 736 * Ping the client, return the round-trip time 737 * (in microseconds). Returns -1 if the operation 738 * timed out. 739 */ 740 int 741 PINGPROC_PINGBACK(void) = 1; 742 } = 2; 743 744 /* 745 * Original version 746 */ 747 version PING_VERS_ORIG { 748 void 749 PINGPROC_NULL(void) = 0; 750 } = 1; 751 } = 1; 752 753 const PING_VERS = 2; /* latest version */ 754 755 The first version described is PING_VERS_PINGBACK with two 756 procedures, PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes 757 no arguments and returns no results, but it is useful for computing 758 round-trip times from the client to the server and back again. By 759 convention, procedure 0 of any RPC protocol should have the same 760 semantics, and never require any kind of authentication. The second 761 procedure is used for the client to have the server do a reverse ping 762 operation back to the client, and it returns the amount of time (in 763 microseconds) that the operation used. The next version, 764 PING_VERS_ORIG, is the original version of the protocol and it does 765 not contain PINGPROC_PINGBACK procedure. It is useful for 766 compatibility with old client programs, and as this program matures 767 it may be dropped from the protocol entirely. 768 76911.2 The RPC Language Specification 770 771 The RPC language is identical to the XDR language defined in RFC 772 1014, except for the added definition of a "program-def" described 773 below. 774 775 program-def: 776 "program" identifier "{" 777 version-def 778 version-def * 779 "}" "=" constant ";" 780 781 version-def: 782 "version" identifier "{" 783 784 785 786Srinivasan Standards Track [Page 14] 787 788RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 789 790 791 procedure-def 792 procedure-def * 793 "}" "=" constant ";" 794 795 procedure-def: 796 type-specifier identifier "(" type-specifier 797 ("," type-specifier )* ")" "=" constant ";" 798 79911.3 Syntax Notes 800 801 (1) The following keywords are added and cannot be used as 802 identifiers: "program" and "version"; 803 804 (2) A version name cannot occur more than once within the scope of a 805 program definition. Nor can a version number occur more than once 806 within the scope of a program definition. 807 808 (3) A procedure name cannot occur more than once within the scope of 809 a version definition. Nor can a procedure number occur more than once 810 within the scope of version definition. 811 812 (4) Program identifiers are in the same name space as constant and 813 type identifiers. 814 815 (5) Only unsigned constants can be assigned to programs, versions and 816 procedures. 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842Srinivasan Standards Track [Page 15] 843 844RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 845 846 847APPENDIX A: SYSTEM AUTHENTICATION 848 849 The client may wish to identify itself, for example, as it is 850 identified on a UNIX(tm) system. The flavor of the client credential 851 is "AUTH_SYS". The opaque data constituting the credential encodes 852 the following structure: 853 854 struct authsys_parms { 855 unsigned int stamp; 856 string machinename<255>; 857 unsigned int uid; 858 unsigned int gid; 859 unsigned int gids<16>; 860 }; 861 862 The "stamp" is an arbitrary ID which the caller machine may generate. 863 The "machinename" is the name of the caller's machine (like 864 "krypton"). The "uid" is the caller's effective user ID. The "gid" 865 is the caller's effective group ID. The "gids" is a counted array of 866 groups which contain the caller as a member. The verifier 867 accompanying the credential should have "AUTH_NONE" flavor value 868 (defined above). Note this credential is only unique within a 869 particular domain of machine names, uids, and gids. 870 871 The flavor value of the verifier received in the reply message from 872 the server may be "AUTH_NONE" or "AUTH_SHORT". In the case of 873 "AUTH_SHORT", the bytes of the reply verifier's string encode an 874 opaque structure. This new opaque structure may now be passed to the 875 server instead of the original "AUTH_SYS" flavor credential. The 876 server may keep a cache which maps shorthand opaque structures 877 (passed back by way of an "AUTH_SHORT" style reply verifier) to the 878 original credentials of the caller. The caller can save network 879 bandwidth and server cpu cycles by using the shorthand credential. 880 881 The server may flush the shorthand opaque structure at any time. If 882 this happens, the remote procedure call message will be rejected due 883 to an authentication error. The reason for the failure will be 884 "AUTH_REJECTEDCRED". At this point, the client may wish to try the 885 original "AUTH_SYS" style of credential. 886 887 It should be noted that use of this flavor of authentication does not 888 guarantee any security for the users or providers of a service, in 889 itself. The authentication provided by this scheme can be considered 890 legitimate only when applications using this scheme and the network 891 can be secured externally, and privileged transport addresses are 892 used for the communicating end-points (an example of this is the use 893 of privileged TCP/UDP ports in Unix systems - note that not all 894 systems enforce privileged transport address mechanisms). 895 896 897 898Srinivasan Standards Track [Page 16] 899 900RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 901 902 903REFERENCES 904 905 [1] Birrell, A. D. & Nelson, B. J., "Implementing Remote Procedure 906 Calls", XEROX CSL-83-7, October 1983. 907 908 [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol", 909 Preliminary Version 0.3, Stanford University, January 1987. 910 911 [3] Diffie & Hellman, "New Directions in Cryptography", IEEE 912 Transactions on Information Theory IT-22, November 1976. 913 914 [4] Mills, D., "Network Time Protocol", RFC 1305, UDEL, 915 March 1992. 916 917 [5] National Bureau of Standards, "Data Encryption Standard", 918 Federal Information Processing Standards Publication 46, January 919 1977. 920 921 [6] Postel, J., "Transmission Control Protocol - DARPA Internet 922 Program Protocol Specification", STD 7, RFC 793, USC/Information 923 Sciences Institute, September 1981. 924 925 [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 926 USC/Information Sciences Institute, August 1980. 927 928 [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, 929 RFC 1700, USC/Information Sciences Institute, October 1994. 930 931 [9] Srinivasan, R., "XDR: External Data Representation Standard", 932 RFC 1832, Sun Microsystems, Inc., August 1995. 933 934 [10] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section 935 E.2.1: Kerberos Authentication and Authorization System", 936 M.I.T. Project Athena, Cambridge, Massachusetts, December 21, 937 1987. 938 939 [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An 940 Authentication Service for Open Network Systems", pp. 191-202 in 941 Usenix Conference Proceedings, Dallas, Texas, February 1988. 942 943 [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication 944 Service (V5)", RFC 1510, Digital Equipment Corporation, 945 USC/Information Sciences Institute, September 1993. 946 947 948 949 950 951 952 953 954Srinivasan Standards Track [Page 17] 955 956RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 957 958 959Security Considerations 960 961 Security issues are not discussed in this memo. 962 963Author's Address 964 965 Raj Srinivasan 966 Sun Microsystems, Inc. 967 ONC Technologies 968 2550 Garcia Avenue 969 M/S MTV-5-40 970 Mountain View, CA 94043 971 USA 972 973 Phone: 415-336-2478 974 Fax: 415-336-6015 975 EMail: raj@eng.sun.com 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 1010Srinivasan Standards Track [Page 18] 1011 1012