PageRenderTime 42ms CodeModel.GetById 17ms app.highlight 16ms RepoModel.GetById 1ms app.codeStats 0ms

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