rpc.rfc.ms

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

.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: "[e-mail]".  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 "[e-mail]" and the other is
"[e-mail]".
.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