+.OH 'RPC Protocol Spec''Page \\\\n(PN'
+.EH 'Page \\\\n(PN''RPC Protocol Spec'
+.OF 'Sun Microsystems''Release 2.0'
+.EF 'Release 2.0''Sun Microsystems'
+.RP
+.rm DY
+.TL
+.ps 20
+Remote Procedure Call
+.sp.5
+Protocol Specification
+.
+.H 1 "Introduction"
+.LP
+This document specifies a message protocol used in implementing
+Sun's Remote Procedure Call (RPC) package.
+The protocol is specified with the
+eXternal Data Representation (XDR) language.
+.LP
+This document assumes that the reader is familiar with both RPC and XDR.
+It does not attempt to justify RPC or its uses.
+Also, the casual user of RPC does not need to be
+familiar with the information in this document.
+.
+.H 2 "Terminology"
+.LP
+The document discusses servers, services,
+programs, procedures, clients and versions.
+A server is a machine where some number
+of network services are implemented.
+A service 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 Appendix 3 for an example).
+Network clients are pieces of software that initiate
+remote procedure calls to services.
+A server may support more than one version of a remote program
+in order to be forward compatible with changing protocols.
+.LP
+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 I/O,
+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.
+.H 2 "The RPC Model"
+.LP
+The remote procedure call model is similar to
+the local procedure 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 well-specified location,
+and the caller continues execution.
+.LP
+The remote procedure call is similar,
+except that one thread of control winds through two processes \(em
+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 process and waits (blocks) for a reply message.
+The call message 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 execution is resumed.
+.LP
+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.
+That is, the RPC protocol does not explicitly support
+multi-threading of caller or server processes.
+.
+.H 2 "Transports and Semantics"
+.LP
+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 only deals with the specification and interpretation of
+messages.
+.LP
+Because of transport independence,
+the RPC protocol does not attach specific semantics to the
+remote procedures or their execution. Some semantics can be inferred from (but
+should be explicitly specified by) the underlying transport protocol.
+For example, RPC message passing using UDP/IP is unreliable.
+Thus, if the caller retransmits call messages after short time-outs, the only thing he
+can infer from no reply message is that the remote procedure was executed
+zero or more times (and from a reply message, one or more times).
+On the other hand, RPC message passing using TCP/IP is reliable.
+No reply message means that the remote procedure was executed at most once,
+whereas a reply message means that the remote procedure was exactly once.
+(Note:
+At Sun, RPC is currently implemented
+on top of TCP/IP and UDP/IP transports.)
+.
+.H 2 "Binding and Rendezvous Independence"
+.LP
+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 Appendix 3.)
+.LP
+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 useful,
+using RPC to accomplish this task.
+.
+.H 2 "Message Authentication"
+.LP
+The RPC protocol provides the fields necessary for a client to
+identify himself to a service and vice versa.
+Security and access control mechanisms
+can be built on top of the message authentication.
+.bp
+.
+.H 1 "Requirements"
+.LP
+The RPC protocol must provide for the following:
+.DS
+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.
+.DE
+Besides these requirements,
+features that detect the following are worth supporting
+because of protocol roll-over errors, implementation bugs,
+user error, and network administration:
+.DS
+1. RPC protocol mismatches.
+2. Remote program protocol version mismatches.
+3. Protocol errors (like mis-specification of a procedure's parameters).
+4. Reasons why remote authentication failed.
+5. Any other reasons why the desired procedure was not called.
+.DE
+.
+.H 2 "Remote Programs and Procedures"
+.LP
+The RPC call message has three unsigned fields:
+remote program number,
+remote program version number,
+and remote procedure number.
+The three fields uniquely identify the procedure 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 number 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 protocols
+through the same server process possible.
+.LP
+The procedure number identifies the procedure to be called.
+These numbers are documented in
+the specific program's protocol specification.
+For example, a file service's protocol specification
+may state that its procedure number 5 is
+.L read
+and procedure number 12 is
+.L write .
+.LP
+Just as remote program protocols may change over several versions,
+the actual RPC message protocol could also change.
+Therefore, the call message also has the RPC version number in it;
+this field must be two (2).
+.LP
+The reply message to a request message has enough information
+to distinguish the following error conditions:
+.IP 1)
+The remote implementation of RPC does speak protocol version 2. The
+lowest and highest supported RPC version numbers are returned.
+.IP 2)
+The remote program is not available on the remote system.
+.IP 3)
+The remote program does not support the requested version number.
+The lowest and highest supported
+remote program version numbers are returned.
+.IP 4)
+The requested procedure number does not exist
+(this is usually a caller side protocol or programming error).
+.IP 5)
+The parameters to the remote procedure
+appear to be garbage from the server's point of view.
+(Again, this is caused by a disagreement about the
+protocol between client and service.)
+.
+.H 2 "Authentication"
+.LP
+Provisions for authentication of caller to service and vice versa are
+provided as a wart on the side 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:
+.LS
+enum auth_flavor {
+ AUTH_NULL = 0,
+ AUTH_UNIX = 1,
+ AUTH_SHORT = 2
+ /* and more to be defined */
+};
+.sp.5
+struct opaque_auth {
+ union switch (enum auth_flavor) {
+ default: string auth_body<400>;
+ };
+};
+.LE
+In simple English, any
+.L opaque_auth
+structure is an
+.L auth_flavor
+enumeration followed by a counted string,
+whose bytes are opaque to the RPC protocol implementation.
+.LP
+The interpretation and semantics of the data contained
+within the authentication fields is specified by individual,
+independent authentication protocol specifications.
+Appendix 1 defines three authentication protocols.
+.LP
+If authentication parameters were rejected,
+the response message contains information stating
+why they were rejected.
+.
+.H 2 "Program Number Assignment"
+.LP
+Program numbers are given out in groups of 0x20000000 (536870912)
+according to the following chart:
+.LS
+ 0 - 1fffffff defined by Sun
+20000000 - 3fffffff defined by user
+40000000 - 5fffffff transient
+60000000 - 7fffffff reserved
+80000000 - 9fffffff reserved
+a0000000 - bfffffff reserved
+c0000000 - dfffffff reserved
+e0000000 - ffffffff reserved
+.LE
+The first group is a range of numbers administered by Sun Microsystems,
+and should be identical for all Sun customers. The second range
+is for applications peculiar to a particular customer.
+This range is intended primarily for debugging new programs.
+When a customer 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 reservered for future use, and should not be used.
+.LP
+The exact registration process for Sun defined numbers is yet
+to be established.
+.bp
+.
+.H 1 "Other Uses and Abuses of the RPC Protocol"
+.LP
+The intended use of this protocol is for calling remote procedures.
+That is, each call message is matched with a response message.
+However, the protocol itself is a message passing protocol
+with which other (non-RPC) protocols can be implemented.
+Sun currently uses (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.
+.
+.H 2 "Batching"
+.LP
+Batching allows a client to send an arbitrarily large sequence
+of call messages to a server;
+batching uses reliable bytes stream protocols (like TCP/IP)
+for their 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).
+.
+.H 2 "Broadcast RPC"
+.LP
+In broadcast RPC based protocols,
+the client sends an a broadcast packet to
+the network and waits for numerous replies.
+Broadcast RPC uses unreliable, packet based protocols (like UDP/IP)
+as their transports.
+Servers that support broadcast protocols only respond
+when the request is successfully processed,
+and are silent in the face of errors.
+.
+.H 1 "The RPC Message Protocol"
+.LP
+This section defines the RPC message protocol in the XDR data description
+language. The message is defined in a top down style.
+Note: This is an XDR specification, not C code.
+.LP
+.LS 0
+enum msg_type {
+ CALL = 0,
+ REPLY = 1
+};
+.LE
+.LS 0
+/*
+ * A reply to a call message can take on two forms:
+ * the message was either accepted or rejected.
+ */
+enum reply_stat {
+ MSG_ACCEPTED = 0,
+ MSG_DENIED = 1
+};
+.LE
+.LS 0
+/*
+ * Given that a call message was accepted, the following is the status of
+ * an attempt to call a remote procedure.
+ */
+enum accept_stat {
+ SUCCESS = 0, /* remote procedure was successfully executed */
+ PROG_UNAVAIL = 1, /* remote machine exports the program number */
+ PROG_MISMATCH = 2, /* remote machine can't support version number */
+ PROC_UNAVAIL = 3, /* remote program doesn't know about procedure */
+ GARBAGE_ARGS = 4 /* remote procedure can't figure out parameters */
+};
+.LE
+.LS 0
+/*
+ * Reasons why a call message was rejected:
+ */
+enum reject_stat {
+ RPC_MISMATCH = 0, /* RPC version number was not two (2) */
+ AUTH_ERROR = 1 /* caller not authenticated on remote machine */
+};
+.LE
+.LS 0
+/*
+ * Why authentication failed:
+ */
+enum auth_stat {
+ AUTH_BADCRED = 1, /* bogus credentials (seal broken) */
+ AUTH_REJECTEDCRED = 2, /* client should begin new session */
+ AUTH_BADVERF = 3, /* bogus verifier (seal broken) */
+ AUTH_REJECTEDVERF = 4, /* verifier expired or was replayed */
+ AUTH_TOOWEAK = 5, /* rejected due to security reasons */
+};
+.LE
+.LS 0
+/*
+ * The RPC message:
+ * All messages start with a transaction identifier, xid, followed by
+ * a two-armed discriminated union. The union's discriminant is a msg_type
+ * which switches to one of the two types of the message. The xid of a
+ * REPLY message always matches that of the initiating CALL message.
+ * NB: The xid field is only used for clients matching reply messages with
+ * call messages; the service side cannot treat this id as any type of
+ * sequence number.
+ */
+struct rpc_msg {
+ unsigned xid;
+ union switch (enum msg_type) {
+ CALL: struct call_body;
+ REPLY: struct reply_body;
+ };
+};
+.LE
+.LS 0
+/*
+ * Body of an RPC request call:
+ * In version 2 of the RPC protocol specification, rpcvers must be equal to 2.
+ * The fields prog, vers, and proc specify the remote program, its version,
+ * and the procedure within the remote program to be called. These fields are
+ * followed by two authentication parameters, cred (authentication credentials)
+ * and verf (authentication verifier). The authentication parameters are
+ * followed * by the parameters to the remote procedure; these parameters are
+ * specified by the specific program protocol.
+ */
+struct call_body {
+ unsigned rpcvers; /* must be equal to two (2) */
+ unsigned prog;
+ unsigned vers;
+ unsigned proc;
+ struct opaque_auth cred;
+ struct opaque_auth verf;
+ /* procedure specific parameters start here */
+};
+.LE
+.LS 0
+/*
+ * Body of a reply to an RPC request.
+ * The call message was either accepted or rejected.
+ */
+struct reply_body {
+ union switch (enum reply_stat) {
+ MSG_ACCEPTED: struct accepted_reply;
+ MSG_DENIED: struct rejected_reply;
+ };
+};
+.LE
+.LS 0
+/*
+ * Reply to an RPC request that was accepted by the server.
+ * Note: there could be an error even though the request was accepted.
+ * The first field is an authentication verifier which the server generates
+ * in order to validate itself to the caller. It is followed by a union
+ * whose discriminant is an enum accept_stat. The SUCCESS arm of the union is
+ * protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, and GARBAGE_ARGS arms
+ * of the union are void. The PROG_MISMATCH arm specifies the lowest and
+ * highest version numbers of the remote program that are supported by the
+ * server.
+ */
+struct accepted_reply {
+ struct opaque_auth verf;
+ union switch (enum accept_stat) {
+ SUCCESS: struct {
+ /*
+ * procedure-specific results start here
+ */
+ };
+ PROG_MISMATCH: struct {
+ unsigned low;
+ unsigned high;
+ };
+ default: struct {
+ /*
+ * void. Cases include PROG_UNAVAIL,
+ * PROC_UNAVAIL, and GARBAGE_ARGS.
+ */
+ };
+ };
+};
+.LE
+.LS 0
+/*
+ * Reply to an RPC request that was rejected by the server.
+ * The request can be rejected because of two reasons - either the server is
+ * not running a compatible version of the RPC protocol (RPC_MISMATCH), or
+ * the server refused to authenticate the caller (AUTH_ERROR). In the case of
+ * an RPC version mismatch, the server returns the lowest and highest supported
+ * RPC version numbers. In the case of refused authentication, the failure
+ * status is returned.
+ */
+struct rejected_reply {
+ union switch (enum reject_stat) {
+ RPC_MISMATCH: struct {
+ unsigned low;
+ unsigned high;
+ };
+ AUTH_ERROR: enum auth_stat;
+ };
+};
+.LE
+.bp
+.
+.H 1 "Appendix 1: Authentication Parameters Specification"
+.LP
+As previously stated, authentication parameters are opaque,
+but open-ended to the rest of the
+RPC protocol. This section defines some ``flavors'' of authentication
+which have been implemented at (and supported by) Sun.
+.
+.H 2 "Null Authentication"
+.LP
+Often calls must be made where the caller does not know who he is and
+the server does not care who the caller is. In this case, the auth_flavor value
+(the discriminant of the opaque_auth's union) of the
+RPC message's credentials, verifier, and response verifier
+is AUTH_NULL (0).
+The bytes of the auth_body string are undefined.
+It is recommended that the string length be zero.
+.
+.H 2 "UNIX Authentication"
+.LP
+The caller of a remote procedure may wish to identify himself as he is
+identified on a
+.UX
+system.
+The value of the
+.I credential's
+discriminant of
+an RPC call message is AUTH_UNIX (1). The bytes of the
+.I credential's
+string
+encode the the following (XDR) structure:
+.LS
+struct auth_unix {
+ unsigned stamp;
+ string machinename<255>;
+ unsigned uid;
+ unsigned gid;
+ unsigned gids<10>;
+};
+.LE
+The
+.L stamp
+is an arbitrary id which the caller machine may generate.
+The
+.L machinename
+is the name of the caller's machine (like ``krypton'').
+The
+.L uid
+is the caller's effective user id.
+The
+.L gid
+is the callers effective group id.
+The
+.L gids
+is a counted array of groups
+which contain the caller as a member.
+The
+.I verifier
+accompanying the credentials should be of AUTH_NULL (defined above).
+.LP
+The value of the discriminate of the
+.I "response verifier"
+received in the reply message from the server may be
+AUTH_NULL or AUTH_SHORT (2).
+In the case of AUTH_SHORT, the bytes of the
+.I "response verifier" 's
+string encode an
+.L auth_opaque
+structure.
+This new
+.L auth_opaque
+structure may now be passed to the server
+instead of the original AUTH_UNIX flavor credentials.
+The server keeps a cache which maps short hand
+.I auth_opaque
+structures (passed back via a AUTH_SHORT style
+.L "response verifier" )
+to the original credentials of the caller.
+The caller can save network bandwidth and server cpu cycles
+by using the new credentials.
+.LP
+The server may flush the short hand
+.I auth_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 AUTH_REJECTEDCRED.
+At this point, the caller may wish to try the original AUTH_UNIX style of
+credentials.
+.
+.H 1 "Appendix 2: Record Marking Standard (RM)"
+.LP
+When RPC messages are passed on top of a byte stream protocol
+(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.
+Sun uses this RM/TCP/IP transport for passing
+RPC messages on TCP streams.
+One RPC message fits into one RM record.
+.LP
+A record is composed of one or more record fragments.
+A record fragment is a four-byte header followed by
+.I 0
+to
+.I "2\s-2\u31\d\s+2\-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 \(em
+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
+.I not
+in XDR standard form!)
+.
+.H 1 "Appendix 3: Port Mapper Program Protocol"
+.LP
+The port mapper program maps RPC program and version numbers
+to UDP/IP or TCP/IP port numbers.
+This program makes dynamic binding of remote programs possible.
+.LP
+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.
+.
+.H 2 "The Port Mapper RPC Protocol"
+.LP
+The protocol is specified by the XDR description language.
+.LP
+.LS 0
+Port Mapper RPC Program Number: 100000
+ Version Number: 1
+ Supported Transports:
+ UDP/IP on port 111
+ RM/TCP/IP on port 111
+.LE
+.LS 0
+/*
+ * Handy transport protocol numbers
+ */
+#define IPPROTO_TCP 6 /* protocol number used for rpc/rm/tcp/ip */
+#define IPPROTO_UDP 17 /* protocol number used for rpc/udp/ip */
+.LE
+.LS 0
+/* Procedures */
+
+/*
+ * Convention: procedure zero of any protocol takes no parameters
+ * and returns no results.
+ */
+0. PMAPPROC_NULL () returns ()
+.LE
+.LS 0
+/*
+ * Procedure 1, setting a mapping:
+ * 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 number (prot),
+ * and the port (port) on which it awaits service request. The
+ * procedure returns success whose value is TRUE if the procedure
+ * successfully established the mapping and FALSE otherwise. The
+ * procedure will refuse to establish a mapping if one already exists
+ * for the tuple [prog, vers, prot].
+ */
+1. PMAPPROC_SET (prog, vers, prot, port) returns (success)
+ unsigned prog;
+ unsigned vers;
+ unsigned prot;
+ unsigned port;
+ boolean success;
+.LE
+.LS 0
+/*
+ * Procedure 2, Unsetting a mapping:
+ * When a program becomes unavailable, it should unregister itself
+ * with the port mapper program on the same machine. The parameters
+ * and results have meanings identical to those of PMAPPROC_SET.
+ */
+2. PMAPPROC_UNSET (prog, vers, dummy1, dummy2) returns (success)
+ unsigned prog;
+ unsigned vers;
+ unsigned dummy1; /* this value is always ignored */
+ unsigned dummy2; /* this value is always ignored */
+ boolean success;
+.LE
+.LS 0
+/*
+ * Procedure 3, looking-up a mapping:
+ * Given a program number (prog), version number (vers) and
+ * transport protocol number (prot), this procedure returns the port
+ * number on which the program is awaiting call requests. A port
+ * value of zeros means that the program has not been registered.
+ */
+3. PMAPPROC_GETPORT (prog, vers, prot, dummy) returns (port)
+ unsigned prog;
+ unsigned vers;
+ unsigned prot;
+ unsigned dummy; /* this value is always ignored */
+ unsigned port; /* zero means the program is not registered */
+.LE
+.LS 0
+/*
+ * Procedure 4, dumping the mappings:
+ * This procedure enumerates all entries in the port mapper's database.
+ * The procedure takes no parameters and returns a ``list'' of
+ * [program, version, prot, port] values.
+ */
+4. PMAPPROC_DUMP () returns (maplist)
+ struct maplist {
+ union switch (boolean) {
+ FALSE: struct { /* void, end of list */ };
+ TRUE: struct {
+ unsigned prog;
+ unsigned vers;
+ unsigned prot;
+ unsigned port;
+ struct maplist the_rest;
+ };
+ };
+ } maplist;
+.LE
+.LS 0
+/*
+ * Procedure 5, indirect call routine:
+ * The procedures allows a caller to call another remote procedure
+ * on the same machine without knowing the remote procedure's port
+ * number. Its intended use is 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 the the remote
+ * procedure.
+ *
+ * NB:
+ * 1. This procedure only sends a response if the procedure was
+ * successfully executed and is silent (No response) otherwise.
+ * 2. The port mapper communicates with the remote program via
+ * UDP/IP only.
+ *
+ * The procedure returns the port number of the remote program and
+ * the bytes of results are the results of the remote procedure.
+ */
+5. PMAPPROC_CALLIT (prog, vers, proc, args) returns (port, results)
+ unsigned prog;
+ unsigned vers;
+ unsigned proc;
+ string args<>;
+ unsigned port;
+ string results<>;
+.LE
projects / unix-history / commitdiff