rfc1831.html

this gives details of the network programming

      };

9. AUTHENTICATION PROTOCOLS

   As previously stated, authentication parameters are opaque, but
   open-ended to the rest of the RPC protocol.  This section defines two
   standard "flavors" of authentication.  Implementors are free to
   invent new authentication types, with the same rules of flavor number
   assignment as there is for program number assignment.  The "flavor"
   of a credential or verifier refers to the value of the "flavor" field
   in the opaque_auth structure. Flavor numbers, like RPC program
   numbers, are also administered centrally, and developers may assign
   new flavor numbers by applying through electronic mail to
   "<A HREF="mailto:[e-mail]">[e-mail]</A>".  Credentials and verifiers are represented as variable
   length opaque data (the "body" field in the opaque_auth structure).

   In this document, two flavors of authentication are described.  Of
   these, Null authentication (described in the next subsection) is
   mandatory - it must be available in all implementations.  System
   authentication is described in Appendix A.  It is strongly
   recommended that implementors include System authentication in their
   implementations.  Many applications use this style of authentication,
   and availability of this flavor in an implementation will enhance
   interoperability.

9.1 Null Authentication

   Often calls must be made where the client does not care about its
   identity or the server does not care who the client is.  In this
   case, the flavor of the RPC message's credential, verifier, and reply
   verifier is "AUTH_NONE".  Opaque data associated with "AUTH_NONE" is
   undefined.  It is recommended that the length of the opaque data be
   zero.

10. RECORD MARKING STANDARD

   When RPC messages are passed on top of a byte stream transport
   protocol (like TCP), it is necessary to delimit one message from
   another in order to detect and possibly recover from protocol errors.
   This is called record marking (RM).  One RPC message fits into one RM
   record.

   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 -- a boolean which indicates whether the fragment
   is the last fragment of the record (bit value 1 implies the fragment
   is the last fragment) and a 31-bit unsigned binary value which is the
   length in bytes of the fragment's data.  The boolean value is the
   highest-order bit of the header; the length is the 31 low-order bits.
   (Note that this record specification is NOT in XDR standard form!)

11. THE RPC LANGUAGE

   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.  The RPC
   Language is an extension to the XDR language, with the addition of
   "program", "procedure", and "version" declarations.  The following
   example is used to describe the essence of the language.

11.1 An Example Service Described in the RPC Language

   Here is an example of the specification of a simple ping program.

   program PING_PROG {
         /*
          * Latest and greatest version
          */
         version PING_VERS_PINGBACK {
            void
            PINGPROC_NULL(void) = 0;

            /*
             * Ping the client, return the round-trip time
             * (in microseconds). Returns -1 if the operation
             * timed out.
             */
            int
            PINGPROC_PINGBACK(void) = 1;
         } = 2;

         /*
          * Original version
          */
         version PING_VERS_ORIG {
            void
            PINGPROC_NULL(void) = 0;
         } = 1;
      } = 1;

      const PING_VERS = 2;      /* latest version */

   The first version described is PING_VERS_PINGBACK with two
   procedures, PINGPROC_NULL and PINGPROC_PINGBACK.  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,
   PING_VERS_ORIG, is the original version of the protocol and it does
   not contain 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.

11.2 The RPC Language Specification

   The RPC language is identical to the XDR language defined in RFC
   1014, except for the added definition of a "program-def" described
   below.

   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
        ("," type-specifier )* ")" "=" constant ";"

