RPC Message Protocol (2024)

The Remote Procedure Call (RPC) message protocol consists of two distinct structures: the call message and the reply message. A client makes a remote procedure call to a network server and receives a reply containing the results of the procedure's execution. By providing a unique specification for the remote procedure, RPC can match a reply message to each call (or request) message.

The RPC message protocol is defined using the eXternal Data Representation (XDR) data description, which includes structures, enumerations, and unions. See "RPC Language Descriptions" for more information.

When RPC messages are passed using the TCP/IP byte-stream protocol for data transport, it is important to identify the end of one message and the start of the next one.

RPC Protocol Requirements

The RPC message protocol requires:

Unique specification of a procedure to call
Matching of response messages to request messages
Authentication of caller to service and service to caller

To help reduce network administration and eliminate protocol roll-over errors, implementation bugs, and user errors, features that detect the following conditions are useful:

RPC protocol mismatches
Remote program protocol version mismatches
Protocol errors (such as misspecification of a procedure's parameters)
Reasons why remote authentication failed
Any other reasons why the desired procedure was not called

RPC Messages

The initial structure of an RPC message is as follows:

structrpc_msg{unsignedintxid;unionswitch(enummsg_typemtype){caseCALL:call_bodycbody;caseREPLY;reply_bodyrbody;}body;};

All RPC call and reply messages start with a transaction identifier, xid, which is followed by a two-armed discriminated union. The union's discriminant is msg_type, which switches to one of the following message types: CALL or REPLY. The msg_type has the following enumeration:

RPC Call Message

Each remote procedure call message contains the following unsigned integer fields to uniquely identify the remote procedure:

Program number
Program version number
Procedure number

The body of an RPC call message takes the following form:

structcall_body{unsignedintrpcvers;unsignedintprog;unsignedintvers;unsignedintproc;opaque_authcred;opaque_authverf;1parameter2parameter...};

The parameters for this structure are:

`rpcvers`	Specifies the version number of the RPC protocol. The value of this parameter is 2 to indicate the second version of RPC.
`prog`	Specifies the number that identifies the remote program. This is an assigned number represented in a protocol that identifies the program needed to call a remote procedure. Program numbers are administered by a central authority and documented in the program's protocol specification.
`vers`	Specifies the number that identifies the remote program version. As a remote program's protocols are implemented, they evolve and change. Version numbers are assigned to identify different stages of a protocol's evolution. Servers can service requests for different versions of the same protocol simultaneously.
`proc`	Specifies the number of the procedure associated with the remote program being called. These numbers are documented in the specific program's protocol specification. For example, a protocol's specification can list the read procedure as procedure number 5 or the write procedure as procedure number 12.
`cred`	Specifies the credentials-authentication parameter that identifies the caller as having permission to call the remote program. This parameter is passed as an opaque data structure, which means the data is not interpreted as it is passed from the client to the server.
`verf`	Specifies the verifier-authentication parameter that identifies the caller to the server. This parameter is passed as an opaque data structure, which means the data is not interpreted as it is passed from the client to the server.
`1parameter`	Denotes a procedure-specific parameter.
`2parameter`	Denotes a procedure-specific parameter.

The client can send a broadcast packet to the network and wait for numerous replies from various servers. The client can also send an arbitrarily large sequence of call messages in a batch to the server.

RPC Reply Message

The RPC protocol for a reply message varies depending on whether the call message is accepted or rejected by the network server.

The reply message to a request contains information to distinguish the following conditions:

RPC executed the call message successfully.
The remote implementation of RPC is not protocol version 2. The lowest and highest supported RPC version numbers are returned.
The remote program is not available on the remote system.
The remote program does not support the requested version number. The lowest and highest supported remote program version numbers are returned.
The requested procedure number does not exist. This is usually a caller-side protocol or programming error.

The RPC reply message takes the following form:

enumreply_statstat{MSG_ACCEPTED=0,MSG_DENIED=1};

The enumreply_stat discriminant acts as a switch to the rejected or accepted reply message forms.

The Reply to an Accepted Request

An RPC reply message for a request accepted by the network server has the following structure:

structaccepted_replyareply{opaque_authverf;unionswitch(enumaccept_statstat){caseSUCCESS:opaqueresults{0};/*procedurespecificresultsstarthere*/casePROG_MISMATCH:struct{unsignedintlow;unsignedinthigh;}mismatch_info;default:void;}reply_data;};

The structures within the accepted reply are:

`opaque_authverf`	Authentication verifier generated by the server to identify itself to the caller.
`enumaccept_stat`	A discriminant that acts as a switch between SUCCESS, PROG_MISMATCH, and other appropriate conditions.

The accept_stat enumeration data type has the following definitions:

enumaccept_stat{SUCCESS=0,/*RPCexecutedsuccessfully*/PROG_UNAVAIL=1,/*remotehasnotexportedprogram*/PROG_MISMATCH=2,/*remotecannotsupportversion#*/PROC_UNAVAIL=3,/*programcannotsupportprocedure*/GARBAGE_ARGS=4,/*procedurecannotdecodeparams*/};

The structures within the accept_stat enumeration data type are defined as follows:

`SUCCESS`	RPC call is successful.
`PROG_UNAVAIL`	The remote server has not exported the program.
`PROG_MISMATCH`	The remote server cannot support the client's version number. Returns the lowest and highest version numbers of the remote program that are supported by the server.
`PROC_UNAVAIL`	The program cannot support the requested procedure.
`GARBAGE_ARGS`	The procedure cannot decode the parameters specified in the call.

Note: An error condition can exist even when a call message is accepted by the server.

The Reply to a Rejected Request

A call message can be rejected by the server for two reasons: either the server is not running a compatible version of the RPC protocol, or there is an authentication failure.

An RPC reply message for a request rejected by the network server has the following structure:

structrejected_replyrreply{unionswitch(enumreject_statstat){caseRPC_MISMATCH:struct{unsignedintlow;unsignedinthigh;}mismatch_info;caseAUTH_ERROR:enumauth_statstat;};

The enumreject_stat discriminant acts as a switch between RPC_MISMATCH and AUTH_ERROR. The rejected call message returns one of the following status conditions:

enumreject_stat{RPC_MISMATCH=0,/*RPCversionnumberisnot2*/AUTH_ERROR=1,/*remotecannotauthenticatecaller*/};

RPC_MISMATCH

The server is not running a compatible version of the RPC protocol. The server returns the lowest and highest version numbers available.

AUTH_ERROR

The server refuses to authenticate the caller and returns a failure status with the value enumauth_stat. Authentication may fail because of bad or rejected credentials, bad or rejected verifier, expired or replayed verifier, or security problems.

If the server does not authenticate the caller, AUTH_ERROR returns one of the following conditions as the failure status:

enumauth_stat{AUTH_BADCRED=1,/*badcredentials*/AUTH_REJECTEDCRED=2,/*beginnewsession */AUTH_BADVERF=3,/*badverifier*/AUTH_REJECTEDVERF=4,/*expiredorreplayed*/AUTH_TOOWEAK=5,/*rejectedforsecurity*/};

Marking Records in RPC Messages

When RPC messages are passed using the TCP/IP byte-stream protocol for data transport, it is important to identify the end of one message and the start of the next one. This is called record marking (RM).

A record is composed of one or more record fragments. A record fragment is a four-byte header, followed by 0 to 232 -1 bytes of fragment data. The bytes encode an unsigned binary number, similar to XDR integers, in which the order of bytes is from highest to lowest. This binary number encodes a Boolean and an unsigned binary value of 31 bits.

The Boolean value is the highest-order bit of the header. A Boolean value of 1 indicates the last fragment of the record. The unsigned binary value is the length, in bytes, of the data fragment.

Note: A protocol disagreement between client and server can cause remote procedure parameters to be unintelligible to the server.