RReemmoottee PPrroocceedduurree CCaallllss:: PPrroottooccooll SSppeecciiffiiccaattiioonn 11.. SSttaattuuss ooff tthhiiss MMeemmoo Note: This chapter specifies a protocol that Sun Microsys- tems, Inc., and others are using. It has been designated RFC1050 by the ARPA Network Information Center. 22.. IInnttrroodduuccttiioonn This chapter specifies a message protocol used in imple- menting Sun's Remote Procedure Call (RPC) package. (The message protocol is specified with the External Data Repre- sentation (XDR) language. See the _E_x_t_e_r_n_a_l _D_a_t_a _R_e_p_r_e_s_e_n_t_a_- _t_i_o_n _S_t_a_n_d_a_r_d_: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n for the details. Here, we assume that the reader is familiar with XDR and do not attempt to justify it or its uses). The paper by Birrell and Nelson [1] is recommended as an excellent background to and justification of RPC. 22..11.. TTeerrmmiinnoollooggyy This chapter discusses servers, services, programs, proce- dures, clients, and versions. A server is a piece of soft- ware where network services are implemented. A network ser- vice is a collection of one or more remote programs. A remote program implements one or more remote procedures; the procedures, their parameters, and results are documented in the specific program's protocol specification (see the _P_o_r_t _M_a_p_p_e_r _P_r_o_g_r_a_m _P_r_o_t_o_c_o_l below, for an example). Network clients are pieces of software that initiate remote proce- dure calls to services. A server may support more than one version of a remote program in order to be forward compati- ble with changing protocols. For example, a network file service may be composed of two programs. One program may deal with high-level applications such as file system access control and locking. The other may deal with low-level file IO and have procedures like "read" and "write". A client machine of the network file service would call the procedures associated with the two programs of the service on behalf of some user on the client machine. 22..22.. TThhee RRPPCC MMooddeell The remote procedure call model is similar to the local pro- cedure call model. In the local case, the caller places arguments to a procedure in some well-specified location (such as a result register). It then transfers control to the procedure, and eventually gains back control. At that point, the results of the procedure are extracted from the - 1 - Page 2 Remote Procedure Calls: Protocol Specification well-specified location, and the caller continues execution. The remote procedure call is similar, in that one thread of control logically winds through two processes--one is the caller's process, the other is a server's process. That is, the caller process sends a call message to the server pro- cess and waits (blocks) for a reply message. The call mes- sage contains the procedure's parameters, among other things. The reply message contains the procedure's results, among other things. Once the reply message is received, the results of the procedure are extracted, and caller's execu- tion is resumed. On the server side, a process is dormant awaiting the arrival of a call message. When one arrives, the server process extracts the procedure's parameters, computes the results, sends a reply message, and then awaits the next call message. Note that in this model, only one of the two processes is active at any given time. However, this model is only given as an example. The RPC protocol makes no restrictions on the concurrency model implemented, and others are possible. For example, an implementation may choose to have RPC calls be asynchronous, so that the client may do useful work while waiting for the reply from the server. Another possibility is to have the server create a task to process an incoming request, so that the server can be free to receive other requests. 22..33.. TTrraannssppoorrttss aanndd SSeemmaannttiiccss The RPC protocol is independent of transport protocols. That is, RPC does not care how a message is passed from one process to another. The protocol deals only with specifica- tion and interpretation of messages. It is important to point out that RPC does not try to imple- ment any kind of reliability and that the application must be aware of the type of transport protocol underneath RPC. If it knows it is running on top of a reliable transport such as TCP/IP[6], then most of the work is already done for it. On the other hand, if it is running on top of an unre- liable transport such as UDP/IP[7], it must implement is own retransmission and time-out policy as the RPC layer does not provide this service. Because of transport independence, the RPC protocol does not attach specific semantics to the remote procedures or their execution. Semantics can be inferred from (but should be explicitly specified by) the underlying transport protocol. For example, consider RPC running on top of an unreliable transport such as UDP/IP. If an application retransmits RPC messages after short time-outs, the only thing it can infer Remote Procedure Calls: Protocol Specification Page 3 if it receives no reply is that the procedure was executed zero or more times. If it does receive a reply, then it can infer that the procedure was executed at least once. A server may wish to remember previously granted requests from a client and not regrant them in order to insure some degree of execute-at-most-once semantics. A server can do this by taking advantage of the transaction ID that is pack- aged with every RPC request. The main use of this transac- tion is by the client RPC layer in matching replies to requests. However, a client application may choose to reuse its previous transaction ID when retransmitting a request. The server application, knowing this fact, may choose to remember this ID after granting a request and not regrant requests with the same ID in order to achieve some degree of execute-at-most-once semantics. The server is not allowed to examine this ID in any other way except as a test for equality. On the other hand, if using a reliable transport such as TCP/IP, the application can infer from a reply message that the procedure was executed exactly once, but if it receives no reply message, it cannot assume the remote procedure was not executed. Note that even if a connection-oriented pro- tocol like TCP is used, an application still needs time-outs and reconnection to handle server crashes. There are other possibilities for transports besides data- gram- or connection-oriented protocols. For example, a request-reply protocol such as VMTP[2] is perhaps the most natural transport for RPC. _N_O_T_E_: _A_t _S_u_n_, _R_P_C _i_s _c_u_r_r_e_n_t_l_y _i_m_p_l_e_m_e_n_t_e_d _o_n _t_o_p _o_f _b_o_t_h _T_C_P_/_I_P _a_n_d _U_D_P_/_I_P _t_r_a_n_s_p_o_r_t_s_. 22..44.. BBiinnddiinngg aanndd RReennddeezzvvoouuss IInnddeeppeennddeennccee The act of binding a client to a service is NOT part of the remote procedure call specification. This important and necessary function is left up to some higher-level software. (The software may use RPC itself--see the _P_o_r_t _M_a_p_p_e_r _P_r_o_- _g_r_a_m _P_r_o_t_o_c_o_l below). Implementors should think of the RPC protocol as the jump- subroutine instruction ("JSR") of a network; the loader (binder) makes JSR useful, and the loader itself uses JSR to accomplish its task. Likewise, the network makes RPC use- ful, using RPC to accomplish this task. 22..55.. AAuutthheennttiiccaattiioonn The RPC protocol provides the fields necessary for a client to identify itself to a service and vice-versa. Security Page 4 Remote Procedure Calls: Protocol Specification and access control mechanisms can be built on top of the message authentication. Several different authentication protocols can be supported. A field in the RPC header indi- cates which protocol is being used. More information on specific authentication protocols can be found in the _A_u_t_h_e_n_t_i_c_a_t_i_o_n _P_r_o_t_o_c_o_l_s below. 33.. RRPPCC PPrroottooccooll RReeqquuiirreemmeennttss The RPC protocol must provide for the following: 1. Unique specification of a procedure to be called. 2. Provisions for matching response messages to request messages. 3. Provisions for authenticating the caller to service and vice-versa. Besides these requirements, features that detect the follow- ing are worth supporting because of protocol roll-over errors, implementation bugs, user error, and network admin- istration: 1. RPC protocol mismatches. 2. Remote program protocol version mismatches. 3. Protocol errors (such as misspecification of a proce- dure's parameters). 4. Reasons why remote authentication failed. 5. Any other reasons why the desired procedure was not called. 33..11.. PPrrooggrraammss aanndd PPrroocceedduurreess The RPC call message has three unsigned fields: remote pro- gram number, remote program version number, and remote pro- cedure number. The three fields uniquely identify the pro- cedure to be called. Program numbers are administered by some central authority (like Sun). Once an implementor has a program number, he can implement his remote program; the first implementation would most likely have the version num- ber of 1. Because most new protocols evolve into better, stable, and mature protocols, a version field of the call message identifies which version of the protocol the caller is using. Version numbers make speaking old and new proto- cols through the same server process possible. The procedure number identifies the procedure to be called. These numbers are documented in the specific program's pro- tocol specification. For example, a file service's protocol Remote Procedure Calls: Protocol Specification Page 5 specification may state that its procedure number 5 is "read" and procedure number 12 is "write". Just as remote program protocols may change over several versions, the actual RPC message protocol could also change. Therefore, the call message also has in it the RPC version number, which is always equal to two for the version of RPC described here. The reply message to a request message has enough infor- mation to distinguish the following error conditions: 1. The remote implementation of RPC does speak protocol version 2. The lowest and highest supported RPC ver- sion numbers are returned. 2. The remote program is not available on the remote sys- tem. 3. The remote program does not support the requested ver- sion number. The lowest and highest supported remote program version numbers are returned. 4. The requested procedure number does not exist. (This is usually a caller side protocol or programming error.) 5. The parameters to the remote procedure appear to be garbage from the server's point of view. (Again, this is usually caused by a disagreement about the protocol between client and service.) 33..22.. AAuutthheennttiiccaattiioonn Provisions for authentication of caller to service and vice- versa are provided as a part of the RPC protocol. The call message has two authentication fields, the credentials and verifier. The reply message has one authentication field, the response verifier. The RPC protocol specification defines all three fields to be the following opaque type: enum auth_flavor { AUTH_NULL = 0, AUTH_UNIX = 1, AUTH_SHORT = 2, AUTH_DES = 3 /* _a_n_d _m_o_r_e _t_o _b_e _d_e_f_i_n_e_d */ }; struct opaque_auth { auth_flavor flavor; opaque body<400>; }; Page 6 Remote Procedure Calls: Protocol Specification In simple English, any _o_p_a_q_u_e___a_u_t_h structure is an _a_u_t_h___f_l_a_- _v_o_r enumeration followed by bytes which are opaque to the RPC protocol implementation. The interpretation and semantics of the data contained within the authentication fields is specified by indi- vidual, independent authentication protocol specifica- tions. (See _A_u_t_h_e_n_t_i_c_a_t_i_o_n _P_r_o_t_o_c_o_l_s below, for defini- tions of the various authentication protocols.) If authentication parameters were rejected, the response message contains information stating why they were rejected. 33..33.. PPrrooggrraamm NNuummbbeerr AAssssiiggnnmmeenntt Program numbers are given out in groups of _0_x_2_0_0_0_0_0_0_0 (deci- mal 536870912) according to the following chart: +--------------------------------------+ |_P_r_o_g_r_a_m _N_u_m_b_e_r_s _D_e_s_c_r_i_p_t_i_o_n | +--------------------------------------+ | 0 - 1fffffff _D_e_f_i_n_e_d _b_y _S_u_n | |20000000 - 3fffffff _D_e_f_i_n_e_d _b_y _u_s_e_r | |40000000 - 5fffffff _T_r_a_n_s_i_e_n_t | |60000000 - 7fffffff _R_e_s_e_r_v_e_d | |80000000 - 9fffffff _R_e_s_e_r_v_e_d | |a0000000 - bfffffff _R_e_s_e_r_v_e_d | |c0000000 - dfffffff _R_e_s_e_r_v_e_d | |e0000000 - ffffffff _R_e_s_e_r_v_e_d | +--------------------------------------+ The first group is a range of numbers administered by Sun Microsystems and should be identical for all sites. The second range is for applications peculiar to a particular site. This range is intended primarily for debugging new programs. When a site develops an application that might be of general interest, that application should be given an assigned number in the first range. The third group is for applications that generate program numbers dynamically. The final groups are reserved for future use, and should not be used. 33..44.. OOtthheerr UUsseess ooff tthhee RRPPCC PPrroottooccooll The intended use of this protocol is for calling remote pro- cedures. That is, each call message is matched with a response message. However, the protocol itself is a mes- sage-passing protocol with which other (non-RPC) protocols can be implemented. Sun currently uses, or perhaps abuses, the RPC message protocol for the following two (non-RPC) protocols: batching (or pipelining) and broadcast RPC. These two protocols are discussed but not defined below. Remote Procedure Calls: Protocol Specification Page 7 33..44..11.. BBaattcchhiinngg Batching allows a client to send an arbitrarily large sequence of call messages to a server; batching typically uses reliable byte stream protocols (like TCP/IP) for its transport. In the case of batching, the client never waits for a reply from the server, and the server does not send replies to batch requests. A sequence of batch calls is usually terminated by a legitimate RPC in order to flush the pipeline (with positive acknowledgement). 33..44..22.. BBrrooaaddccaasstt RRPPCC In broadcast RPC-based protocols, the client sends a broad- cast packet to the network and waits for numerous replies. Broadcast RPC uses unreliable, packet-based protocols (like UDP/IP) as its transports. Servers that support broadcast protocols only respond when the request is successfully pro- cessed, and are silent in the face of errors. Broadcast RPC uses the Port Mapper RPC service to achieve its semantics. See the _P_o_r_t _M_a_p_p_e_r _P_r_o_g_r_a_m _P_r_o_t_o_c_o_l below, for more infor- mation. Page 8 Remote Procedure Calls: Protocol Specification 44.. TThhee RRPPCC MMeessssaaggee PPrroottooccooll This section defines the RPC message protocol in the XDR data description language. The message is defined in a top- down style. enum msg_type { CALL = 0, REPLY = 1 }; _/_* _* _A _r_e_p_l_y _t_o _a _c_a_l_l _m_e_s_s_a_g_e _c_a_n _t_a_k_e _o_n _t_w_o _f_o_r_m_s_: _* _T_h_e _m_e_s_s_a_g_e _w_a_s _e_i_t_h_e_r _a_c_c_e_p_t_e_d _o_r _r_e_j_e_c_t_e_d_. _*_/ _e_n_u_m _r_e_p_l_y___s_t_a_t _{ _M_S_G___A_C_C_E_P_T_E_D _= _0_, _M_S_G___D_E_N_I_E_D _= _1 _}_; _/_* _* _G_i_v_e_n _t_h_a_t _a _c_a_l_l _m_e_s_s_a_g_e _w_a_s _a_c_c_e_p_t_e_d_, _t_h_e _f_o_l_l_o_w_i_n_g _i_s _t_h_e _* _s_t_a_t_u_s _o_f _a_n _a_t_t_e_m_p_t _t_o _c_a_l_l _a _r_e_m_o_t_e _p_r_o_c_e_d_u_r_e_. _*_/ _e_n_u_m _a_c_c_e_p_t___s_t_a_t _{ _S_U_C_C_E_S_S _= _0_, _/_* _R_P_C _e_x_e_c_u_t_e_d _s_u_c_c_e_s_s_f_u_l_l_y _*_/ _P_R_O_G___U_N_A_V_A_I_L _= _1_, _/_* _r_e_m_o_t_e _h_a_s_n_'_t _e_x_p_o_r_t_e_d _p_r_o_g_r_a_m _*_/ _P_R_O_G___M_I_S_M_A_T_C_H _= _2_, _/_* _r_e_m_o_t_e _c_a_n_'_t _s_u_p_p_o_r_t _v_e_r_s_i_o_n _# _*_/ _P_R_O_C___U_N_A_V_A_I_L _= _3_, _/_* _p_r_o_g_r_a_m _c_a_n_'_t _s_u_p_p_o_r_t _p_r_o_c_e_d_u_r_e _*_/ _G_A_R_B_A_G_E___A_R_G_S _= _4 _/_* _p_r_o_c_e_d_u_r_e _c_a_n_'_t _d_e_c_o_d_e _p_a_r_a_m_s _*_/ _}_; _/_* _* _R_e_a_s_o_n_s _w_h_y _a _c_a_l_l _m_e_s_s_a_g_e _w_a_s _r_e_j_e_c_t_e_d_: _*_/ _e_n_u_m _r_e_j_e_c_t___s_t_a_t _{ _R_P_C___M_I_S_M_A_T_C_H _= _0_, _/_* _R_P_C _v_e_r_s_i_o_n _n_u_m_b_e_r _!_= _2 _*_/ _A_U_T_H___E_R_R_O_R _= _1 _/_* _r_e_m_o_t_e _c_a_n_'_t _a_u_t_h_e_n_t_i_c_a_t_e _c_a_l_l_e_r _*_/ _}_; _/_* _* _W_h_y _a_u_t_h_e_n_t_i_c_a_t_i_o_n _f_a_i_l_e_d_: _*_/ _e_n_u_m _a_u_t_h___s_t_a_t _{ _A_U_T_H___B_A_D_C_R_E_D _= _1_, _/_* _b_a_d _c_r_e_d_e_n_t_i_a_l_s _*_/ _A_U_T_H___R_E_J_E_C_T_E_D_C_R_E_D _= _2_, _/_* _c_l_i_e_n_t _m_u_s_t _b_e_g_i_n _n_e_w _s_e_s_s_i_o_n _*_/ _A_U_T_H___B_A_D_V_E_R_F _= _3_, _/_* _b_a_d _v_e_r_i_f_i_e_r _*_/ _A_U_T_H___R_E_J_E_C_T_E_D_V_E_R_F _= _4_, _/_* _v_e_r_i_f_i_e_r _e_x_p_i_r_e_d _o_r _r_e_p_l_a_y_e_d _*_/ _A_U_T_H___T_O_O_W_E_A_K _= _5 _/_* _r_e_j_e_c_t_e_d _f_o_r _s_e_c_u_r_i_t_y _r_e_a_s_o_n_s _*_/ _}_; Remote Procedure Calls: Protocol Specification Page 9 _/_* _* _T_h_e _R_P_C _m_e_s_s_a_g_e_: _* _A_l_l _m_e_s_s_a_g_e_s _s_t_a_r_t _w_i_t_h _a _t_r_a_n_s_a_c_t_i_o_n _i_d_e_n_t_i_f_i_e_r_, _x_i_d_, _* _f_o_l_l_o_w_e_d _b_y _a _t_w_o_-_a_r_m_e_d _d_i_s_c_r_i_m_i_n_a_t_e_d _u_n_i_o_n_. _T_h_e _u_n_i_o_n_'_s _* _d_i_s_c_r_i_m_i_n_a_n_t _i_s _a _m_s_g___t_y_p_e _w_h_i_c_h _s_w_i_t_c_h_e_s _t_o _o_n_e _o_f _t_h_e _t_w_o _* _t_y_p_e_s _o_f _t_h_e _m_e_s_s_a_g_e_. _T_h_e _x_i_d _o_f _a _R_E_P_L_Y _m_e_s_s_a_g_e _a_l_w_a_y_s _* _m_a_t_c_h_e_s _t_h_a_t _o_f _t_h_e _i_n_i_t_i_a_t_i_n_g _C_A_L_L _m_e_s_s_a_g_e_. _N_B_: _T_h_e _x_i_d _* _f_i_e_l_d _i_s _o_n_l_y _u_s_e_d _f_o_r _c_l_i_e_n_t_s _m_a_t_c_h_i_n_g _r_e_p_l_y _m_e_s_s_a_g_e_s _w_i_t_h _* _c_a_l_l _m_e_s_s_a_g_e_s _o_r _f_o_r _s_e_r_v_e_r_s _d_e_t_e_c_t_i_n_g _r_e_t_r_a_n_s_m_i_s_s_i_o_n_s_; _t_h_e _* _s_e_r_v_i_c_e _s_i_d_e _c_a_n_n_o_t _t_r_e_a_t _t_h_i_s _i_d _a_s _a_n_y _t_y_p_e _o_f _s_e_q_u_e_n_c_e _* _n_u_m_b_e_r_. _*_/ _s_t_r_u_c_t _r_p_c___m_s_g _{ _u_n_s_i_g_n_e_d _i_n_t _x_i_d_; _u_n_i_o_n _s_w_i_t_c_h _(_m_s_g___t_y_p_e _m_t_y_p_e_) _{ _c_a_s_e _C_A_L_L_: _c_a_l_l___b_o_d_y _c_b_o_d_y_; _c_a_s_e _R_E_P_L_Y_: _r_e_p_l_y___b_o_d_y _r_b_o_d_y_; _} _b_o_d_y_; _}_; _/_* _* _B_o_d_y _o_f _a_n _R_P_C _r_e_q_u_e_s_t _c_a_l_l_: _* _I_n _v_e_r_s_i_o_n _2 _o_f _t_h_e _R_P_C _p_r_o_t_o_c_o_l _s_p_e_c_i_f_i_c_a_t_i_o_n_, _r_p_c_v_e_r_s _m_u_s_t _* _b_e _e_q_u_a_l _t_o _2_. _T_h_e _f_i_e_l_d_s _p_r_o_g_, _v_e_r_s_, _a_n_d _p_r_o_c _s_p_e_c_i_f_y _t_h_e _* _r_e_m_o_t_e _p_r_o_g_r_a_m_, _i_t_s _v_e_r_s_i_o_n _n_u_m_b_e_r_, _a_n_d _t_h_e _p_r_o_c_e_d_u_r_e _w_i_t_h_i_n _* _t_h_e _r_e_m_o_t_e _p_r_o_g_r_a_m _t_o _b_e _c_a_l_l_e_d_. _A_f_t_e_r _t_h_e_s_e _f_i_e_l_d_s _a_r_e _t_w_o _* _a_u_t_h_e_n_t_i_c_a_t_i_o_n _p_a_r_a_m_e_t_e_r_s_: _c_r_e_d _(_a_u_t_h_e_n_t_i_c_a_t_i_o_n _c_r_e_d_e_n_t_i_a_l_s_) _* _a_n_d _v_e_r_f _(_a_u_t_h_e_n_t_i_c_a_t_i_o_n _v_e_r_i_f_i_e_r_)_. _T_h_e _t_w_o _a_u_t_h_e_n_t_i_c_a_t_i_o_n _* _p_a_r_a_m_e_t_e_r_s _a_r_e _f_o_l_l_o_w_e_d _b_y _t_h_e _p_a_r_a_m_e_t_e_r_s _t_o _t_h_e _r_e_m_o_t_e _* _p_r_o_c_e_d_u_r_e_, _w_h_i_c_h _a_r_e _s_p_e_c_i_f_i_e_d _b_y _t_h_e _s_p_e_c_i_f_i_c _p_r_o_g_r_a_m _* _p_r_o_t_o_c_o_l_. _*_/ _s_t_r_u_c_t _c_a_l_l___b_o_d_y _{ _u_n_s_i_g_n_e_d _i_n_t _r_p_c_v_e_r_s_; _/_* _m_u_s_t _b_e _e_q_u_a_l _t_o _t_w_o _(_2_) _*_/ _u_n_s_i_g_n_e_d _i_n_t _p_r_o_g_; _u_n_s_i_g_n_e_d _i_n_t _v_e_r_s_; _u_n_s_i_g_n_e_d _i_n_t _p_r_o_c_; _o_p_a_q_u_e___a_u_t_h _c_r_e_d_; _o_p_a_q_u_e___a_u_t_h _v_e_r_f_; _/_* _p_r_o_c_e_d_u_r_e _s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s _s_t_a_r_t _h_e_r_e _*_/ _}_; Page 10 Remote Procedure Calls: Protocol Specification _/_* _* _B_o_d_y _o_f _a _r_e_p_l_y _t_o _a_n _R_P_C _r_e_q_u_e_s_t_: _* _T_h_e _c_a_l_l _m_e_s_s_a_g_e _w_a_s _e_i_t_h_e_r _a_c_c_e_p_t_e_d _o_r _r_e_j_e_c_t_e_d_. _*_/ _u_n_i_o_n _r_e_p_l_y___b_o_d_y _s_w_i_t_c_h _(_r_e_p_l_y___s_t_a_t _s_t_a_t_) _{ _c_a_s_e _M_S_G___A_C_C_E_P_T_E_D_: _a_c_c_e_p_t_e_d___r_e_p_l_y _a_r_e_p_l_y_; _c_a_s_e _M_S_G___D_E_N_I_E_D_: _r_e_j_e_c_t_e_d___r_e_p_l_y _r_r_e_p_l_y_; _} _r_e_p_l_y_; _/_* _* _R_e_p_l_y _t_o _a_n _R_P_C _r_e_q_u_e_s_t _t_h_a_t _w_a_s _a_c_c_e_p_t_e_d _b_y _t_h_e _s_e_r_v_e_r_: _* _t_h_e_r_e _c_o_u_l_d _b_e _a_n _e_r_r_o_r _e_v_e_n _t_h_o_u_g_h _t_h_e _r_e_q_u_e_s_t _w_a_s _a_c_c_e_p_t_e_d_. _* _T_h_e _f_i_r_s_t _f_i_e_l_d _i_s _a_n _a_u_t_h_e_n_t_i_c_a_t_i_o_n _v_e_r_i_f_i_e_r _t_h_a_t _t_h_e _s_e_r_v_e_r _* _g_e_n_e_r_a_t_e_s _i_n _o_r_d_e_r _t_o _v_a_l_i_d_a_t_e _i_t_s_e_l_f _t_o _t_h_e _c_a_l_l_e_r_. _I_t _i_s _* _f_o_l_l_o_w_e_d _b_y _a _u_n_i_o_n _w_h_o_s_e _d_i_s_c_r_i_m_i_n_a_n_t _i_s _a_n _e_n_u_m _* _a_c_c_e_p_t___s_t_a_t_. _T_h_e _S_U_C_C_E_S_S _a_r_m _o_f _t_h_e _u_n_i_o_n _i_s _p_r_o_t_o_c_o_l _* _s_p_e_c_i_f_i_c_. _T_h_e _P_R_O_G___U_N_A_V_A_I_L_, _P_R_O_C___U_N_A_V_A_I_L_, _a_n_d _G_A_R_B_A_G_E___A_R_G_P _* _a_r_m_s _o_f _t_h_e _u_n_i_o_n _a_r_e _v_o_i_d_. _T_h_e _P_R_O_G___M_I_S_M_A_T_C_H _a_r_m _s_p_e_c_i_f_i_e_s _* _t_h_e _l_o_w_e_s_t _a_n_d _h_i_g_h_e_s_t _v_e_r_s_i_o_n _n_u_m_b_e_r_s _o_f _t_h_e _r_e_m_o_t_e _p_r_o_g_r_a_m _* _s_u_p_p_o_r_t_e_d _b_y _t_h_e _s_e_r_v_e_r_. _*_/ _s_t_r_u_c_t _a_c_c_e_p_t_e_d___r_e_p_l_y _{ _o_p_a_q_u_e___a_u_t_h _v_e_r_f_; _u_n_i_o_n _s_w_i_t_c_h _(_a_c_c_e_p_t___s_t_a_t _s_t_a_t_) _{ _c_a_s_e _S_U_C_C_E_S_S_: _o_p_a_q_u_e _r_e_s_u_l_t_s_[_0_]_; _/_* _p_r_o_c_e_d_u_r_e_-_s_p_e_c_i_f_i_c _r_e_s_u_l_t_s _s_t_a_r_t _h_e_r_e _*_/ _c_a_s_e _P_R_O_G___M_I_S_M_A_T_C_H_: _s_t_r_u_c_t _{ _u_n_s_i_g_n_e_d _i_n_t _l_o_w_; _u_n_s_i_g_n_e_d _i_n_t _h_i_g_h_; _} _m_i_s_m_a_t_c_h___i_n_f_o_; _d_e_f_a_u_l_t_: _/_* _* _V_o_i_d_. _C_a_s_e_s _i_n_c_l_u_d_e _P_R_O_G___U_N_A_V_A_I_L_, _P_R_O_C___U_N_A_V_A_I_L_, _* _a_n_d _G_A_R_B_A_G_E___A_R_G_S_. _*_/ _v_o_i_d_; _} _r_e_p_l_y___d_a_t_a_; _}_; Remote Procedure Calls: Protocol Specification Page 11 _/_* _* _R_e_p_l_y _t_o _a_n _R_P_C _r_e_q_u_e_s_t _t_h_a_t _w_a_s _r_e_j_e_c_t_e_d _b_y _t_h_e _s_e_r_v_e_r_: _* _T_h_e _r_e_q_u_e_s_t _c_a_n _b_e _r_e_j_e_c_t_e_d _f_o_r _t_w_o _r_e_a_s_o_n_s_: _e_i_t_h_e_r _t_h_e _* _s_e_r_v_e_r _i_s _n_o_t _r_u_n_n_i_n_g _a _c_o_m_p_a_t_i_b_l_e _v_e_r_s_i_o_n _o_f _t_h_e _R_P_C _* _p_r_o_t_o_c_o_l _(_R_P_C___M_I_S_M_A_T_C_H_)_, _o_r _t_h_e _s_e_r_v_e_r _r_e_f_u_s_e_s _t_o _* _a_u_t_h_e_n_t_i_c_a_t_e _t_h_e _c_a_l_l_e_r _(_A_U_T_H___E_R_R_O_R_)_. _I_n _c_a_s_e _o_f _a_n _R_P_C _* _v_e_r_s_i_o_n _m_i_s_m_a_t_c_h_, _t_h_e _s_e_r_v_e_r _r_e_t_u_r_n_s _t_h_e _l_o_w_e_s_t _a_n_d _h_i_g_h_e_s_t _* _s_u_p_p_o_r_t_e_d _R_P_C _v_e_r_s_i_o_n _n_u_m_b_e_r_s_. _I_n _c_a_s_e _o_f _r_e_f_u_s_e_d _* _a_u_t_h_e_n_t_i_c_a_t_i_o_n_, _f_a_i_l_u_r_e _s_t_a_t_u_s _i_s _r_e_t_u_r_n_e_d_. _*_/ _u_n_i_o_n _r_e_j_e_c_t_e_d___r_e_p_l_y _s_w_i_t_c_h _(_r_e_j_e_c_t___s_t_a_t _s_t_a_t_) _{ _c_a_s_e _R_P_C___M_I_S_M_A_T_C_H_: _s_t_r_u_c_t _{ _u_n_s_i_g_n_e_d _i_n_t _l_o_w_; _u_n_s_i_g_n_e_d _i_n_t _h_i_g_h_; _} _m_i_s_m_a_t_c_h___i_n_f_o_; _c_a_s_e _A_U_T_H___E_R_R_O_R_: _a_u_t_h___s_t_a_t _s_t_a_t_; _}_; 55.. AAuutthheennttiiccaattiioonn PPrroottooccoollss As previously stated, authentication parameters are opaque, but open-ended to the rest of the RPC protocol. This sec- tion defines some "flavors" of authentication implemented at (and supported by) Sun. Other sites are free to invent new authentication types, with the same rules of flavor number assignment as there is for program number assignment. 55..11.. NNuullll AAuutthheennttiiccaattiioonn Often calls must be made where the caller does not know who he is or the server does not care who the caller is. In this case, the flavor value (the discriminant of the _o_p_a_q_u_e___a_u_t_h's union) of the RPC message's credentials, veri- fier, and response verifier is _A_U_T_H___N_U_L_L. The bytes of the opaque_auth's body are undefined. It is recommended that the opaque length be zero. 55..22.. UUNNIIXX AAuutthheennttiiccaattiioonn The caller of a remote procedure may wish to identify him- self as he is identified on a UNIX system. The value of the credential's discriminant of an RPC call message is _A_U_T_H___U_N_I_X. The bytes of the credential's opaque body encode the following structure: Page 12 Remote Procedure Calls: Protocol Specification struct auth_unix { unsigned int stamp; string machinename<255>; unsigned int uid; unsigned int gid; unsigned int gids<10>; }; The _s_t_a_m_p is an arbitrary ID which the caller machine may generate. The _m_a_c_h_i_n_e_n_a_m_e is the name of the caller's machine (like "krypton"). The _u_i_d is the caller's effec- tive user ID. The _g_i_d is the caller's effective group ID. The _g_i_d_s is a counted array of groups which contain the caller as a member. The verifier accompanying the credentials should be of _A_U_T_H___N_U_L_L (defined above). The value of the discriminant of the response verifier received in the reply message from the server may be _A_U_T_H___N_U_L_L or _A_U_T_H___S_H_O_R_T. In the case of _A_U_T_H___S_H_O_R_T, the bytes of the response verifier's string encode an opaque structure. This new opaque structure may now be passed to the server instead of the original _A_U_T_H___U_N_I_X flavor creden- tials. The server keeps a cache which maps shorthand opaque structures (passed back by way of an _A_U_T_H___S_H_O_R_T style response verifier) to the original credentials of the caller. The caller can save network bandwidth and server cpu cycles by using the new credentials. The server may flush the shorthand opaque structure at any time. If this happens, the remote procedure call message will be rejected due to an authentication error. The reason for the failure will be _A_U_T_H___R_E_J_E_C_T_E_D_C_R_E_D. At this point, the caller may wish to try the original _A_U_T_H___U_N_I_X style of credentials. 55..33.. DDEESS AAuutthheennttiiccaattiioonn UNIX authentication suffers from two major problems: 1. The naming is too UNIX-system oriented. 2. There is no verifier, so credentials can easily be faked. DES authentication attempts to fix these two problems. 55..33..11.. NNaammiinngg The first problem is handled by addressing the caller by a simple string of characters instead of by an operating sys- tem specific integer. This string of characters is known as the "netname" or network name of the caller. The server is not allowed to interpret the contents of the caller's name in any other way except to identify the caller. Thus, Remote Procedure Calls: Protocol Specification Page 13 netnames should be unique for every caller in the internet. It is up to each operating system's implementation of DES authentication to generate netnames for its users that insure this uniqueness when they call upon remote servers. Operating systems already know how to distinguish users local to their systems. It is usually a simple matter to extend this mechanism to the network. For example, a UNIX user at Sun with a user ID of 515 might be assigned the fol- lowing netname: "unix.515@sun.com". This netname contains three items that serve to insure it is unique. Going back- wards, there is only one naming domain called "sun.com" in the internet. Within this domain, there is only one UNIX user with user ID 515. However, there may be another user on another operating system, for example VMS, within the same naming domain that, by coincidence, happens to have the same user ID. To insure that these two users can be distin- guished we add the operating system name. So one user is "unix.515@sun.com" and the other is "vms.515@sun.com". The first field is actually a naming method rather than an operating system name. It just happens that today there is almost a one-to-one correspondence between naming methods and operating systems. If the world could agree on a naming standard, the first field could be the name of that stan- dard, instead of an operating system name. 55..33..22.. DDEESS AAuutthheennttiiccaattiioonn VVeerriiffiieerrss Unlike UNIX authentication, DES authentication does have a verifier so the server can validate the client's credential (and vice-versa). The contents of this verifier is primar- ily an encrypted timestamp. The server can decrypt this timestamp, and if it is close to what the real time is, then the client must have encrypted it correctly. The only way the client could encrypt it correctly is to know the "con- versation key" of the RPC session. And if the client knows the conversation key, then it must be the real client. The conversation key is a DES [5] key which the client gen- erates and notifies the server of in its first RPC call. The conversation key is encrypted using a public key scheme in this first transaction. The particular public key scheme used in DES authentication is Diffie-Hellman [3] with 192-bit keys. The details of this encryption method are described later. The client and the server need the same notion of the cur- rent time in order for all of this to work. If network time synchronization cannot be guaranteed, then client can syn- chronize with the server before beginning the conversation, perhaps by consulting the Internet Time Server (TIME[4]). Page 14 Remote Procedure Calls: Protocol Specification The way a server determines if a client timestamp is valid is somewhat complicated. For any other transaction but the first, the server just checks for two things: 1. the timestamp is greater than the one previously seen from the same client. 2. the timestamp has not expired. A timestamp is expired if the server's time is later than the sum of the client's timestamp plus what is known as the client's "window". The "window" is a number the client passes (encrypted) to the server in its first transaction. You can think of it as a lifetime for the credential. This explains everything but the first transaction. In the first transaction, the server checks only that the timestamp has not expired. If this was all that was done though, then it would be quite easy for the client to send random data in place of the timestamp with a fairly good chance of succeed- ing. As an added check, the client sends an encrypted item in the first transaction known as the "window verifier" which must be equal to the window minus 1, or the server will reject the credential. The client too must check the verifier returned from the server to be sure it is legitimate. The server sends back to the client the encrypted timestamp it received from the client, minus one second. If the client gets anything dif- ferent than this, it will reject it. 55..33..33.. NNiicckknnaammeess aanndd CClloocckk SSyynncchhrroonniizzaattiioonn After the first transaction, the server's DES authentication subsystem returns in its verifier to the client an integer "nickname" which the client may use in its further transac- tions instead of passing its netname, encrypted DES key and window every time. The nickname is most likely an index into a table on the server which stores for each client its netname, decrypted DES key and window. Though they originally were synchronized, the client's and server's clocks can get out of sync again. When this hap- pens the client RPC subsystem most likely will get back _R_P_C___A_U_T_H_E_R_R_O_R at which point it should resynchronize. A client may still get the _R_P_C___A_U_T_H_E_R_R_O_R error even though it is synchronized with the server. The reason is that the server's nickname table is a limited size, and it may flush entries whenever it wants. A client should resend its orig- inal credential in this case and the server will give it a new nickname. If a server crashes, the entire nickname table gets flushed, and all clients will have to resend Remote Procedure Calls: Protocol Specification Page 15 their original credentials. Page 16 Remote Procedure Calls: Protocol Specification 55..33..44.. DDEESS AAuutthheennttiiccaattiioonn PPrroottooccooll ((iinn XXDDRR llaanngguuaaggee)) _/_* _* _T_h_e_r_e _a_r_e _t_w_o _k_i_n_d_s _o_f _c_r_e_d_e_n_t_i_a_l_s_: _o_n_e _i_n _w_h_i_c_h _t_h_e _c_l_i_e_n_t _u_s_e_s _* _i_t_s _f_u_l_l _n_e_t_w_o_r_k _n_a_m_e_, _a_n_d _o_n_e _i_n _w_h_i_c_h _i_t _u_s_e_s _i_t_s _"_n_i_c_k_n_a_m_e_" _* _(_j_u_s_t _a_n _u_n_s_i_g_n_e_d _i_n_t_e_g_e_r_) _g_i_v_e_n _t_o _i_t _b_y _t_h_e _s_e_r_v_e_r_. _T_h_e _* _c_l_i_e_n_t _m_u_s_t _u_s_e _i_t_s _f_u_l_l_n_a_m_e _i_n _i_t_s _f_i_r_s_t _t_r_a_n_s_a_c_t_i_o_n _w_i_t_h _t_h_e _* _s_e_r_v_e_r_, _i_n _w_h_i_c_h _t_h_e _s_e_r_v_e_r _w_i_l_l _r_e_t_u_r_n _t_o _t_h_e _c_l_i_e_n_t _i_t_s _* _n_i_c_k_n_a_m_e_. _T_h_e _c_l_i_e_n_t _m_a_y _u_s_e _i_t_s _n_i_c_k_n_a_m_e _i_n _a_l_l _f_u_r_t_h_e_r _* _t_r_a_n_s_a_c_t_i_o_n_s _w_i_t_h _t_h_e _s_e_r_v_e_r_. _T_h_e_r_e _i_s _n_o _r_e_q_u_i_r_e_m_e_n_t _t_o _u_s_e _t_h_e _* _n_i_c_k_n_a_m_e_, _b_u_t _i_t _i_s _w_i_s_e _t_o _u_s_e _i_t _f_o_r _p_e_r_f_o_r_m_a_n_c_e _r_e_a_s_o_n_s_. _*_/ _e_n_u_m _a_u_t_h_d_e_s___n_a_m_e_k_i_n_d _{ _A_D_N___F_U_L_L_N_A_M_E _= _0_, _A_D_N___N_I_C_K_N_A_M_E _= _1 _}_; _/_* _* _A _6_4_-_b_i_t _b_l_o_c_k _o_f _e_n_c_r_y_p_t_e_d _D_E_S _d_a_t_a _*_/ _t_y_p_e_d_e_f _o_p_a_q_u_e _d_e_s___b_l_o_c_k_[_8_]_; _/_* _* _M_a_x_i_m_u_m _l_e_n_g_t_h _o_f _a _n_e_t_w_o_r_k _u_s_e_r_'_s _n_a_m_e _*_/ _c_o_n_s_t _M_A_X_N_E_T_N_A_M_E_L_E_N _= _2_5_5_; _/_* _* _A _f_u_l_l_n_a_m_e _c_o_n_t_a_i_n_s _t_h_e _n_e_t_w_o_r_k _n_a_m_e _o_f _t_h_e _c_l_i_e_n_t_, _a_n _e_n_c_r_y_p_t_e_d _* _c_o_n_v_e_r_s_a_t_i_o_n _k_e_y _a_n_d _t_h_e _w_i_n_d_o_w_. _T_h_e _w_i_n_d_o_w _i_s _a_c_t_u_a_l_l_y _a _* _l_i_f_e_t_i_m_e _f_o_r _t_h_e _c_r_e_d_e_n_t_i_a_l_. _I_f _t_h_e _t_i_m_e _i_n_d_i_c_a_t_e_d _i_n _t_h_e _* _v_e_r_i_f_i_e_r _t_i_m_e_s_t_a_m_p _p_l_u_s _t_h_e _w_i_n_d_o_w _h_a_s _p_a_s_t_, _t_h_e_n _t_h_e _s_e_r_v_e_r _* _s_h_o_u_l_d _e_x_p_i_r_e _t_h_e _r_e_q_u_e_s_t _a_n_d _n_o_t _g_r_a_n_t _i_t_. _T_o _i_n_s_u_r_e _t_h_a_t _* _r_e_q_u_e_s_t_s _a_r_e _n_o_t _r_e_p_l_a_y_e_d_, _t_h_e _s_e_r_v_e_r _s_h_o_u_l_d _i_n_s_i_s_t _t_h_a_t _* _t_i_m_e_s_t_a_m_p_s _a_r_e _g_r_e_a_t_e_r _t_h_a_n _t_h_e _p_r_e_v_i_o_u_s _o_n_e _s_e_e_n_, _u_n_l_e_s_s _i_t _i_s _* _t_h_e _f_i_r_s_t _t_r_a_n_s_a_c_t_i_o_n_. _I_n _t_h_e _f_i_r_s_t _t_r_a_n_s_a_c_t_i_o_n_, _t_h_e _s_e_r_v_e_r _* _c_h_e_c_k_s _i_n_s_t_e_a_d _t_h_a_t _t_h_e _w_i_n_d_o_w _v_e_r_i_f_i_e_r _i_s _o_n_e _l_e_s_s _t_h_a_n _t_h_e _* _w_i_n_d_o_w_. _*_/ _s_t_r_u_c_t _a_u_t_h_d_e_s___f_u_l_l_n_a_m_e _{ _s_t_r_i_n_g _n_a_m_e_<_M_A_X_N_E_T_N_A_M_E_L_E_N_>_; _/_* _n_a_m_e _o_f _c_l_i_e_n_t _*_/ _d_e_s___b_l_o_c_k _k_e_y_; _/_* _P_K _e_n_c_r_y_p_t_e_d _c_o_n_v_e_r_s_a_t_i_o_n _k_e_y _*_/ _u_n_s_i_g_n_e_d _i_n_t _w_i_n_d_o_w_; _/_* _e_n_c_r_y_p_t_e_d _w_i_n_d_o_w _*_/ _}_; _/_* _* _A _c_r_e_d_e_n_t_i_a_l _i_s _e_i_t_h_e_r _a _f_u_l_l_n_a_m_e _o_r _a _n_i_c_k_n_a_m_e _*_/ _u_n_i_o_n _a_u_t_h_d_e_s___c_r_e_d _s_w_i_t_c_h _(_a_u_t_h_d_e_s___n_a_m_e_k_i_n_d _a_d_c___n_a_m_e_k_i_n_d_) _{ _c_a_s_e _A_D_N___F_U_L_L_N_A_M_E_: _a_u_t_h_d_e_s___f_u_l_l_n_a_m_e _a_d_c___f_u_l_l_n_a_m_e_; _c_a_s_e _A_D_N___N_I_C_K_N_A_M_E_: _u_n_s_i_g_n_e_d _i_n_t _a_d_c___n_i_c_k_n_a_m_e_; _}_; Remote Procedure Calls: Protocol Specification Page 17 _/_* _* _A _t_i_m_e_s_t_a_m_p _e_n_c_o_d_e_s _t_h_e _t_i_m_e _s_i_n_c_e _m_i_d_n_i_g_h_t_, _J_a_n_u_a_r_y _1_, _1_9_7_0_. _*_/ _s_t_r_u_c_t _t_i_m_e_s_t_a_m_p _{ _u_n_s_i_g_n_e_d _i_n_t _s_e_c_o_n_d_s_; _/_* _s_e_c_o_n_d_s _*_/ _u_n_s_i_g_n_e_d _i_n_t _u_s_e_c_o_n_d_s_; _/_* _a_n_d _m_i_c_r_o_s_e_c_o_n_d_s _*_/ _}_; _/_* _* _V_e_r_i_f_i_e_r_: _c_l_i_e_n_t _v_a_r_i_e_t_y _* _T_h_e _w_i_n_d_o_w _v_e_r_i_f_i_e_r _i_s _o_n_l_y _u_s_e_d _i_n _t_h_e _f_i_r_s_t _t_r_a_n_s_a_c_t_i_o_n_. _I_n _* _c_o_n_j_u_n_c_t_i_o_n _w_i_t_h _a _f_u_l_l_n_a_m_e _c_r_e_d_e_n_t_i_a_l_, _t_h_e_s_e _i_t_e_m_s _a_r_e _p_a_c_k_e_d _* _i_n_t_o _t_h_e _f_o_l_l_o_w_i_n_g _s_t_r_u_c_t_u_r_e _b_e_f_o_r_e _b_e_i_n_g _e_n_c_r_y_p_t_e_d_: _* _* _s_t_r_u_c_t _{ _* _a_d_v___t_i_m_e_s_t_a_m_p_; _-_- _o_n_e _D_E_S _b_l_o_c_k _* _a_d_c___f_u_l_l_n_a_m_e_._w_i_n_d_o_w_; _-_- _o_n_e _h_a_l_f _D_E_S _b_l_o_c_k _* _a_d_v___w_i_n_v_e_r_f_; _-_- _o_n_e _h_a_l_f _D_E_S _b_l_o_c_k _* _} _* _T_h_i_s _s_t_r_u_c_t_u_r_e _i_s _e_n_c_r_y_p_t_e_d _u_s_i_n_g _C_B_C _m_o_d_e _e_n_c_r_y_p_t_i_o_n _w_i_t_h _a_n _* _i_n_p_u_t _v_e_c_t_o_r _o_f _z_e_r_o_. _A_l_l _o_t_h_e_r _e_n_c_r_y_p_t_i_o_n_s _o_f _t_i_m_e_s_t_a_m_p_s _u_s_e _* _E_C_B _m_o_d_e _e_n_c_r_y_p_t_i_o_n_. _*_/ _s_t_r_u_c_t _a_u_t_h_d_e_s___v_e_r_f___c_l_n_t _{ _t_i_m_e_s_t_a_m_p _a_d_v___t_i_m_e_s_t_a_m_p_; _/_* _e_n_c_r_y_p_t_e_d _t_i_m_e_s_t_a_m_p _*_/ _u_n_s_i_g_n_e_d _i_n_t _a_d_v___w_i_n_v_e_r_f_; _/_* _e_n_c_r_y_p_t_e_d _w_i_n_d_o_w _v_e_r_i_f_i_e_r _*_/ _}_; _/_* _* _V_e_r_i_f_i_e_r_: _s_e_r_v_e_r _v_a_r_i_e_t_y _* _T_h_e _s_e_r_v_e_r _r_e_t_u_r_n_s _(_e_n_c_r_y_p_t_e_d_) _t_h_e _s_a_m_e _t_i_m_e_s_t_a_m_p _t_h_e _c_l_i_e_n_t _* _g_a_v_e _i_t _m_i_n_u_s _o_n_e _s_e_c_o_n_d_. _I_t _a_l_s_o _t_e_l_l_s _t_h_e _c_l_i_e_n_t _i_t_s _n_i_c_k_n_a_m_e _* _t_o _b_e _u_s_e_d _i_n _f_u_t_u_r_e _t_r_a_n_s_a_c_t_i_o_n_s _(_u_n_e_n_c_r_y_p_t_e_d_)_. _*_/ _s_t_r_u_c_t _a_u_t_h_d_e_s___v_e_r_f___s_v_r _{ _t_i_m_e_s_t_a_m_p _a_d_v___t_i_m_e_v_e_r_f_; _/_* _e_n_c_r_y_p_t_e_d _v_e_r_i_f_i_e_r _*_/ _u_n_s_i_g_n_e_d _i_n_t _a_d_v___n_i_c_k_n_a_m_e_; _/_* _n_e_w _n_i_c_k_n_a_m_e _f_o_r _c_l_i_e_n_t _*_/ _}_; 55..33..55.. DDiiffffiiee--HHeellllmmaann EEnnccrryyppttiioonn In this scheme, there are two constants, _B_A_S_E and _M_O_D_U_L_U_S. The particular values Sun has chosen for these for the DES authentication protocol are: const BASE = 3; const MODULUS = "d4a0ba0250b6fd2ec626e7efd637df76c716e22d0944b88b"; /* _h_e_x */ The way this scheme works is best explained by an example. Suppose there are two people "A" and "B" who want to send encrypted messages to each other. So, A and B both generate "secret" keys at random which they do not reveal to anyone. Page 18 Remote Procedure Calls: Protocol Specification Let these keys be represented as SK(A) and SK(B). They also publish in a public directory their "public" keys. These keys are computed as follows: PK(A) = ( BASE ** SK(A) ) mod MODULUS PK(B) = ( BASE ** SK(B) ) mod MODULUS The "**" notation is used here to represent exponentiation. Now, both A and B can arrive at the "common" key between them, represented here as CK(A, B), without revealing their secret keys. A computes: CK(A, B) = ( PK(B) ** SK(A)) mod MODULUS while B computes: CK(A, B) = ( PK(A) ** SK(B)) mod MODULUS These two can be shown to be equivalent: (PK(B) ** SK(A)) mod MODULUS = (PK(A) ** SK(B)) mod MODULUS We drop the "mod MODULUS" parts and assume modulo arithmetic to simplify things: PK(B) ** SK(A) = PK(A) ** SK(B) Then, replace PK(B) by what B computed earlier and likewise for PK(A). ((BASE ** SK(B)) ** SK(A) = (BASE ** SK(A)) ** SK(B) which leads to: BASE ** (SK(A) * SK(B)) = BASE ** (SK(A) * SK(B)) This common key CK(A, B) is not used to encrypt the times- tamps used in the protocol. Rather, it is used only to encrypt a conversation key which is then used to encrypt the timestamps. The reason for doing this is to use the common key as little as possible, for fear that it could be broken. Breaking the conversation key is a far less serious offense, since conversations are relatively short-lived. The conversation key is encrypted using 56-bit DES keys, yet the common key is 192 bits. To reduce the number of bits, 56 bits are selected from the common key as follows. The middle-most 8-bytes are selected from the common key, and then parity is added to the lower order bit of each byte, producing a 56-bit key with 8 bits of parity. Remote Procedure Calls: Protocol Specification Page 19 66.. RReeccoorrdd MMaarrkkiinngg SSttaannddaarrdd When RPC messages are passed on top of a byte stream proto- col (like TCP/IP), it is necessary, or at least desirable, to delimit one message from another in order to detect and possibly recover from user protocol errors. This is called record marking (RM). Sun uses this RM/TCP/IP transport for passing RPC messages on TCP streams. One RPC message fits into one RM record. A record is composed of one or more record fragments. A record fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of fragment data. The bytes encode an unsigned binary number; as with XDR integers, the byte order is from highest to lowest. The number encodes two values--a boolean which indicates whether the fragment is the last fragment of the record (bit value 1 implies the fragment is the last fragment) and a 31-bit unsigned binary value which is the length in bytes of the fragment's data. The boolean value is the highest-order bit of the header; the length is the 31 low-order bits. (Note that this record specification is NOT in XDR standard form!) Page 20 Remote Procedure Calls: Protocol Specification 77.. TThhee RRPPCC LLaanngguuaaggee Just as there was a need to describe the XDR data-types in a formal language, there is also need to describe the proce- dures that operate on these XDR data-types in a formal lan- guage as well. We use the RPC Language for this purpose. It is an extension to the XDR language. The following exam- ple is used to describe the essence of the language. 77..11.. AAnn EExxaammppllee SSeerrvviiccee DDeessccrriibbeedd iinn tthhee RRPPCC LLaanngguuaaggee Here is an example of the specification of a simple ping program. _/_* _* _S_i_m_p_l_e _p_i_n_g _p_r_o_g_r_a_m _*_/ _p_r_o_g_r_a_m _P_I_N_G___P_R_O_G _{ _/_* _L_a_t_e_s_t _a_n_d _g_r_e_a_t_e_s_t _v_e_r_s_i_o_n _*_/ _v_e_r_s_i_o_n _P_I_N_G___V_E_R_S___P_I_N_G_B_A_C_K _{ _v_o_i_d _P_I_N_G_P_R_O_C___N_U_L_L_(_v_o_i_d_) _= _0_; _/_* _* _P_i_n_g _t_h_e _c_a_l_l_e_r_, _r_e_t_u_r_n _t_h_e _r_o_u_n_d_-_t_r_i_p _t_i_m_e _* _(_i_n _m_i_c_r_o_s_e_c_o_n_d_s_)_. _R_e_t_u_r_n_s _-_1 _i_f _t_h_e _o_p_e_r_a_t_i_o_n _* _t_i_m_e_d _o_u_t_. _*_/ _i_n_t _P_I_N_G_P_R_O_C___P_I_N_G_B_A_C_K_(_v_o_i_d_) _= _1_; _} _= _2_; _/_* _* _O_r_i_g_i_n_a_l _v_e_r_s_i_o_n _*_/ _v_e_r_s_i_o_n _P_I_N_G___V_E_R_S___O_R_I_G _{ _v_o_i_d _P_I_N_G_P_R_O_C___N_U_L_L_(_v_o_i_d_) _= _0_; _} _= _1_; _} _= _1_; _c_o_n_s_t _P_I_N_G___V_E_R_S _= _2_; _/_* _l_a_t_e_s_t _v_e_r_s_i_o_n _*_/ The first version described is _P_I_N_G___V_E_R_S___P_I_N_G_B_A_C_K with two procedures, _P_I_N_G_P_R_O_C___N_U_L_L and _P_I_N_G_P_R_O_C___P_I_N_G_B_A_C_K. _P_I_N_G_- _P_R_O_C___N_U_L_L takes no arguments and returns no results, but it is useful for computing round-trip times from the client to the server and back again. By convention, procedure 0 of any RPC protocol should have the same semantics, and never require any kind of authentication. The second procedure is used for the client to have the server do a reverse ping operation back to the client, and it returns the amount of time (in microseconds) that the operation used. The next Remote Procedure Calls: Protocol Specification Page 21 version, _P_I_N_G___V_E_R_S___O_R_I_G, is the original version of the pro- tocol and it does not contain _P_I_N_G_P_R_O_C___P_I_N_G_B_A_C_K procedure. It is useful for compatibility with old client programs, and as this program matures it may be dropped from the pro- tocol entirely. 77..22.. TThhee RRPPCC LLaanngguuaaggee SSppeecciiffiiccaattiioonn The RPC language is identical to the XDR language, except for the added definition of a _p_r_o_g_r_a_m_-_d_e_f described below. program-def: "program" identifier "{" version-def version-def * "}" "=" constant ";" version-def: "version" identifier "{" procedure-def procedure-def * "}" "=" constant ";" procedure-def: type-specifier identifier "(" type-specifier ")" "=" constant ";" 77..33.. SSyynnttaaxx NNootteess 1. The following keywords are added and cannot be used as identifiers: "program" and "version"; 2. A version name cannot occur more than once within the scope of a program definition. Nor can a version number occur more than once within the scope of a program def- inition. 3. A procedure name cannot occur more than once within the scope of a version definition. Nor can a procedure number occur more than once within the scope of version definition. 4. Program identifiers are in the same name space as con- stant and type identifiers. 5. Only unsigned constants can be assigned to programs, versions and procedures. 88.. PPoorrtt MMaappppeerr PPrrooggrraamm PPrroottooccooll The port mapper program maps RPC program and version numbers to transport-specific port numbers. This program makes dynamic binding of remote programs possible. Page 22 Remote Procedure Calls: Protocol Specification This is desirable because the range of reserved port numbers is very small and the number of potential remote programs is very large. By running only the port mapper on a reserved port, the port numbers of other remote programs can be ascertained by querying the port mapper. The port mapper also aids in broadcast RPC. A given RPC program will usually have different port number bindings on different machines, so there is no way to directly broadcast to all of these programs. The port mapper, however, does have a fixed port number. So, to broadcast to a given pro- gram, the client actually sends its message to the port map- per located at the broadcast address. Each port mapper that picks up the broadcast then calls the local service speci- fied by the client. When the port mapper gets the reply from the local service, it sends the reply on back to the client. Remote Procedure Calls: Protocol Specification Page 23 88..11.. PPoorrtt MMaappppeerr PPrroottooccooll SSppeecciiffiiccaattiioonn ((iinn RRPPCC LLaanngguuaaggee)) const PMAP_PORT = 111; /* _p_o_r_t_m_a_p_p_e_r _p_o_r_t _n_u_m_b_e_r */ _/_* _* _A _m_a_p_p_i_n_g _o_f _(_p_r_o_g_r_a_m_, _v_e_r_s_i_o_n_, _p_r_o_t_o_c_o_l_) _t_o _p_o_r_t _n_u_m_b_e_r _*_/ _s_t_r_u_c_t _m_a_p_p_i_n_g _{ _u_n_s_i_g_n_e_d _i_n_t _p_r_o_g_; _u_n_s_i_g_n_e_d _i_n_t _v_e_r_s_; _u_n_s_i_g_n_e_d _i_n_t _p_r_o_t_; _u_n_s_i_g_n_e_d _i_n_t _p_o_r_t_; _}_; _/_* _* _S_u_p_p_o_r_t_e_d _v_a_l_u_e_s _f_o_r _t_h_e _"_p_r_o_t_" _f_i_e_l_d _*_/ _c_o_n_s_t _I_P_P_R_O_T_O___T_C_P _= _6_; _/_* _p_r_o_t_o_c_o_l _n_u_m_b_e_r _f_o_r _T_C_P_/_I_P _*_/ _c_o_n_s_t _I_P_P_R_O_T_O___U_D_P _= _1_7_; _/_* _p_r_o_t_o_c_o_l _n_u_m_b_e_r _f_o_r _U_D_P_/_I_P _*_/ _/_* _* _A _l_i_s_t _o_f _m_a_p_p_i_n_g_s _*_/ _s_t_r_u_c_t _*_p_m_a_p_l_i_s_t _{ _m_a_p_p_i_n_g _m_a_p_; _p_m_a_p_l_i_s_t _n_e_x_t_; _}_; _/_* _* _A_r_g_u_m_e_n_t_s _t_o _c_a_l_l_i_t _*_/ _s_t_r_u_c_t _c_a_l_l___a_r_g_s _{ _u_n_s_i_g_n_e_d _i_n_t _p_r_o_g_; _u_n_s_i_g_n_e_d _i_n_t _v_e_r_s_; _u_n_s_i_g_n_e_d _i_n_t _p_r_o_c_; _o_p_a_q_u_e _a_r_g_s_<_>_; _}_; _/_* _* _R_e_s_u_l_t_s _o_f _c_a_l_l_i_t _*_/ _s_t_r_u_c_t _c_a_l_l___r_e_s_u_l_t _{ _u_n_s_i_g_n_e_d _i_n_t _p_o_r_t_; _o_p_a_q_u_e _r_e_s_<_>_; _}_; Page 24 Remote Procedure Calls: Protocol Specification _/_* _* _P_o_r_t _m_a_p_p_e_r _p_r_o_c_e_d_u_r_e_s _*_/ _p_r_o_g_r_a_m _P_M_A_P___P_R_O_G _{ _v_e_r_s_i_o_n _P_M_A_P___V_E_R_S _{ _v_o_i_d _P_M_A_P_P_R_O_C___N_U_L_L_(_v_o_i_d_) _= _0_; _b_o_o_l _P_M_A_P_P_R_O_C___S_E_T_(_m_a_p_p_i_n_g_) _= _1_; _b_o_o_l _P_M_A_P_P_R_O_C___U_N_S_E_T_(_m_a_p_p_i_n_g_) _= _2_; _u_n_s_i_g_n_e_d _i_n_t _P_M_A_P_P_R_O_C___G_E_T_P_O_R_T_(_m_a_p_p_i_n_g_) _= _3_; _p_m_a_p_l_i_s_t _P_M_A_P_P_R_O_C___D_U_M_P_(_v_o_i_d_) _= _4_; _c_a_l_l___r_e_s_u_l_t _P_M_A_P_P_R_O_C___C_A_L_L_I_T_(_c_a_l_l___a_r_g_s_) _= _5_; _} _= _2_; _} _= _1_0_0_0_0_0_; 88..22.. PPoorrtt MMaappppeerr OOppeerraattiioonn The portmapper program currently supports two protocols (UDP/IP and TCP/IP). The portmapper is contacted by talking to it on assigned port number 111 (SUNRPC [8]) on either of these protocols. The following is a description of each of the portmapper procedures: PPMMAAPPPPRROOCC__NNUULLLL:: This procedure does no work. By convention, procedure zero of any protocol takes no parameters and returns no results. PPMMAAPPPPRROOCC__SSEETT:: When a program first becomes available on a machine, it registers itself with the port mapper program on the same machine. The program passes its program number "prog", version number "vers", transport protocol num- ber "prot", and the port "port" on which it awaits ser- vice request. The procedure returns a boolean response whose value is _T_R_U_E if the procedure successfully established the mapping and _F_A_L_S_E otherwise. The pro- cedure refuses to establish a mapping if one already exists for the tuple "(prog, vers, prot)". PPMMAAPPPPRROOCC__UUNNSSEETT:: When a program becomes unavailable, it should unregis- ter itself with the port mapper program on the same Remote Procedure Calls: Protocol Specification Page 25 machine. The parameters and results have meanings identical to those of _P_M_A_P_P_R_O_C___S_E_T. The protocol and port number fields of the argument are ignored. PPMMAAPPPPRROOCC__GGEETTPPOORRTT:: Given a program number "prog", version number "vers", and transport protocol number "prot", this procedure returns the port number on which the program is await- ing call requests. A port value of zeros means the program has not been registered. The "port" field of the argument is ignored. PPMMAAPPPPRROOCC__DDUUMMPP:: This procedure enumerates all entries in the port map- per's database. The procedure takes no parameters and returns a list of program, version, protocol, and port values. PPMMAAPPPPRROOCC__CCAALLLLIITT:: This procedure allows a caller to call another remote procedure on the same machine without knowing the remote procedure's port number. It is intended for supporting broadcasts to arbitrary remote programs via the well-known port mapper's port. The parameters "prog", "vers", "proc", and the bytes of "args" are the program number, version number, procedure number, and parameters of the remote procedure. NNoottee:: 1. This procedure only sends a response if the proce- dure was successfully executed and is silent (no response) otherwise. 2. The port mapper communicates with the remote pro- gram using UDP/IP only. The procedure returns the remote program's port number, and the bytes of results are the results of the remote proce- dure. Page 26 Remote Procedure Calls: Protocol Specification 99.. RReeffeerreenncceess [1] Birrell, Andrew D. & Nelson, Bruce Jay; "Implementing Remote Procedure Calls"; XEROX CSL-83-7, October 1983. [2] Cheriton, D.; "VMTP: Versatile Message Transaction Protocol", Preliminary Version 0.3; Stanford University, January 1987. [3] Diffie & Hellman; "New Directions in Cryptography"; IEEE Transactions on Information Theory IT-22, November 1976. [4] Harrenstien, K.; "Time Server", RFC 738; Information Sciences Institute, October 1977. [5] National Bureau of Standards; "Data Encryption Stan- dard"; Federal Information Processing Standards Publication 46, January 1977. [6] Postel, J.; "Transmission Control Protocol - DARPA Internet Program Protocol Specification", RFC 793; Informa- tion Sciences Institute, September 1981. [7] Postel, J.; "User Datagram Protocol", RFC 768; Informa- tion Sciences Institute, August 1980. [8] Reynolds, J. & Postel, J.; "Assigned Numbers", RFC 923; Information Sciences Institute, October 1984.