11.3 Syntax Notes

   (1) The following keywords are added and cannot be used as
   identifiers: "program" and "version";

   (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.

   (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.

   (4) Program identifiers are in the same name space as constant and
   type identifiers.

   (5) Only unsigned constants can be assigned to programs, versions and
   procedures.

APPENDIX A: SYSTEM AUTHENTICATION

   The client may wish to identify itself, for example, as it is
   identified on a UNIX(tm) system.  The flavor of the client credential
   is "AUTH_SYS".  The opaque data constituting the credential encodes
   the following structure:

      struct authsys_parms {
         unsigned int stamp;
         string machinename&lt;255&gt;;
         unsigned int uid;
         unsigned int gid;
         unsigned int gids&lt;16&gt;;
      };

   The "stamp" is an arbitrary ID which the caller machine may generate.
   The "machinename" is the name of the caller's machine (like
   "krypton").  The "uid" is the caller's effective user ID.  The "gid"
   is the caller's effective group ID.  The "gids" is a counted array of
   groups which contain the caller as a member.  The verifier
   accompanying the credential should have "AUTH_NONE" flavor value
   (defined above).  Note this credential is only unique within a
   particular domain of machine names, uids, and gids.

   The flavor value of the verifier received in the reply message from
   the server may be "AUTH_NONE" or "AUTH_SHORT".  In the case of
   "AUTH_SHORT", the bytes of the reply verifier's string encode an
   opaque structure.  This new opaque structure may now be passed to the
   server instead of the original "AUTH_SYS" flavor credential.  The
   server may keep a cache which maps shorthand opaque structures
   (passed back by way of an "AUTH_SHORT" style reply verifier) to the
   original credentials of the caller.  The caller can save network
   bandwidth and server cpu cycles by using the shorthand credential.

   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
   "AUTH_REJECTEDCRED".  At this point, the client may wish to try the
   original "AUTH_SYS" style of credential.

   It should be noted that use of this flavor of authentication does not
   guarantee any security for the users or providers of a service, in
   itself.  The authentication provided by this scheme can be considered
   legitimate only when applications using this scheme and the network
   can be secured externally, and privileged transport addresses are
   used for the communicating end-points (an example of this is the use
   of privileged TCP/UDP ports in Unix systems - note that not all
   systems enforce privileged transport address mechanisms).

REFERENCES

   [1]  Birrell, A. D.  &amp; Nelson, B. J., "Implementing Remote Procedure
        Calls", XEROX CSL-83-7, October 1983.

   [2]  Cheriton, D., "VMTP: Versatile Message Transaction Protocol",
        Preliminary Version 0.3, Stanford University, January 1987.

   [3]  Diffie &amp; Hellman, "New Directions in Cryptography", IEEE
        Transactions on Information Theory IT-22, November 1976.

   [4]  Mills, D., "Network Time Protocol", <A HREF="../../../../../www.faqs.org/rfcs/rfc1305.html">RFC 1305</A>, UDEL,
        March 1992.

   [5]  National Bureau of Standards, "Data Encryption Standard",
        Federal Information Processing Standards Publication 46, January
        1977.

   [6]  Postel, J., "Transmission Control Protocol - DARPA Internet
        Program Protocol Specification", STD 7, <A HREF="../../../../../www.faqs.org/rfcs/rfc793.html">RFC 793</A>, USC/Information
        Sciences Institute, September 1981.

   [7]  Postel, J., "User Datagram Protocol", STD 6, <A HREF="../../../../../www.faqs.org/rfcs/rfc768.html">RFC 768</A>,
        USC/Information Sciences Institute, August 1980.

   [8]  Reynolds, J., and Postel, J., "Assigned Numbers", STD 2,
        <A HREF="../../../../../www.faqs.org/rfcs/rfc1700.html">RFC 1700</A>, USC/Information Sciences Institute, October 1994.

   [9]  Srinivasan, R., "XDR: External Data Representation Standard",
        <A HREF="../../../../../www.faqs.org/rfcs/rfc1832.html">RFC 1832</A>, Sun Microsystems, Inc., August 1995.

   [10] Miller, S., Neuman, C., Schiller, J., and  J. Saltzer, "Section
        E.2.1: Kerberos  Authentication and Authorization System",
        M.I.T. Project Athena, Cambridge, Massachusetts, December 21,
        1987.

   [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An
        Authentication Service for Open Network Systems", pp. 191-202 in
        Usenix Conference Proceedings, Dallas, Texas, February 1988.

   [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication
        Service (V5)", <A HREF="../../../../../www.faqs.org/rfcs/rfc1510.html">RFC 1510</A>, Digital Equipment Corporation,
        USC/Information Sciences Institute, September 1993.

Security Considerations

   Security issues are not discussed in this memo.

Author's Address

   Raj Srinivasan
   Sun Microsystems, Inc.
   ONC Technologies
   2550 Garcia Avenue
   M/S MTV-5-40
   Mountain View, CA  94043
   USA

   Phone: [phone]
   Fax:   [phone]
   EMail: <A HREF="mailto:[e-mail]">[e-mail]</A>

</PRE>
<P ALIGN=CENTER><IMG SRC="../../../../images/clrbar.gif" HEIGHT=2 WIDTH=500 ALT="---"></P>
<P ALIGN=CENTER>[ <A HREF="../../../../rfcs/index.html">Index</A> | 
<A HREF="../../../../rfcs/rfcsearch.html">Search</A> | 
<A HREF="../../../../rfcs/changed.html">What's New</A> | 
<A HREF="mailto:[e-mail]">Comments</A> | 
<A HREF="../../../../rfcs/rfchelp.html">Help</A> ]</P>
<SMALL>
<ADDRESS>
<P ALIGN=CENTER>
Comments/Questions about this archive ? Send mail to <A NAME=name HREF="mailto:[e-mail]">[e-mail]</A>
</P>
</ADDRESS>
</SMALL>
</BODY>
</HTML>