/share/doc/psd/26.rpcrfc/rpc.rfc.ms
Unknown | 1304 lines | 1279 code | 25 blank | 0 comment | 0 complexity | 13190eaea4c2ba839877b6769d8a75a4 MD5 | raw file
1.\" 2.\" Must use -- tbl -- with this one 3.\" 4.\" @(#)rpc.rfc.ms 2.2 88/08/05 4.0 RPCSRC 5.\" $FreeBSD$ 6.\" 7.de BT 8.if \\n%=1 .tl ''- % -'' 9.. 10.ND 11.\" prevent excess underlining in nroff 12.if n .fp 2 R 13.OH 'Remote Procedure Calls: Protocol Specification''Page %' 14.EH 'Page %''Remote Procedure Calls: Protocol Specification' 15.if \n%=1 .bp 16.SH 17\&Remote Procedure Calls: Protocol Specification 18.LP 19.NH 0 20\&Status of this Memo 21.LP 22Note: This chapter specifies a protocol that Sun Microsystems, Inc., 23and others are using. 24It has been designated RFC1050 by the ARPA Network 25Information Center. 26.LP 27.NH 1 28\&Introduction 29.LP 30This chapter specifies a message protocol used in implementing 31Sun's Remote Procedure Call (RPC) package. (The message protocol is 32specified with the External Data Representation (XDR) language. 33See the 34.I "External Data Representation Standard: Protocol Specification" 35for the details. Here, we assume that the reader is familiar 36with XDR and do not attempt to justify it or its uses). The paper 37by Birrell and Nelson [1] is recommended as an excellent background 38to and justification of RPC. 39.NH 2 40\&Terminology 41.LP 42This chapter discusses servers, services, programs, procedures, 43clients, and versions. A server is a piece of software where network 44services are implemented. A network service is a collection of one 45or more remote programs. A remote program implements one or more 46remote procedures; the procedures, their parameters, and results are 47documented in the specific program's protocol specification (see the 48\fIPort Mapper Program Protocol\fP\, below, for an example). Network 49clients are pieces of software that initiate remote procedure calls 50to services. A server may support more than one version of a remote 51program in order to be forward compatible with changing protocols. 52.LP 53For example, a network file service may be composed of two programs. 54One program may deal with high-level applications such as file system 55access control and locking. The other may deal with low-level file 56IO and have procedures like "read" and "write". A client machine of 57the network file service would call the procedures associated with 58the two programs of the service on behalf of some user on the client 59machine. 60.NH 2 61\&The RPC Model 62.LP 63The remote procedure call model is similar to the local procedure 64call model. In the local case, the caller places arguments to a 65procedure in some well-specified location (such as a result 66register). It then transfers control to the procedure, and 67eventually gains back control. At that point, the results of the 68procedure are extracted from the well-specified location, and the 69caller continues execution. 70.LP 71The remote procedure call is similar, in that one thread of control 72logically winds through two processes\(emone is the caller's process, 73the other is a server's process. That is, the caller process sends a 74call message to the server process and waits (blocks) for a reply 75message. The call message contains the procedure's parameters, among 76other things. The reply message contains the procedure's results, 77among other things. Once the reply message is received, the results 78of the procedure are extracted, and caller's execution is resumed. 79.LP 80On the server side, a process is dormant awaiting the arrival of a 81call message. When one arrives, the server process extracts the 82procedure's parameters, computes the results, sends a reply message, 83and then awaits the next call message. 84.LP 85Note that in this model, only one of the two processes is active at 86any given time. However, this model is only given as an example. 87The RPC protocol makes no restrictions on the concurrency model 88implemented, and others are possible. For example, an implementation 89may choose to have RPC calls be asynchronous, so that the client may 90do useful work while waiting for the reply from the server. Another 91possibility is to have the server create a task to process an 92incoming request, so that the server can be free to receive other 93requests. 94.NH 2 95\&Transports and Semantics 96.LP 97The RPC protocol is independent of transport protocols. That is, RPC 98does not care how a message is passed from one process to another. 99The protocol deals only with specification and interpretation of 100messages. 101.LP 102It is important to point out that RPC does not try to implement any 103kind of reliability and that the application must be aware of the 104type of transport protocol underneath RPC. If it knows it is running 105on top of a reliable transport such as TCP/IP[6], then most of the 106work is already done for it. On the other hand, if it is running on 107top of an unreliable transport such as UDP/IP[7], it must implement 108is own retransmission and time-out policy as the RPC layer does not 109provide this service. 110.LP 111Because of transport independence, the RPC protocol does not attach 112specific semantics to the remote procedures or their execution. 113Semantics can be inferred from (but should be explicitly specified 114by) the underlying transport protocol. For example, consider RPC 115running on top of an unreliable transport such as UDP/IP. If an 116application retransmits RPC messages after short time-outs, the only 117thing it can infer if it receives no reply is that the procedure was 118executed zero or more times. If it does receive a reply, then it can 119infer that the procedure was executed at least once. 120.LP 121A server may wish to remember previously granted requests from a 122client and not regrant them in order to insure some degree of 123execute-at-most-once semantics. A server can do this by taking 124advantage of the transaction ID that is packaged with every RPC 125request. The main use of this transaction is by the client RPC layer 126in matching replies to requests. However, a client application may 127choose to reuse its previous transaction ID when retransmitting a 128request. The server application, knowing this fact, may choose to 129remember this ID after granting a request and not regrant requests 130with the same ID in order to achieve some degree of 131execute-at-most-once semantics. The server is not allowed to examine 132this ID in any other way except as a test for equality. 133.LP 134On the other hand, if using a reliable transport such as TCP/IP, the 135application can infer from a reply message that the procedure was 136executed exactly once, but if it receives no reply message, it cannot 137assume the remote procedure was not executed. Note that even if a 138connection-oriented protocol like TCP is used, an application still 139needs time-outs and reconnection to handle server crashes. 140.LP 141There are other possibilities for transports besides datagram- or 142connection-oriented protocols. For example, a request-reply protocol 143such as VMTP[2] is perhaps the most natural transport for RPC. 144.SH 145.I 146NOTE: At Sun, RPC is currently implemented on top of both TCP/IP 147and UDP/IP transports. 148.LP 149.NH 2 150\&Binding and Rendezvous Independence 151.LP 152The act of binding a client to a service is NOT part of the remote 153procedure call specification. This important and necessary function 154is left up to some higher-level software. (The software may use RPC 155itself\(emsee the \fIPort Mapper Program Protocol\fP\, below). 156.LP 157Implementors should think of the RPC protocol as the jump-subroutine 158instruction ("JSR") of a network; the loader (binder) makes JSR 159useful, and the loader itself uses JSR to accomplish its task. 160Likewise, the network makes RPC useful, using RPC to accomplish this 161task. 162.NH 2 163\&Authentication 164.LP 165The RPC protocol provides the fields necessary for a client to 166identify itself to a service and vice-versa. Security and access 167control mechanisms can be built on top of the message authentication. 168Several different authentication protocols can be supported. A field 169in the RPC header indicates which protocol is being used. More 170information on specific authentication protocols can be found in the 171\fIAuthentication Protocols\fP\, 172below. 173.KS 174.NH 1 175\&RPC Protocol Requirements 176.LP 177The RPC protocol must provide for the following: 178.IP 1. 179Unique specification of a procedure to be called. 180.IP 2. 181Provisions for matching response messages to request messages. 182.KE 183.IP 3. 184Provisions for authenticating the caller to service and vice-versa. 185.LP 186Besides these requirements, features that detect the following are 187worth supporting because of protocol roll-over errors, implementation 188bugs, user error, and network administration: 189.IP 1. 190RPC protocol mismatches. 191.IP 2. 192Remote program protocol version mismatches. 193.IP 3. 194Protocol errors (such as misspecification of a procedure's parameters). 195.IP 4. 196Reasons why remote authentication failed. 197.IP 5. 198Any other reasons why the desired procedure was not called. 199.NH 2 200\&Programs and Procedures 201.LP 202The RPC call message has three unsigned fields: remote program 203number, remote program version number, and remote procedure number. 204The three fields uniquely identify the procedure to be called. 205Program numbers are administered by some central authority (like 206Sun). Once an implementor has a program number, he can implement his 207remote program; the first implementation would most likely have the 208version number of 1. Because most new protocols evolve into better, 209stable, and mature protocols, a version field of the call message 210identifies which version of the protocol the caller is using. 211Version numbers make speaking old and new protocols through the same 212server process possible. 213.LP 214The procedure number identifies the procedure to be called. These 215numbers are documented in the specific program's protocol 216specification. For example, a file service's protocol specification 217may state that its procedure number 5 is "read" and procedure number 21812 is "write". 219.LP 220Just as remote program protocols may change over several versions, 221the actual RPC message protocol could also change. Therefore, the 222call message also has in it the RPC version number, which is always 223equal to two for the version of RPC described here. 224.LP 225The reply message to a request message has enough information to 226distinguish the following error conditions: 227.IP 1. 228The remote implementation of RPC does speak protocol version 2. 229The lowest and highest supported RPC version numbers are returned. 230.IP 2. 231The remote program is not available on the remote system. 232.IP 3. 233The remote program does not support the requested version number. 234The lowest and highest supported remote program version numbers are 235returned. 236.IP 4. 237The requested procedure number does not exist. (This is usually a 238caller side protocol or programming error.) 239.IP 5. 240The parameters to the remote procedure appear to be garbage from the 241server's point of view. (Again, this is usually caused by a 242disagreement about the protocol between client and service.) 243.NH 2 244\&Authentication 245.LP 246Provisions for authentication of caller to service and vice-versa are 247provided as a part of the RPC protocol. The call message has two 248authentication fields, the credentials and verifier. The reply 249message has one authentication field, the response verifier. The RPC 250protocol specification defines all three fields to be the following 251opaque type: 252.DS 253.ft CW 254.vs 11 255enum auth_flavor { 256 AUTH_NULL = 0, 257 AUTH_UNIX = 1, 258 AUTH_SHORT = 2, 259 AUTH_DES = 3 260 /* \fIand more to be defined\fP */ 261}; 262 263struct opaque_auth { 264 auth_flavor flavor; 265 opaque body<400>; 266}; 267.DE 268.LP 269In simple English, any 270.I opaque_auth 271structure is an 272.I auth_flavor 273enumeration followed by bytes which are opaque to the RPC protocol 274implementation. 275.LP 276The interpretation and semantics of the data contained within the 277authentication fields is specified by individual, independent 278authentication protocol specifications. (See 279\fIAuthentication Protocols\fP\, 280below, for definitions of the various authentication protocols.) 281.LP 282If authentication parameters were rejected, the response message 283contains information stating why they were rejected. 284.NH 2 285\&Program Number Assignment 286.LP 287Program numbers are given out in groups of 288.I 0x20000000 289(decimal 536870912) according to the following chart: 290.TS 291box tab (&) ; 292lfI lfI 293rfL cfI . 294Program Numbers&Description 295_ 296.sp .5 2970 - 1fffffff&Defined by Sun 29820000000 - 3fffffff&Defined by user 29940000000 - 5fffffff&Transient 30060000000 - 7fffffff&Reserved 30180000000 - 9fffffff&Reserved 302a0000000 - bfffffff&Reserved 303c0000000 - dfffffff&Reserved 304e0000000 - ffffffff&Reserved 305.TE 306.LP 307The first group is a range of numbers administered by Sun 308Microsystems and should be identical for all sites. The second range 309is for applications peculiar to a particular site. This range is 310intended primarily for debugging new programs. When a site develops 311an application that might be of general interest, that application 312should be given an assigned number in the first range. The third 313group is for applications that generate program numbers dynamically. 314The final groups are reserved for future use, and should not be used. 315.NH 2 316\&Other Uses of the RPC Protocol 317.LP 318The intended use of this protocol is for calling remote procedures. 319That is, each call message is matched with a response message. 320However, the protocol itself is a message-passing protocol with which 321other (non-RPC) protocols can be implemented. Sun currently uses, or 322perhaps abuses, the RPC message protocol for the following two 323(non-RPC) protocols: batching (or pipelining) and broadcast RPC. 324These two protocols are discussed but not defined below. 325.NH 3 326\&Batching 327.LP 328Batching allows a client to send an arbitrarily large sequence of 329call messages to a server; batching typically uses reliable byte 330stream protocols (like TCP/IP) for its transport. In the case of 331batching, the client never waits for a reply from the server, and the 332server does not send replies to batch requests. A sequence of batch 333calls is usually terminated by a legitimate RPC in order to flush the 334pipeline (with positive acknowledgement). 335.NH 3 336\&Broadcast RPC 337.LP 338In broadcast RPC-based protocols, the client sends a broadcast packet 339to the network and waits for numerous replies. Broadcast RPC uses 340unreliable, packet-based protocols (like UDP/IP) as its transports. 341Servers that support broadcast protocols only respond when the 342request is successfully processed, and are silent in the face of 343errors. Broadcast RPC uses the Port Mapper RPC service to achieve 344its semantics. See the \fIPort Mapper Program Protocol\fP\, below, 345for more information. 346.KS 347.NH 1 348\&The RPC Message Protocol 349.LP 350This section defines the RPC message protocol in the XDR data 351description language. The message is defined in a top-down style. 352.ie t .DS 353.el .DS L 354.ft CW 355enum msg_type { 356 CALL = 0, 357 REPLY = 1 358}; 359 360.ft I 361/* 362* A reply to a call message can take on two forms: 363* The message was either accepted or rejected. 364*/ 365.ft CW 366enum reply_stat { 367 MSG_ACCEPTED = 0, 368 MSG_DENIED = 1 369}; 370 371.ft I 372/* 373* Given that a call message was accepted, the following is the 374* status of an attempt to call a remote procedure. 375*/ 376.ft CW 377enum accept_stat { 378 SUCCESS = 0, /* \fIRPC executed successfully \fP*/ 379 PROG_UNAVAIL = 1, /* \fIremote hasn't exported program \fP*/ 380 PROG_MISMATCH = 2, /* \fIremote can't support version # \fP*/ 381 PROC_UNAVAIL = 3, /* \fIprogram can't support procedure \fP*/ 382 GARBAGE_ARGS = 4 /* \fIprocedure can't decode params \fP*/ 383}; 384.DE 385.ie t .DS 386.el .DS L 387.ft I 388/* 389* Reasons why a call message was rejected: 390*/ 391.ft CW 392enum reject_stat { 393 RPC_MISMATCH = 0, /* \fIRPC version number != 2 \fP*/ 394 AUTH_ERROR = 1 /* \fIremote can't authenticate caller \fP*/ 395}; 396 397.ft I 398/* 399* Why authentication failed: 400*/ 401.ft CW 402enum auth_stat { 403 AUTH_BADCRED = 1, /* \fIbad credentials \fP*/ 404 AUTH_REJECTEDCRED = 2, /* \fIclient must begin new session \fP*/ 405 AUTH_BADVERF = 3, /* \fIbad verifier \fP*/ 406 AUTH_REJECTEDVERF = 4, /* \fIverifier expired or replayed \fP*/ 407 AUTH_TOOWEAK = 5 /* \fIrejected for security reasons \fP*/ 408}; 409.DE 410.KE 411.ie t .DS 412.el .DS L 413.ft I 414/* 415* The RPC message: 416* All messages start with a transaction identifier, xid, 417* followed by a two-armed discriminated union. The union's 418* discriminant is a msg_type which switches to one of the two 419* types of the message. The xid of a \fIREPLY\fP message always 420* matches that of the initiating \fICALL\fP message. NB: The xid 421* field is only used for clients matching reply messages with 422* call messages or for servers detecting retransmissions; the 423* service side cannot treat this id as any type of sequence 424* number. 425*/ 426.ft CW 427struct rpc_msg { 428 unsigned int xid; 429 union switch (msg_type mtype) { 430 case CALL: 431 call_body cbody; 432 case REPLY: 433 reply_body rbody; 434 } body; 435}; 436.DE 437.ie t .DS 438.el .DS L 439.ft I 440/* 441* Body of an RPC request call: 442* In version 2 of the RPC protocol specification, rpcvers must 443* be equal to 2. The fields prog, vers, and proc specify the 444* remote program, its version number, and the procedure within 445* the remote program to be called. After these fields are two 446* authentication parameters: cred (authentication credentials) 447* and verf (authentication verifier). The two authentication 448* parameters are followed by the parameters to the remote 449* procedure, which are specified by the specific program 450* protocol. 451*/ 452.ft CW 453struct call_body { 454 unsigned int rpcvers; /* \fImust be equal to two (2) \fP*/ 455 unsigned int prog; 456 unsigned int vers; 457 unsigned int proc; 458 opaque_auth cred; 459 opaque_auth verf; 460 /* \fIprocedure specific parameters start here \fP*/ 461}; 462.DE 463.ie t .DS 464.el .DS L 465.ft I 466/* 467* Body of a reply to an RPC request: 468* The call message was either accepted or rejected. 469*/ 470.ft CW 471union reply_body switch (reply_stat stat) { 472 case MSG_ACCEPTED: 473 accepted_reply areply; 474 case MSG_DENIED: 475 rejected_reply rreply; 476} reply; 477.DE 478.ie t .DS 479.el .DS L 480.ft I 481/* 482* Reply to an RPC request that was accepted by the server: 483* there could be an error even though the request was accepted. 484* The first field is an authentication verifier that the server 485* generates in order to validate itself to the caller. It is 486* followed by a union whose discriminant is an enum 487* accept_stat. The \fISUCCESS\fP arm of the union is protocol 488* specific. The \fIPROG_UNAVAIL\fP, \fIPROC_UNAVAIL\fP, and \fIGARBAGE_ARGP\fP 489* arms of the union are void. The \fIPROG_MISMATCH\fP arm specifies 490* the lowest and highest version numbers of the remote program 491* supported by the server. 492*/ 493.ft CW 494struct accepted_reply { 495 opaque_auth verf; 496 union switch (accept_stat stat) { 497 case SUCCESS: 498 opaque results[0]; 499 /* \fIprocedure-specific results start here\fP */ 500 case PROG_MISMATCH: 501 struct { 502 unsigned int low; 503 unsigned int high; 504 } mismatch_info; 505 default: 506.ft I 507 /* 508 * Void. Cases include \fIPROG_UNAVAIL, PROC_UNAVAIL\fP, 509 * and \fIGARBAGE_ARGS\fP. 510 */ 511.ft CW 512 void; 513 } reply_data; 514}; 515.DE 516.ie t .DS 517.el .DS L 518.ft I 519/* 520* Reply to an RPC request that was rejected by the server: 521* The request can be rejected for two reasons: either the 522* server is not running a compatible version of the RPC 523* protocol (\fIRPC_MISMATCH\fP), or the server refuses to 524* authenticate the caller (\fIAUTH_ERROR\fP). In case of an RPC 525* version mismatch, the server returns the lowest and highest 526* supported RPC version numbers. In case of refused 527* authentication, failure status is returned. 528*/ 529.ft CW 530union rejected_reply switch (reject_stat stat) { 531 case RPC_MISMATCH: 532 struct { 533 unsigned int low; 534 unsigned int high; 535 } mismatch_info; 536 case AUTH_ERROR: 537 auth_stat stat; 538}; 539.DE 540.NH 1 541\&Authentication Protocols 542.LP 543As previously stated, authentication parameters are opaque, but 544open-ended to the rest of the RPC protocol. This section defines 545some "flavors" of authentication implemented at (and supported by) 546Sun. Other sites are free to invent new authentication types, with 547the same rules of flavor number assignment as there is for program 548number assignment. 549.NH 2 550\&Null Authentication 551.LP 552Often calls must be made where the caller does not know who he is or 553the server does not care who the caller is. In this case, the flavor 554value (the discriminant of the \fIopaque_auth\fP's union) of the RPC 555message's credentials, verifier, and response verifier is 556.I AUTH_NULL . 557The bytes of the opaque_auth's body are undefined. 558It is recommended that the opaque length be zero. 559.NH 2 560\&UNIX Authentication 561.LP 562The caller of a remote procedure may wish to identify himself as he 563is identified on a UNIX system. The value of the credential's 564discriminant of an RPC call message is 565.I AUTH_UNIX . 566The bytes of 567the credential's opaque body encode the following structure: 568.DS 569.ft CW 570struct auth_unix { 571 unsigned int stamp; 572 string machinename<255>; 573 unsigned int uid; 574 unsigned int gid; 575 unsigned int gids<10>; 576}; 577.DE 578The 579.I stamp 580is an arbitrary ID which the caller machine may 581generate. The 582.I machinename 583is the name of the caller's machine (like "krypton"). The 584.I uid 585is the caller's effective user ID. The 586.I gid 587is the caller's effective group ID. The 588.I gids 589is a 590counted array of groups which contain the caller as a member. The 591verifier accompanying the credentials should be of 592.I AUTH_NULL 593(defined above). 594.LP 595The value of the discriminant of the response verifier received in 596the reply message from the server may be 597.I AUTH_NULL 598or 599.I AUTH_SHORT . 600In the case of 601.I AUTH_SHORT , 602the bytes of the response verifier's string encode an opaque 603structure. This new opaque structure may now be passed to the server 604instead of the original 605.I AUTH_UNIX 606flavor credentials. The server keeps a cache which maps shorthand 607opaque structures (passed back by way of an 608.I AUTH_SHORT 609style response verifier) to the original credentials of the caller. 610The caller can save network bandwidth and server cpu cycles by using 611the new credentials. 612.LP 613The server may flush the shorthand opaque structure at any time. If 614this happens, the remote procedure call message will be rejected due 615to an authentication error. The reason for the failure will be 616.I AUTH_REJECTEDCRED . 617At this point, the caller may wish to try the original 618.I AUTH_UNIX 619style of credentials. 620.KS 621.NH 2 622\&DES Authentication 623.LP 624UNIX authentication suffers from two major problems: 625.IP 1. 626The naming is too UNIX-system oriented. 627.IP 2. 628There is no verifier, so credentials can easily be faked. 629.LP 630DES authentication attempts to fix these two problems. 631.KE 632.NH 3 633\&Naming 634.LP 635The first problem is handled by addressing the caller by a simple 636string of characters instead of by an operating system specific 637integer. This string of characters is known as the "netname" or 638network name of the caller. The server is not allowed to interpret 639the contents of the caller's name in any other way except to 640identify the caller. Thus, netnames should be unique for every 641caller in the internet. 642.LP 643It is up to each operating system's implementation of DES 644authentication to generate netnames for its users that insure this 645uniqueness when they call upon remote servers. Operating systems 646already know how to distinguish users local to their systems. It is 647usually a simple matter to extend this mechanism to the network. 648For example, a UNIX user at Sun with a user ID of 515 might be 649assigned the following netname: "unix.515@sun.com". This netname 650contains three items that serve to insure it is unique. Going 651backwards, there is only one naming domain called "sun.com" in the 652internet. Within this domain, there is only one UNIX user with 653user ID 515. However, there may be another user on another 654operating system, for example VMS, within the same naming domain 655that, by coincidence, happens to have the same user ID. To insure 656that these two users can be distinguished we add the operating 657system name. So one user is "unix.515@sun.com" and the other is 658"vms.515@sun.com". 659.LP 660The first field is actually a naming method rather than an 661operating system name. It just happens that today there is almost 662a one-to-one correspondence between naming methods and operating 663systems. If the world could agree on a naming standard, the first 664field could be the name of that standard, instead of an operating 665system name. 666.LP 667.NH 3 668\&DES Authentication Verifiers 669.LP 670Unlike UNIX authentication, DES authentication does have a verifier 671so the server can validate the client's credential (and 672vice-versa). The contents of this verifier is primarily an 673encrypted timestamp. The server can decrypt this timestamp, and if 674it is close to what the real time is, then the client must have 675encrypted it correctly. The only way the client could encrypt it 676correctly is to know the "conversation key" of the RPC session. And 677if the client knows the conversation key, then it must be the real 678client. 679.LP 680The conversation key is a DES [5] key which the client generates 681and notifies the server of in its first RPC call. The conversation 682key is encrypted using a public key scheme in this first 683transaction. The particular public key scheme used in DES 684authentication is Diffie-Hellman [3] with 192-bit keys. The 685details of this encryption method are described later. 686.LP 687The client and the server need the same notion of the current time 688in order for all of this to work. If network time synchronization 689cannot be guaranteed, then client can synchronize with the server 690before beginning the conversation, perhaps by consulting the 691Internet Time Server (TIME[4]). 692.LP 693The way a server determines if a client timestamp is valid is 694somewhat complicated. For any other transaction but the first, the 695server just checks for two things: 696.IP 1. 697the timestamp is greater than the one previously seen from the 698same client. 699.IP 2. 700the timestamp has not expired. 701.LP 702A timestamp is expired if the server's time is later than the sum 703of the client's timestamp plus what is known as the client's 704"window". The "window" is a number the client passes (encrypted) 705to the server in its first transaction. You can think of it as a 706lifetime for the credential. 707.LP 708This explains everything but the first transaction. In the first 709transaction, the server checks only that the timestamp has not 710expired. If this was all that was done though, then it would be 711quite easy for the client to send random data in place of the 712timestamp with a fairly good chance of succeeding. As an added 713check, the client sends an encrypted item in the first transaction 714known as the "window verifier" which must be equal to the window 715minus 1, or the server will reject the credential. 716.LP 717The client too must check the verifier returned from the server to 718be sure it is legitimate. The server sends back to the client the 719encrypted timestamp it received from the client, minus one second. 720If the client gets anything different than this, it will reject it. 721.LP 722.NH 3 723\&Nicknames and Clock Synchronization 724.LP 725After the first transaction, the server's DES authentication 726subsystem returns in its verifier to the client an integer 727"nickname" which the client may use in its further transactions 728instead of passing its netname, encrypted DES key and window every 729time. The nickname is most likely an index into a table on the 730server which stores for each client its netname, decrypted DES key 731and window. 732.LP 733Though they originally were synchronized, the client's and server's 734clocks can get out of sync again. When this happens the client RPC 735subsystem most likely will get back 736.I RPC_AUTHERROR 737at which point it should resynchronize. 738.LP 739A client may still get the 740.I RPC_AUTHERROR 741error even though it is 742synchronized with the server. The reason is that the server's 743nickname table is a limited size, and it may flush entries whenever 744it wants. A client should resend its original credential in this 745case and the server will give it a new nickname. If a server 746crashes, the entire nickname table gets flushed, and all clients 747will have to resend their original credentials. 748.KS 749.NH 3 750\&DES Authentication Protocol (in XDR language) 751.ie t .DS 752.el .DS L 753.ft I 754/* 755* There are two kinds of credentials: one in which the client uses 756* its full network name, and one in which it uses its "nickname" 757* (just an unsigned integer) given to it by the server. The 758* client must use its fullname in its first transaction with the 759* server, in which the server will return to the client its 760* nickname. The client may use its nickname in all further 761* transactions with the server. There is no requirement to use the 762* nickname, but it is wise to use it for performance reasons. 763*/ 764.ft CW 765enum authdes_namekind { 766 ADN_FULLNAME = 0, 767 ADN_NICKNAME = 1 768}; 769 770.ft I 771/* 772* A 64-bit block of encrypted DES data 773*/ 774.ft CW 775typedef opaque des_block[8]; 776 777.ft I 778/* 779* Maximum length of a network user's name 780*/ 781.ft CW 782const MAXNETNAMELEN = 255; 783 784.ft I 785/* 786* A fullname contains the network name of the client, an encrypted 787* conversation key and the window. The window is actually a 788* lifetime for the credential. If the time indicated in the 789* verifier timestamp plus the window has past, then the server 790* should expire the request and not grant it. To insure that 791* requests are not replayed, the server should insist that 792* timestamps are greater than the previous one seen, unless it is 793* the first transaction. In the first transaction, the server 794* checks instead that the window verifier is one less than the 795* window. 796*/ 797.ft CW 798struct authdes_fullname { 799string name<MAXNETNAMELEN>; /* \fIname of client \f(CW*/ 800des_block key; /* \fIPK encrypted conversation key \f(CW*/ 801unsigned int window; /* \fIencrypted window \f(CW*/ 802}; 803 804.ft I 805/* 806* A credential is either a fullname or a nickname 807*/ 808.ft CW 809union authdes_cred switch (authdes_namekind adc_namekind) { 810 case ADN_FULLNAME: 811 authdes_fullname adc_fullname; 812 case ADN_NICKNAME: 813 unsigned int adc_nickname; 814}; 815 816.ft I 817/* 818* A timestamp encodes the time since midnight, January 1, 1970. 819*/ 820.ft CW 821struct timestamp { 822 unsigned int seconds; /* \fIseconds \fP*/ 823 unsigned int useconds; /* \fIand microseconds \fP*/ 824}; 825 826.ft I 827/* 828* Verifier: client variety 829* The window verifier is only used in the first transaction. In 830* conjunction with a fullname credential, these items are packed 831* into the following structure before being encrypted: 832* 833* \f(CWstruct {\fP 834* \f(CWadv_timestamp; \fP-- one DES block 835* \f(CWadc_fullname.window; \fP-- one half DES block 836* \f(CWadv_winverf; \fP-- one half DES block 837* \f(CW}\fP 838* This structure is encrypted using CBC mode encryption with an 839* input vector of zero. All other encryptions of timestamps use 840* ECB mode encryption. 841*/ 842.ft CW 843struct authdes_verf_clnt { 844 timestamp adv_timestamp; /* \fIencrypted timestamp \fP*/ 845 unsigned int adv_winverf; /* \fIencrypted window verifier \fP*/ 846}; 847 848.ft I 849/* 850* Verifier: server variety 851* The server returns (encrypted) the same timestamp the client 852* gave it minus one second. It also tells the client its nickname 853* to be used in future transactions (unencrypted). 854*/ 855.ft CW 856struct authdes_verf_svr { 857timestamp adv_timeverf; /* \fIencrypted verifier \fP*/ 858unsigned int adv_nickname; /* \fInew nickname for client \fP*/ 859}; 860.DE 861.KE 862.NH 3 863\&Diffie-Hellman Encryption 864.LP 865In this scheme, there are two constants, 866.I BASE 867and 868.I MODULUS . 869The 870particular values Sun has chosen for these for the DES 871authentication protocol are: 872.ie t .DS 873.el .DS L 874.ft CW 875const BASE = 3; 876const MODULUS = 877 "d4a0ba0250b6fd2ec626e7efd637df76c716e22d0944b88b"; /* \fIhex \fP*/ 878.DE 879.ft R 880The way this scheme works is best explained by an example. Suppose 881there are two people "A" and "B" who want to send encrypted 882messages to each other. So, A and B both generate "secret" keys at 883random which they do not reveal to anyone. Let these keys be 884represented as SK(A) and SK(B). They also publish in a public 885directory their "public" keys. These keys are computed as follows: 886.ie t .DS 887.el .DS L 888.ft CW 889PK(A) = ( BASE ** SK(A) ) mod MODULUS 890PK(B) = ( BASE ** SK(B) ) mod MODULUS 891.DE 892.ft R 893The "**" notation is used here to represent exponentiation. Now, 894both A and B can arrive at the "common" key between them, 895represented here as CK(A, B), without revealing their secret keys. 896.LP 897A computes: 898.ie t .DS 899.el .DS L 900.ft CW 901CK(A, B) = ( PK(B) ** SK(A)) mod MODULUS 902.DE 903.ft R 904while B computes: 905.ie t .DS 906.el .DS L 907.ft CW 908CK(A, B) = ( PK(A) ** SK(B)) mod MODULUS 909.DE 910.ft R 911These two can be shown to be equivalent: 912.ie t .DS 913.el .DS L 914.ft CW 915(PK(B) ** SK(A)) mod MODULUS = (PK(A) ** SK(B)) mod MODULUS 916.DE 917.ft R 918We drop the "mod MODULUS" parts and assume modulo arithmetic to 919simplify things: 920.ie t .DS 921.el .DS L 922.ft CW 923PK(B) ** SK(A) = PK(A) ** SK(B) 924.DE 925.ft R 926Then, replace PK(B) by what B computed earlier and likewise for 927PK(A). 928.ie t .DS 929.el .DS L 930.ft CW 931((BASE ** SK(B)) ** SK(A) = (BASE ** SK(A)) ** SK(B) 932.DE 933.ft R 934which leads to: 935.ie t .DS 936.el .DS L 937.ft CW 938BASE ** (SK(A) * SK(B)) = BASE ** (SK(A) * SK(B)) 939.DE 940.ft R 941This common key CK(A, B) is not used to encrypt the timestamps used 942in the protocol. Rather, it is used only to encrypt a conversation 943key which is then used to encrypt the timestamps. The reason for 944doing this is to use the common key as little as possible, for fear 945that it could be broken. Breaking the conversation key is a far 946less serious offense, since conversations are relatively 947short-lived. 948.LP 949The conversation key is encrypted using 56-bit DES keys, yet the 950common key is 192 bits. To reduce the number of bits, 56 bits are 951selected from the common key as follows. The middle-most 8-bytes 952are selected from the common key, and then parity is added to the 953lower order bit of each byte, producing a 56-bit key with 8 bits of 954parity. 955.KS 956.NH 1 957\&Record Marking Standard 958.LP 959When RPC messages are passed on top of a byte stream protocol (like 960TCP/IP), it is necessary, or at least desirable, to delimit one 961message from another in order to detect and possibly recover from 962user protocol errors. This is called record marking (RM). Sun uses 963this RM/TCP/IP transport for passing RPC messages on TCP streams. 964One RPC message fits into one RM record. 965.LP 966A record is composed of one or more record fragments. A record 967fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of 968fragment data. The bytes encode an unsigned binary number; as with 969XDR integers, the byte order is from highest to lowest. The number 970encodes two values\(ema boolean which indicates whether the fragment 971is the last fragment of the record (bit value 1 implies the fragment 972is the last fragment) and a 31-bit unsigned binary value which is the 973length in bytes of the fragment's data. The boolean value is the 974highest-order bit of the header; the length is the 31 low-order bits. 975(Note that this record specification is NOT in XDR standard form!) 976.KE 977.KS 978.NH 1 979\&The RPC Language 980.LP 981Just as there was a need to describe the XDR data-types in a formal 982language, there is also need to describe the procedures that operate 983on these XDR data-types in a formal language as well. We use the RPC 984Language for this purpose. It is an extension to the XDR language. 985The following example is used to describe the essence of the 986language. 987.NH 2 988\&An Example Service Described in the RPC Language 989.LP 990Here is an example of the specification of a simple ping program. 991.ie t .DS 992.el .DS L 993.vs 11 994.ft I 995/* 996* Simple ping program 997*/ 998.ft CW 999program PING_PROG { 1000 /* \fILatest and greatest version\fP */ 1001 version PING_VERS_PINGBACK { 1002 void 1003 PINGPROC_NULL(void) = 0; 1004 1005.ft I 1006 /* 1007 * Ping the caller, return the round-trip time 1008 * (in microseconds). Returns -1 if the operation 1009 * timed out. 1010 */ 1011.ft CW 1012 int 1013 PINGPROC_PINGBACK(void) = 1; 1014} = 2; 1015 1016.ft I 1017/* 1018* Original version 1019*/ 1020.ft CW 1021version PING_VERS_ORIG { 1022 void 1023 PINGPROC_NULL(void) = 0; 1024 } = 1; 1025} = 1; 1026 1027const PING_VERS = 2; /* \fIlatest version \fP*/ 1028.vs 1029.DE 1030.KE 1031.LP 1032The first version described is 1033.I PING_VERS_PINGBACK 1034with two procedures, 1035.I PINGPROC_NULL 1036and 1037.I PINGPROC_PINGBACK . 1038.I PINGPROC_NULL 1039takes no arguments and returns no results, but it is useful for 1040computing round-trip times from the client to the server and back 1041again. By convention, procedure 0 of any RPC protocol should have 1042the same semantics, and never require any kind of authentication. 1043The second procedure is used for the client to have the server do a 1044reverse ping operation back to the client, and it returns the amount 1045of time (in microseconds) that the operation used. The next version, 1046.I PING_VERS_ORIG , 1047is the original version of the protocol 1048and it does not contain 1049.I PINGPROC_PINGBACK 1050procedure. It is useful 1051for compatibility with old client programs, and as this program 1052matures it may be dropped from the protocol entirely. 1053.KS 1054.NH 2 1055\&The RPC Language Specification 1056.LP 1057The RPC language is identical to the XDR language, except for the 1058added definition of a 1059.I program-def 1060described below. 1061.DS 1062.ft CW 1063program-def: 1064 "program" identifier "{" 1065 version-def 1066 version-def * 1067 "}" "=" constant ";" 1068 1069version-def: 1070 "version" identifier "{" 1071 procedure-def 1072 procedure-def * 1073 "}" "=" constant ";" 1074 1075procedure-def: 1076 type-specifier identifier "(" type-specifier ")" 1077 "=" constant ";" 1078.DE 1079.KE 1080.NH 2 1081\&Syntax Notes 1082.IP 1. 1083The following keywords are added and cannot be used as 1084identifiers: "program" and "version"; 1085.IP 2. 1086A version name cannot occur more than once within the scope of 1087a program definition. Nor can a version number occur more than once 1088within the scope of a program definition. 1089.IP 3. 1090A procedure name cannot occur more than once within the scope 1091of a version definition. Nor can a procedure number occur more than 1092once within the scope of version definition. 1093.IP 4. 1094Program identifiers are in the same name space as constant and 1095type identifiers. 1096.IP 5. 1097Only unsigned constants can be assigned to programs, versions 1098and procedures. 1099.NH 1 1100\&Port Mapper Program Protocol 1101.LP 1102The port mapper program maps RPC program and version numbers to 1103transport-specific port numbers. This program makes dynamic binding 1104of remote programs possible. 1105.LP 1106This is desirable because the range of reserved port numbers is very 1107small and the number of potential remote programs is very large. By 1108running only the port mapper on a reserved port, the port numbers of 1109other remote programs can be ascertained by querying the port mapper. 1110.LP 1111The port mapper also aids in broadcast RPC. A given RPC program will 1112usually have different port number bindings on different machines, so 1113there is no way to directly broadcast to all of these programs. The 1114port mapper, however, does have a fixed port number. So, to 1115broadcast to a given program, the client actually sends its message 1116to the port mapper located at the broadcast address. Each port 1117mapper that picks up the broadcast then calls the local service 1118specified by the client. When the port mapper gets the reply from 1119the local service, it sends the reply on back to the client. 1120.KS 1121.NH 2 1122\&Port Mapper Protocol Specification (in RPC Language) 1123.ie t .DS 1124.el .DS L 1125.ft CW 1126.vs 11 1127const PMAP_PORT = 111; /* \fIportmapper port number \fP*/ 1128 1129.ft I 1130/* 1131* A mapping of (program, version, protocol) to port number 1132*/ 1133.ft CW 1134struct mapping { 1135 unsigned int prog; 1136 unsigned int vers; 1137 unsigned int prot; 1138 unsigned int port; 1139}; 1140 1141.ft I 1142/* 1143* Supported values for the "prot" field 1144*/ 1145.ft CW 1146const IPPROTO_TCP = 6; /* \fIprotocol number for TCP/IP \fP*/ 1147const IPPROTO_UDP = 17; /* \fIprotocol number for UDP/IP \fP*/ 1148 1149.ft I 1150/* 1151* A list of mappings 1152*/ 1153.ft CW 1154struct *pmaplist { 1155 mapping map; 1156 pmaplist next; 1157}; 1158.vs 1159.DE 1160.ie t .DS 1161.el .DS L 1162.vs 11 1163.ft I 1164/* 1165* Arguments to callit 1166*/ 1167.ft CW 1168struct call_args { 1169 unsigned int prog; 1170 unsigned int vers; 1171 unsigned int proc; 1172 opaque args<>; 1173}; 1174 1175.ft I 1176/* 1177* Results of callit 1178*/ 1179.ft CW 1180struct call_result { 1181 unsigned int port; 1182 opaque res<>; 1183}; 1184.vs 1185.DE 1186.KE 1187.ie t .DS 1188.el .DS L 1189.vs 11 1190.ft I 1191/* 1192* Port mapper procedures 1193*/ 1194.ft CW 1195program PMAP_PROG { 1196 version PMAP_VERS { 1197 void 1198 PMAPPROC_NULL(void) = 0; 1199 1200 bool 1201 PMAPPROC_SET(mapping) = 1; 1202 1203 bool 1204 PMAPPROC_UNSET(mapping) = 2; 1205 1206 unsigned int 1207 PMAPPROC_GETPORT(mapping) = 3; 1208 1209 pmaplist 1210 PMAPPROC_DUMP(void) = 4; 1211 1212 call_result 1213 PMAPPROC_CALLIT(call_args) = 5; 1214 } = 2; 1215} = 100000; 1216.vs 1217.DE 1218.NH 2 1219\&Port Mapper Operation 1220.LP 1221The portmapper program currently supports two protocols (UDP/IP and 1222TCP/IP). The portmapper is contacted by talking to it on assigned 1223port number 111 (SUNRPC [8]) on either of these protocols. The 1224following is a description of each of the portmapper procedures: 1225.IP \fBPMAPPROC_NULL:\fP 1226This procedure does no work. By convention, procedure zero of any 1227protocol takes no parameters and returns no results. 1228.IP \fBPMAPPROC_SET:\fP 1229When a program first becomes available on a machine, it registers 1230itself with the port mapper program on the same machine. The program 1231passes its program number "prog", version number "vers", transport 1232protocol number "prot", and the port "port" on which it awaits 1233service request. The procedure returns a boolean response whose 1234value is 1235.I TRUE 1236if the procedure successfully established the mapping and 1237.I FALSE 1238otherwise. The procedure refuses to establish 1239a mapping if one already exists for the tuple "(prog, vers, prot)". 1240.IP \fBPMAPPROC_UNSET:\fP 1241When a program becomes unavailable, it should unregister itself with 1242the port mapper program on the same machine. The parameters and 1243results have meanings identical to those of 1244.I PMAPPROC_SET . 1245The protocol and port number fields of the argument are ignored. 1246.IP \fBPMAPPROC_GETPORT:\fP 1247Given a program number "prog", version number "vers", and transport 1248protocol number "prot", this procedure returns the port number on 1249which the program is awaiting call requests. A port value of zeros 1250means the program has not been registered. The "port" field of the 1251argument is ignored. 1252.IP \fBPMAPPROC_DUMP:\fP 1253This procedure enumerates all entries in the port mapper's database. 1254The procedure takes no parameters and returns a list of program, 1255version, protocol, and port values. 1256.IP \fBPMAPPROC_CALLIT:\fP 1257This procedure allows a caller to call another remote procedure on 1258the same machine without knowing the remote procedure's port number. 1259It is intended for supporting broadcasts to arbitrary remote programs 1260via the well-known port mapper's port. The parameters "prog", 1261"vers", "proc", and the bytes of "args" are the program number, 1262version number, procedure number, and parameters of the remote 1263procedure. 1264.LP 1265.B Note: 1266.RS 1267.IP 1. 1268This procedure only sends a response if the procedure was 1269successfully executed and is silent (no response) otherwise. 1270.IP 2. 1271The port mapper communicates with the remote program using UDP/IP 1272only. 1273.RE 1274.LP 1275The procedure returns the remote program's port number, and the bytes 1276of results are the results of the remote procedure. 1277.bp 1278.NH 1 1279\&References 1280.LP 1281[1] Birrell, Andrew D. & Nelson, Bruce Jay; "Implementing Remote 1282Procedure Calls"; XEROX CSL-83-7, October 1983. 1283.LP 1284[2] Cheriton, D.; "VMTP: Versatile Message Transaction Protocol", 1285Preliminary Version 0.3; Stanford University, January 1987. 1286.LP 1287[3] Diffie & Hellman; "New Directions in Cryptography"; IEEE 1288Transactions on Information Theory IT-22, November 1976. 1289.LP 1290[4] Harrenstien, K.; "Time Server", RFC 738; Information Sciences 1291Institute, October 1977. 1292.LP 1293[5] National Bureau of Standards; "Data Encryption Standard"; Federal 1294Information Processing Standards Publication 46, January 1977. 1295.LP 1296[6] Postel, J.; "Transmission Control Protocol - DARPA Internet 1297Program Protocol Specification", RFC 793; Information Sciences 1298Institute, September 1981. 1299.LP 1300[7] Postel, J.; "User Datagram Protocol", RFC 768; Information Sciences 1301Institute, August 1980. 1302.LP 1303[8] Reynolds, J. & Postel, J.; "Assigned Numbers", RFC 923; Information 1304Sciences Institute, October 1984.