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