/share/doc/psd/26.rpcrfc/rpc.rfc.ms
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 1304 lines · 1279 code · 25 blank · 0 comment · 0 complexity · 13190eaea4c2ba839877b6769d8a75a4 MD5 · raw file
- .\"
- .\" Must use -- tbl -- with this one
- .\"
- .\" @(#)rpc.rfc.ms 2.2 88/08/05 4.0 RPCSRC
- .\" $FreeBSD$
- .\"
- .de BT
- .if \\n%=1 .tl ''- % -''
- ..
- .ND
- .\" prevent excess underlining in nroff
- .if n .fp 2 R
- .OH 'Remote Procedure Calls: Protocol Specification''Page %'
- .EH 'Page %''Remote Procedure Calls: Protocol Specification'
- .if \n%=1 .bp
- .SH
- \&Remote Procedure Calls: Protocol Specification
- .LP
- .NH 0
- \&Status of this Memo
- .LP
- Note: This chapter specifies a protocol that Sun Microsystems, Inc.,
- and others are using.
- It has been designated RFC1050 by the ARPA Network
- Information Center.
- .LP
- .NH 1
- \&Introduction
- .LP
- This chapter specifies a message protocol used in implementing
- Sun's Remote Procedure Call (RPC) package. (The message protocol is
- specified with the External Data Representation (XDR) language.
- See the
- .I "External Data Representation Standard: Protocol Specification"
- 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.
- .NH 2
- \&Terminology
- .LP
- This chapter discusses servers, services, programs, procedures,
- clients, and versions. A server is a piece of software where network
- services are implemented. A network 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 the
- \fIPort Mapper Program Protocol\fP\, below, 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
- 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.
- .NH 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, in that one thread of control
- logically winds through two processes\(emone 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.
- .LP
- 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.
- .NH 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 deals only with specification and interpretation of
- messages.
- .LP
- It is important to point out that RPC does not try to implement 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 unreliable 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.
- .LP
- 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 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.
- .LP
- 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 packaged with every RPC
- request. The main use of this transaction 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.
- .LP
- 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 protocol like TCP is used, an application still
- needs time-outs and reconnection to handle server crashes.
- .LP
- There are other possibilities for transports besides datagram- or
- connection-oriented protocols. For example, a request-reply protocol
- such as VMTP[2] is perhaps the most natural transport for RPC.
- .SH
- .I
- NOTE: At Sun, RPC is currently implemented on top of both TCP/IP
- and UDP/IP transports.
- .LP
- .NH 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\(emsee the \fIPort Mapper Program Protocol\fP\, below).
- .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.
- .NH 2
- \&Authentication
- .LP
- The RPC protocol provides the fields necessary for a client to
- identify itself to a service and vice-versa. Security 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 indicates which protocol is being used. More
- information on specific authentication protocols can be found in the
- \fIAuthentication Protocols\fP\,
- below.
- .KS
- .NH 1
- \&RPC Protocol Requirements
- .LP
- The RPC protocol must provide for the following:
- .IP 1.
- Unique specification of a procedure to be called.
- .IP 2.
- Provisions for matching response messages to request messages.
- .KE
- .IP 3.
- Provisions for authenticating the caller to service and vice-versa.
- .LP
- Besides these requirements, features that detect the following are
- worth supporting because of protocol roll-over errors, implementation
- bugs, user error, and network administration:
- .IP 1.
- RPC protocol mismatches.
- .IP 2.
- Remote program protocol version mismatches.
- .IP 3.
- Protocol errors (such as misspecification of a procedure's parameters).
- .IP 4.
- Reasons why remote authentication failed.
- .IP 5.
- Any other reasons why the desired procedure was not called.
- .NH 2
- \&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 "read" and procedure number
- 12 is "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 in it the RPC version number, which is always
- equal to two for the version of RPC described here.
- .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 usually caused by a
- disagreement about the protocol between client and service.)
- .NH 2
- \&Authentication
- .LP
- 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:
- .DS
- .ft CW
- .vs 11
- enum auth_flavor {
- AUTH_NULL = 0,
- AUTH_UNIX = 1,
- AUTH_SHORT = 2,
- AUTH_DES = 3
- /* \fIand more to be defined\fP */
- };
- struct opaque_auth {
- auth_flavor flavor;
- opaque body<400>;
- };
- .DE
- .LP
- In simple English, any
- .I opaque_auth
- structure is an
- .I auth_flavor
- enumeration followed by bytes which 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. (See
- \fIAuthentication Protocols\fP\,
- below, for definitions of the various authentication protocols.)
- .LP
- If authentication parameters were rejected, the response message
- contains information stating why they were rejected.
- .NH 2
- \&Program Number Assignment
- .LP
- Program numbers are given out in groups of
- .I 0x20000000
- (decimal 536870912) according to the following chart:
- .TS
- box tab (&) ;
- lfI lfI
- rfL cfI .
- Program Numbers&Description
- _
- .sp .5
- 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
- .TE
- .LP
- 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.
- .NH 2
- \&Other Uses 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, 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.
- .NH 3
- \&Batching
- .LP
- 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).
- .NH 3
- \&Broadcast RPC
- .LP
- In broadcast RPC-based protocols, the client sends a broadcast 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 processed, and are silent in the face of
- errors. Broadcast RPC uses the Port Mapper RPC service to achieve
- its semantics. See the \fIPort Mapper Program Protocol\fP\, below,
- for more information.
- .KS
- .NH 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.
- .ie t .DS
- .el .DS L
- .ft CW
- enum msg_type {
- CALL = 0,
- REPLY = 1
- };
- .ft I
- /*
- * A reply to a call message can take on two forms:
- * The message was either accepted or rejected.
- */
- .ft CW
- enum reply_stat {
- MSG_ACCEPTED = 0,
- MSG_DENIED = 1
- };
- .ft I
- /*
- * Given that a call message was accepted, the following is the
- * status of an attempt to call a remote procedure.
- */
- .ft CW
- enum accept_stat {
- SUCCESS = 0, /* \fIRPC executed successfully \fP*/
- PROG_UNAVAIL = 1, /* \fIremote hasn't exported program \fP*/
- PROG_MISMATCH = 2, /* \fIremote can't support version # \fP*/
- PROC_UNAVAIL = 3, /* \fIprogram can't support procedure \fP*/
- GARBAGE_ARGS = 4 /* \fIprocedure can't decode params \fP*/
- };
- .DE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * Reasons why a call message was rejected:
- */
- .ft CW
- enum reject_stat {
- RPC_MISMATCH = 0, /* \fIRPC version number != 2 \fP*/
- AUTH_ERROR = 1 /* \fIremote can't authenticate caller \fP*/
- };
- .ft I
- /*
- * Why authentication failed:
- */
- .ft CW
- enum auth_stat {
- AUTH_BADCRED = 1, /* \fIbad credentials \fP*/
- AUTH_REJECTEDCRED = 2, /* \fIclient must begin new session \fP*/
- AUTH_BADVERF = 3, /* \fIbad verifier \fP*/
- AUTH_REJECTEDVERF = 4, /* \fIverifier expired or replayed \fP*/
- AUTH_TOOWEAK = 5 /* \fIrejected for security reasons \fP*/
- };
- .DE
- .KE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * 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 \fIREPLY\fP message always
- * matches that of the initiating \fICALL\fP message. NB: The xid
- * field is only used for clients matching reply messages with
- * call messages or for servers detecting retransmissions; the
- * service side cannot treat this id as any type of sequence
- * number.
- */
- .ft CW
- struct rpc_msg {
- unsigned int xid;
- union switch (msg_type mtype) {
- case CALL:
- call_body cbody;
- case REPLY:
- reply_body rbody;
- } body;
- };
- .DE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * 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 number, and the procedure within
- * the remote program to be called. After these fields are two
- * authentication parameters: cred (authentication credentials)
- * and verf (authentication verifier). The two authentication
- * parameters are followed by the parameters to the remote
- * procedure, which are specified by the specific program
- * protocol.
- */
- .ft CW
- struct call_body {
- unsigned int rpcvers; /* \fImust be equal to two (2) \fP*/
- unsigned int prog;
- unsigned int vers;
- unsigned int proc;
- opaque_auth cred;
- opaque_auth verf;
- /* \fIprocedure specific parameters start here \fP*/
- };
- .DE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * Body of a reply to an RPC request:
- * The call message was either accepted or rejected.
- */
- .ft CW
- union reply_body switch (reply_stat stat) {
- case MSG_ACCEPTED:
- accepted_reply areply;
- case MSG_DENIED:
- rejected_reply rreply;
- } reply;
- .DE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * Reply to an RPC request that was accepted by the server:
- * there could be an error even though the request was accepted.
- * The first field is an authentication verifier that 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 \fISUCCESS\fP arm of the union is protocol
- * specific. The \fIPROG_UNAVAIL\fP, \fIPROC_UNAVAIL\fP, and \fIGARBAGE_ARGP\fP
- * arms of the union are void. The \fIPROG_MISMATCH\fP arm specifies
- * the lowest and highest version numbers of the remote program
- * supported by the server.
- */
- .ft CW
- struct accepted_reply {
- opaque_auth verf;
- union switch (accept_stat stat) {
- case SUCCESS:
- opaque results[0];
- /* \fIprocedure-specific results start here\fP */
- case PROG_MISMATCH:
- struct {
- unsigned int low;
- unsigned int high;
- } mismatch_info;
- default:
- .ft I
- /*
- * Void. Cases include \fIPROG_UNAVAIL, PROC_UNAVAIL\fP,
- * and \fIGARBAGE_ARGS\fP.
- */
- .ft CW
- void;
- } reply_data;
- };
- .DE
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * Reply to an RPC request that was rejected by the server:
- * The request can be rejected for two reasons: either the
- * server is not running a compatible version of the RPC
- * protocol (\fIRPC_MISMATCH\fP), or the server refuses to
- * authenticate the caller (\fIAUTH_ERROR\fP). In case of an RPC
- * version mismatch, the server returns the lowest and highest
- * supported RPC version numbers. In case of refused
- * authentication, failure status is returned.
- */
- .ft CW
- union rejected_reply switch (reject_stat stat) {
- case RPC_MISMATCH:
- struct {
- unsigned int low;
- unsigned int high;
- } mismatch_info;
- case AUTH_ERROR:
- auth_stat stat;
- };
- .DE
- .NH 1
- \&Authentication Protocols
- .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 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.
- .NH 2
- \&Null Authentication
- .LP
- 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 \fIopaque_auth\fP's union) of the RPC
- message's credentials, verifier, and response verifier is
- .I AUTH_NULL .
- The bytes of the opaque_auth's body are undefined.
- It is recommended that the opaque length be zero.
- .NH 2
- \&UNIX Authentication
- .LP
- The caller of a remote procedure may wish to identify himself as he
- is identified on a UNIX system. The value of the credential's
- discriminant of an RPC call message is
- .I AUTH_UNIX .
- The bytes of
- the credential's opaque body encode the following structure:
- .DS
- .ft CW
- struct auth_unix {
- unsigned int stamp;
- string machinename<255>;
- unsigned int uid;
- unsigned int gid;
- unsigned int gids<10>;
- };
- .DE
- The
- .I stamp
- is an arbitrary ID which the caller machine may
- generate. The
- .I machinename
- is the name of the caller's machine (like "krypton"). The
- .I uid
- is the caller's effective user ID. The
- .I gid
- is the caller's effective group ID. The
- .I gids
- is a
- counted array of groups which contain the caller as a member. The
- verifier accompanying the credentials should be of
- .I AUTH_NULL
- (defined above).
- .LP
- The value of the discriminant of the response verifier received in
- the reply message from the server may be
- .I AUTH_NULL
- or
- .I AUTH_SHORT .
- In the case of
- .I AUTH_SHORT ,
- 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
- .I AUTH_UNIX
- flavor credentials. The server keeps a cache which maps shorthand
- opaque structures (passed back by way of an
- .I AUTH_SHORT
- 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.
- .LP
- 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
- .I AUTH_REJECTEDCRED .
- At this point, the caller may wish to try the original
- .I AUTH_UNIX
- style of credentials.
- .KS
- .NH 2
- \&DES Authentication
- .LP
- UNIX authentication suffers from two major problems:
- .IP 1.
- The naming is too UNIX-system oriented.
- .IP 2.
- There is no verifier, so credentials can easily be faked.
- .LP
- DES authentication attempts to fix these two problems.
- .KE
- .NH 3
- \&Naming
- .LP
- The first problem is handled by addressing the caller by a simple
- string of characters instead of by an operating system 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, netnames should be unique for every
- caller in the internet.
- .LP
- 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 following netname: "unix.515@sun.com". This netname
- contains three items that serve to insure it is unique. Going
- backwards, 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 distinguished we add the operating
- system name. So one user is "unix.515@sun.com" and the other is
- "vms.515@sun.com".
- .LP
- 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 standard, instead of an operating
- system name.
- .LP
- .NH 3
- \&DES Authentication Verifiers
- .LP
- 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 primarily 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 "conversation key" of the RPC session. And
- if the client knows the conversation key, then it must be the real
- client.
- .LP
- The conversation key is a DES [5] key which the client generates
- 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.
- .LP
- The client and the server need the same notion of the current time
- in order for all of this to work. If network time synchronization
- cannot be guaranteed, then client can synchronize with the server
- before beginning the conversation, perhaps by consulting the
- Internet Time Server (TIME[4]).
- .LP
- 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:
- .IP 1.
- the timestamp is greater than the one previously seen from the
- same client.
- .IP 2.
- the timestamp has not expired.
- .LP
- 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.
- .LP
- 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 succeeding. 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.
- .LP
- 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 different than this, it will reject it.
- .LP
- .NH 3
- \&Nicknames and Clock Synchronization
- .LP
- 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 transactions
- 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.
- .LP
- Though they originally were synchronized, the client's and server's
- clocks can get out of sync again. When this happens the client RPC
- subsystem most likely will get back
- .I RPC_AUTHERROR
- at which point it should resynchronize.
- .LP
- A client may still get the
- .I RPC_AUTHERROR
- 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 original 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 their original credentials.
- .KS
- .NH 3
- \&DES Authentication Protocol (in XDR language)
- .ie t .DS
- .el .DS L
- .ft I
- /*
- * There are two kinds of credentials: one in which the client uses
- * its full network name, and one in which it uses its "nickname"
- * (just an unsigned integer) given to it by the server. The
- * client must use its fullname in its first transaction with the
- * server, in which the server will return to the client its
- * nickname. The client may use its nickname in all further
- * transactions with the server. There is no requirement to use the
- * nickname, but it is wise to use it for performance reasons.
- */
- .ft CW
- enum authdes_namekind {
- ADN_FULLNAME = 0,
- ADN_NICKNAME = 1
- };
- .ft I
- /*
- * A 64-bit block of encrypted DES data
- */
- .ft CW
- typedef opaque des_block[8];
- .ft I
- /*
- * Maximum length of a network user's name
- */
- .ft CW
- const MAXNETNAMELEN = 255;
- .ft I
- /*
- * A fullname contains the network name of the client, an encrypted
- * conversation key and the window. The window is actually a
- * lifetime for the credential. If the time indicated in the
- * verifier timestamp plus the window has past, then the server
- * should expire the request and not grant it. To insure that
- * requests are not replayed, the server should insist that
- * timestamps are greater than the previous one seen, unless it is
- * the first transaction. In the first transaction, the server
- * checks instead that the window verifier is one less than the
- * window.
- */
- .ft CW
- struct authdes_fullname {
- string name<MAXNETNAMELEN>; /* \fIname of client \f(CW*/
- des_block key; /* \fIPK encrypted conversation key \f(CW*/
- unsigned int window; /* \fIencrypted window \f(CW*/
- };
- .ft I
- /*
- * A credential is either a fullname or a nickname
- */
- .ft CW
- union authdes_cred switch (authdes_namekind adc_namekind) {
- case ADN_FULLNAME:
- authdes_fullname adc_fullname;
- case ADN_NICKNAME:
- unsigned int adc_nickname;
- };
- .ft I
- /*
- * A timestamp encodes the time since midnight, January 1, 1970.
- */
- .ft CW
- struct timestamp {
- unsigned int seconds; /* \fIseconds \fP*/
- unsigned int useconds; /* \fIand microseconds \fP*/
- };
- .ft I
- /*
- * Verifier: client variety
- * The window verifier is only used in the first transaction. In
- * conjunction with a fullname credential, these items are packed
- * into the following structure before being encrypted:
- *
- * \f(CWstruct {\fP
- * \f(CWadv_timestamp; \fP-- one DES block
- * \f(CWadc_fullname.window; \fP-- one half DES block
- * \f(CWadv_winverf; \fP-- one half DES block
- * \f(CW}\fP
- * This structure is encrypted using CBC mode encryption with an
- * input vector of zero. All other encryptions of timestamps use
- * ECB mode encryption.
- */
- .ft CW
- struct authdes_verf_clnt {
- timestamp adv_timestamp; /* \fIencrypted timestamp \fP*/
- unsigned int adv_winverf; /* \fIencrypted window verifier \fP*/
- };
- .ft I
- /*
- * Verifier: server variety
- * The server returns (encrypted) the same timestamp the client
- * gave it minus one second. It also tells the client its nickname
- * to be used in future transactions (unencrypted).
- */
- .ft CW
- struct authdes_verf_svr {
- timestamp adv_timeverf; /* \fIencrypted verifier \fP*/
- unsigned int adv_nickname; /* \fInew nickname for client \fP*/
- };
- .DE
- .KE
- .NH 3
- \&Diffie-Hellman Encryption
- .LP
- In this scheme, there are two constants,
- .I BASE
- and
- .I MODULUS .
- The
- particular values Sun has chosen for these for the DES
- authentication protocol are:
- .ie t .DS
- .el .DS L
- .ft CW
- const BASE = 3;
- const MODULUS =
- "d4a0ba0250b6fd2ec626e7efd637df76c716e22d0944b88b"; /* \fIhex \fP*/
- .DE
- .ft R
- 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. 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:
- .ie t .DS
- .el .DS L
- .ft CW
- PK(A) = ( BASE ** SK(A) ) mod MODULUS
- PK(B) = ( BASE ** SK(B) ) mod MODULUS
- .DE
- .ft R
- 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.
- .LP
- A computes:
- .ie t .DS
- .el .DS L
- .ft CW
- CK(A, B) = ( PK(B) ** SK(A)) mod MODULUS
- .DE
- .ft R
- while B computes:
- .ie t .DS
- .el .DS L
- .ft CW
- CK(A, B) = ( PK(A) ** SK(B)) mod MODULUS
- .DE
- .ft R
- These two can be shown to be equivalent:
- .ie t .DS
- .el .DS L
- .ft CW
- (PK(B) ** SK(A)) mod MODULUS = (PK(A) ** SK(B)) mod MODULUS
- .DE
- .ft R
- We drop the "mod MODULUS" parts and assume modulo arithmetic to
- simplify things:
- .ie t .DS
- .el .DS L
- .ft CW
- PK(B) ** SK(A) = PK(A) ** SK(B)
- .DE
- .ft R
- Then, replace PK(B) by what B computed earlier and likewise for
- PK(A).
- .ie t .DS
- .el .DS L
- .ft CW
- ((BASE ** SK(B)) ** SK(A) = (BASE ** SK(A)) ** SK(B)
- .DE
- .ft R
- which leads to:
- .ie t .DS
- .el .DS L
- .ft CW
- BASE ** (SK(A) * SK(B)) = BASE ** (SK(A) * SK(B))
- .DE
- .ft R
- This common key CK(A, B) is not used to encrypt the timestamps 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.
- .LP
- 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.
- .KS
- .NH 1
- \&Record Marking Standard
- .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. 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.
- .LP
- 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\(ema 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!)
- .KE
- .KS
- .NH 1
- \&The RPC Language
- .LP
- Just as there was a need to describe the XDR data-types in a formal
- language, there is also need to describe the procedures that operate
- on these XDR data-types in a formal language as well. We use the RPC
- Language for this purpose. It is an extension to the XDR language.
- The following example is used to describe the essence of the
- language.
- .NH 2
- \&An Example Service Described in the RPC Language
- .LP
- Here is an example of the specification of a simple ping program.
- .ie t .DS
- .el .DS L
- .vs 11
- .ft I
- /*
- * Simple ping program
- */
- .ft CW
- program PING_PROG {
- /* \fILatest and greatest version\fP */
- version PING_VERS_PINGBACK {
- void
- PINGPROC_NULL(void) = 0;
- .ft I
- /*
- * Ping the caller, return the round-trip time
- * (in microseconds). Returns -1 if the operation
- * timed out.
- */
- .ft CW
- int
- PINGPROC_PINGBACK(void) = 1;
- } = 2;
- .ft I
- /*
- * Original version
- */
- .ft CW
- version PING_VERS_ORIG {
- void
- PINGPROC_NULL(void) = 0;
- } = 1;
- } = 1;
- const PING_VERS = 2; /* \fIlatest version \fP*/
- .vs
- .DE
- .KE
- .LP
- The first version described is
- .I PING_VERS_PINGBACK
- with two procedures,
- .I PINGPROC_NULL
- and
- .I PINGPROC_PINGBACK .
- .I PINGPROC_NULL
- 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 version,
- .I PING_VERS_ORIG ,
- is the original version of the protocol
- and it does not contain
- .I PINGPROC_PINGBACK
- procedure. It is useful
- for compatibility with old client programs, and as this program
- matures it may be dropped from the protocol entirely.
- .KS
- .NH 2
- \&The RPC Language Specification
- .LP
- The RPC language is identical to the XDR language, except for the
- added definition of a
- .I program-def
- described below.
- .DS
- .ft CW
- 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 ";"
- .DE
- .KE
- .NH 2
- \&Syntax Notes
- .IP 1.
- The following keywords are added and cannot be used as
- identifiers: "program" and "version";
- .IP 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 definition.
- .IP 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.
- .IP 4.
- Program identifiers are in the same name space as constant and
- type identifiers.
- .IP 5.
- Only unsigned constants can be assigned to programs, versions
- and procedures.
- .NH 1
- \&Port Mapper Program Protocol
- .LP
- The port mapper program maps RPC program and version numbers to
- transport-specific 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.
- .LP
- 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 program, the client actually sends its message
- to the port mapper located at the broadcast address. Each port
- mapper that picks up the broadcast then calls the local service
- specified by the client. When the port mapper gets the reply from
- the local service, it sends the reply on back to the client.
- .KS
- .NH 2
- \&Port Mapper Protocol Specification (in RPC Language)
- .ie t .DS
- .el .DS L
- .ft CW
- .vs 11
- const PMAP_PORT = 111; /* \fIportmapper port number \fP*/
- .ft I
- /*
- * A mapping of (program, version, protocol) to port number
- */
- .ft CW
- struct mapping {
- unsigned int prog;
- unsigned int vers;
- unsigned int prot;
- unsigned int port;
- };
- .ft I
- /*
- * Supported values for the "prot" field
- */
- .ft CW
- const IPPROTO_TCP = 6; /* \fIprotocol number for TCP/IP \fP*/
- const IPPROTO_UDP = 17; /* \fIprotocol number for UDP/IP \fP*/
- .ft I
- /*
- * A list of mappings
- */
- .ft CW
- struct *pmaplist {
- mapping map;
- pmaplist next;
- };
- .vs
- .DE
- .ie t .DS
- .el .DS L
- .vs 11
- .ft I
- /*
- * Arguments to callit
- */
- .ft CW
- struct call_args {
- unsigned int prog;
- unsigned int vers;
- unsigned int proc;
- opaque args<>;
- };
- .ft I
- /*
- * Results of callit
- */
- .ft CW
- struct call_result {
- unsigned int port;
- opaque res<>;
- };
- .vs
- .DE
- .KE
- .ie t .DS
- .el .DS L
- .vs 11
- .ft I
- /*
- * Port mapper procedures
- */
- .ft CW
- program PMAP_PROG {
- version PMAP_VERS {
- void
- PMAPPROC_NULL(void) = 0;
- bool
- PMAPPROC_SET(mapping) = 1;
- bool
- PMAPPROC_UNSET(mapping) = 2;
- unsigned int
- PMAPPROC_GETPORT(mapping) = 3;
- pmaplist
- PMAPPROC_DUMP(void) = 4;
- call_result
- PMAPPROC_CALLIT(call_args) = 5;
- } = 2;
- } = 100000;
- .vs
- .DE
- .NH 2
- \&Port Mapper Operation
- .LP
- 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:
- .IP \fBPMAPPROC_NULL:\fP
- This procedure does no work. By convention, procedure zero of any
- protocol takes no parameters and returns no results.
- .IP \fBPMAPPROC_SET:\fP
- 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 a boolean response whose
- value is
- .I TRUE
- if the procedure successfully established the mapping and
- .I FALSE
- otherwise. The procedure refuses to establish
- a mapping if one already exists for the tuple "(prog, vers, prot)".
- .IP \fBPMAPPROC_UNSET:\fP
- 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
- .I PMAPPROC_SET .
- The protocol and port number fields of the argument are ignored.
- .IP \fBPMAPPROC_GETPORT:\fP
- 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 the program has not been registered. The "port" field of the
- argument is ignored.
- .IP \fBPMAPPROC_DUMP:\fP
- This procedure enumerates all entries in the port mapper's database.
- The procedure takes no parameters and returns a list of program,
- version, protocol, and port values.
- .IP \fBPMAPPROC_CALLIT:\fP
- 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.
- .LP
- .B Note:
- .RS
- .IP 1.
- This procedure only sends a response if the procedure was
- successfully executed and is silent (no response) otherwise.
- .IP 2.
- The port mapper communicates with the remote program using UDP/IP
- only.
- .RE
- .LP
- The procedure returns the remote program's port number, and the bytes
- of results are the results of the remote procedure.
- .bp
- .NH 1
- \&References
- .LP
- [1] Birrell, Andrew D. & Nelson, Bruce Jay; "Implementing Remote
- Procedure Calls"; XEROX CSL-83-7, October 1983.
- .LP
- [2] Cheriton, D.; "VMTP: Versatile Message Transaction Protocol",
- Preliminary Version 0.3; Stanford University, January 1987.
- .LP
- [3] Diffie & Hellman; "New Directions in Cryptography"; IEEE
- Transactions on Information Theory IT-22, November 1976.
- .LP
- [4] Harrenstien, K.; "Time Server", RFC 738; Information Sciences
- Institute, October 1977.
- .LP
- [5] National Bureau of Standards; "Data Encryption Standard"; Federal
- Information Processing Standards Publication 46, January 1977.
- .LP
- [6] Postel, J.; "Transmission Control Protocol - DARPA Internet
- Program Protocol Specification", RFC 793; Information Sciences
- Institute, September 1981.
- .LP
- [7] Postel, J.; "User Datagram Protocol", RFC 768; Information Sciences
- Institute, August 1980.
- .LP
- [8] Reynolds, J. & Postel, J.; "Assigned Numbers", RFC 923; Information
- Sciences Institute, October 1984.