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