From 6af0299aecbfc12d96b17bcf951da646ae36a134 Mon Sep 17 00:00:00 2001 From: Johan Danielsson Date: Sun, 24 Oct 1999 18:22:17 +0000 Subject: [PATCH] add git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@7227 ec53bebd-3082-4978-b11e-865c3cabbd6b --- doc/rfc1831.txt | 1011 ++++++++++++++++++++++++ doc/rfc2203.txt | 1291 +++++++++++++++++++++++++++++++ doc/standardisation/rfc1831.txt | 1011 ++++++++++++++++++++++++ doc/standardisation/rfc2203.txt | 1291 +++++++++++++++++++++++++++++++ 4 files changed, 4604 insertions(+) create mode 100644 doc/rfc1831.txt create mode 100644 doc/rfc2203.txt create mode 100644 doc/standardisation/rfc1831.txt create mode 100644 doc/standardisation/rfc2203.txt diff --git a/doc/rfc1831.txt b/doc/rfc1831.txt new file mode 100644 index 000000000..0556c9e83 --- /dev/null +++ b/doc/rfc1831.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group R. Srinivasan +Request for Comments: 1831 Sun Microsystems +Category: Standards Track August 1995 + + + RPC: Remote Procedure Call Protocol Specification Version 2 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This document describes the ONC Remote Procedure Call (ONC RPC + Version 2) protocol as it is currently deployed and accepted. "ONC" + stands for "Open Network Computing". + +TABLE OF CONTENTS + + 1. INTRODUCTION 2 + 2. TERMINOLOGY 2 + 3. THE RPC MODEL 2 + 4. TRANSPORTS AND SEMANTICS 4 + 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 + 6. AUTHENTICATION 5 + 7. RPC PROTOCOL REQUIREMENTS 5 + 7.1 RPC Programs and Procedures 6 + 7.2 Authentication 7 + 7.3 Program Number Assignment 8 + 7.4 Other Uses of the RPC Protocol 8 + 7.4.1 Batching 8 + 7.4.2 Broadcast Remote Procedure Calls 8 + 8. THE RPC MESSAGE PROTOCOL 9 + 9. AUTHENTICATION PROTOCOLS 12 + 9.1 Null Authentication 13 + 10. RECORD MARKING STANDARD 13 + 11. THE RPC LANGUAGE 13 + 11.1 An Example Service Described in the RPC Language 13 + 11.2 The RPC Language Specification 14 + 11.3 Syntax Notes 15 + APPENDIX A: SYSTEM AUTHENTICATION 16 + REFERENCES 17 + Security Considerations 18 + Author's Address 18 + + + +Srinivasan Standards Track [Page 1] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +1. INTRODUCTION + + This document specifies version two of the message protocol used in + ONC Remote Procedure Call (RPC). The message protocol is specified + with the eXternal Data Representation (XDR) language [9]. This + document assumes that the reader is familiar with XDR. It does not + attempt to justify remote procedure calls systems or describe their + use. The paper by Birrell and Nelson [1] is recommended as an + excellent background for the remote procedure call concept. + +2. TERMINOLOGY + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that makes the call to a server, + which sends back a reply. 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. A + server may support more than one version of a remote program in order + to be compatible with changing protocols. + + 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 + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms client and server only apply to a particular transaction; a + particular hardware entity (host) or software entity (process or + program) could operate in both roles at different times. For + example, a program that supplies remote execution service could also + be a client of a network file service. + +3. THE RPC MODEL + + The ONC RPC protocol is based on the remote procedure call model, + which 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 register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + + + + + +Srinivasan Standards Track [Page 2] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process, and a + server's process. The caller process first sends a call message to + the server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and caller's + execution is resumed. + + 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. + + 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 ONC 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 separate task to process + an incoming call, so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls: + + 1. Error handling: failures of the remote server or network must + be handled when using remote procedure calls. + + 2. Global variables and side-effects: since the server does not + have access to the client's address space, hidden arguments cannot + be passed as global variables or returned as side effects. + + 3. Performance: remote procedures usually operate one or more + orders of magnitude slower than local procedure calls. + + 4. Authentication: since remote procedure calls can be transported + over unsecured networks, authentication may be necessary. + Authentication prevents one entity from masquerading as some other + entity. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + + + + + + +Srinivasan Standards Track [Page 3] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +4. TRANSPORTS AND SEMANTICS + + The RPC protocol can be implemented on several different transport + protocols. The RPC protocol does not care how a message is passed + from one process to another, but only with specification and + interpretation of messages. However, the application may wish to + obtain information about (and perhaps control over) the transport + layer through an interface not specified in this document. For + example, the transport protocol may impose a restriction on the + maximum size of RPC messages, or it may be stream-oriented like TCP + with no size limit. The client and server must agree on their + transport protocol choices. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to 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 [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 [7], it must implement + its own time-out, retransmission, and duplicate detection policies as + the RPC protocol does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. 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. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + 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 + message. The main use of this transaction ID is by the client RPC + entity in matching replies to calls. However, a client application + may choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls 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. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + + + +Srinivasan Standards Track [Page 4] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + assume that 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. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC + uses both TCP and UDP transport protocols. Section 10 (RECORD + MARKING STANDARD) describes the mechanism employed by ONC RPC to + utilize a connection-oriented, stream-oriented transport such as TCP. + +5. BINDING AND RENDEZVOUS INDEPENDENCE + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. + + Implementors could 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 binding software makes RPC useful, possibly using RPC + to accomplish this task. + +6. AUTHENTICATION + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this 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 is in section 9: "Authentication Protocols". + +7. RPC PROTOCOL REQUIREMENTS + + The RPC protocol must provide for the following: + + (1) Unique specification of a procedure to be called. + (2) Provisions for matching response messages to request messages. + (3) Provisions for authenticating the caller to service and + vice-versa. + + + + + + + + + +Srinivasan Standards Track [Page 5] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + (1) RPC protocol mismatches. + (2) Remote program protocol version mismatches. + (3) Protocol errors (such as misspecification of a procedure's + parameters). + (4) Reasons why remote authentication failed. + (5) Any other reasons why the desired procedure was not called. + +7.1 RPC Programs and Procedures + + The RPC call message has three unsigned integer fields -- remote + program number, remote program version number, and remote procedure + number -- which uniquely identify the procedure to be called. + Program numbers are administered by a central authority + (rpc@sun.com). Once implementors have a program number, they can + implement their remote program; the first implementation would most + likely have the version number 1. Because most new protocols evolve, + a version field of the call message identifies which version of the + protocol the caller is using. Version numbers enable support of both + old and new protocols through the same server process. + + 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". + + 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. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + (1) The remote implementation of RPC does not support protocol + version 2. The lowest and highest supported RPC version numbers + are returned. + + (2) The remote program is not available on the remote system. + + (3) The remote program does not support the requested version + number. The lowest and highest supported remote program version + numbers are returned. + + + + +Srinivasan Standards Track [Page 6] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + (4) The requested procedure number does not exist. (This is + usually a client side protocol or programming error.) + + (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.) + +7.2 Authentication + + 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 credential 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 (in the eXternal Data Representation (XDR) language [9]): + + enum auth_flavor { + AUTH_NONE = 0, + AUTH_SYS = 1, + AUTH_SHORT = 2 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by up to 400 bytes which are opaque to + (uninterpreted by) the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields is specified by individual, independent + authentication protocol specifications. (Section 9 defines the + various authentication protocols.) + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + + + + + + + + + + + +Srinivasan Standards Track [Page 7] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +7.3 Program Number Assignment + + Program numbers are given out in groups of hexadecimal 20000000 + (decimal 536870912) according to the following chart: + + 0 - 1fffffff defined by rpc@sun.com + 20000000 - 3fffffff defined by user + 40000000 - 5fffffff transient + 60000000 - 7fffffff reserved + 80000000 - 9fffffff reserved + a0000000 - bfffffff reserved + c0000000 - dfffffff reserved + e0000000 - ffffffff reserved + + The first group is a range of numbers administered by rpc@sun.com 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. Application + developers may apply for blocks of RPC program numbers in the first + range by sending electronic mail to "rpc@sun.com". The third group + is for applications that generate program numbers dynamically. The + final groups are reserved for future use, and should not be used. + +7.4 Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure call) protocols can be implemented. + +7.4.1 Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) 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 calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + +7.4.2 Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + + + +Srinivasan Standards Track [Page 8] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + that support broadcast protocols usually respond only when the call + is successfully processed and are silent in the face of errors, but + this varies with the application. + + The principles of broadcast RPC also apply to multicasting - an RPC + request can be sent to a multicast address. + +8. THE RPC MESSAGE PROTOCOL + + This section defines the RPC message protocol in the XDR data + description language [9]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + + A reply to a call message can take on two forms: The message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4, /* procedure can't decode params */ + SYSTEM_ERR = 5 /* errors like memory allocation failure */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + Why authentication failed: + + enum auth_stat { + AUTH_OK = 0, /* success */ + + + +Srinivasan Standards Track [Page 9] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * failed at remote end + */ + AUTH_BADCRED = 1, /* bad credential (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5, /* rejected for security reasons */ + /* + * failed locally + */ + AUTH_INVALIDRESP = 6, /* bogus response verifier */ + AUTH_FAILED = 7 /* reason unknown */ + }; + + 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 REPLY message always matches that of the initiating CALL + 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. + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC 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 credential) 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. + + The purpose of the authentication verifier is to validate the + authentication credential. Note that these two items are + + + +Srinivasan Standards Track [Page 10] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + historically separate, but are always used together as one logical + entity. + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, + GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The + PROG_MISMATCH arm specifies the lowest and highest version numbers of + the remote program supported by the server. + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + + + +Srinivasan Standards Track [Page 11] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * GARBAGE_ARGS, and SYSTEM_ERR. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH), or + the server rejects the identity of the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of invalid authentication, + failure status is returned. + + 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; + }; + +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 + "rpc@sun.com". 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. + + + +Srinivasan Standards Track [Page 12] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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; + + + +Srinivasan Standards Track [Page 13] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * 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 "{" + + + +Srinivasan Standards Track [Page 14] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 15] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + 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). + + + +Srinivasan Standards Track [Page 16] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +REFERENCES + + [1] Birrell, A. D. & 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 & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [4] Mills, D., "Network Time Protocol", RFC 1305, 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, RFC 793, USC/Information + Sciences Institute, September 1981. + + [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + USC/Information Sciences Institute, August 1980. + + [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, + RFC 1700, USC/Information Sciences Institute, October 1994. + + [9] Srinivasan, R., "XDR: External Data Representation Standard", + RFC 1832, 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)", RFC 1510, Digital Equipment Corporation, + USC/Information Sciences Institute, September 1993. + + + + + + + + +Srinivasan Standards Track [Page 17] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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: 415-336-2478 + Fax: 415-336-6015 + EMail: raj@eng.sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 18] + diff --git a/doc/rfc2203.txt b/doc/rfc2203.txt new file mode 100644 index 000000000..2f6a8a0d0 --- /dev/null +++ b/doc/rfc2203.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group M. Eisler +Request for Comments: 2203 A. Chiu +Category: Standards Track L. Ling + September 1997 + + + RPCSEC_GSS Protocol Specification + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This memo describes an ONC/RPC security flavor that allows RPC + protocols to access the Generic Security Services Application + Programming Interface (referred to henceforth as GSS-API). + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. The ONC RPC Message Protocol . . . . . . . . . . . . . . . . . 2 + 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 3 + 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 3 + 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 3 + 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 5 + 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 5 + 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 5 + 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 6 + 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 8 + 5.2.3.1. Context Creation Response - Successful Acceptance . . . 8 + 5.2.3.1.1. Client Processing of Successful Context Creation + Responses . . . . . . . . . . . . . . . . . . . . . . 9 + 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . . 9 + 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 10 + 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 10 + 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 11 + 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 11 + 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 11 + 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 12 + 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 12 + 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 12 + 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 + 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 15 + + + +Eisler, et. al. Standards Track [Page 1] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 16 + 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 + 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 16 + 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 17 + 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 + 7. Security Considerations . . . . . . . . . . . . . . . . . . 18 + 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 18 + 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 + 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 + 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 + 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 19 + Appendix A. GSS-API Major Status Codes . . . . . . . . . . . . . 20 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 + +1. Introduction + + This document describes the protocol used by the RPCSEC_GSS security + flavor. Security flavors have been called authentication flavors for + historical reasons. This memo recognizes that there are two other + security services besides authentication, integrity, and privacy, and + so defines a new RPCSEC_GSS security flavor. + + The protocol is described using the XDR language [Srinivasan-xdr]. + The reader is assumed to be familiar with ONC RPC and the security + flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be + familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security + flavor uses GSS-API interfaces to provide security services that are + independent of the underlying security mechanism. + +2. The ONC RPC Message Protocol + + This memo refers to the following XDR types of the ONC RPC protocol, + which are described in the document entitled Remote Procedure Call + Protocol Specification Version 2 [Srinivasan-rpc]: + + msg_type + reply_stat + auth_flavor + accept_stat + reject_stat + auth_stat + opaque_auth + rpc_msg + call_body + reply_body + + + +Eisler, et. al. Standards Track [Page 2] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + accepted_reply + rejected_reply + +3. Flavor Number Assignment + + The RPCSEC_GSS security flavor has been assigned the value of 6: + + enum auth_flavor { + ... + RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ + }; + +4. New auth_stat Values + + RPCSEC_GSS requires the addition of two new values to the auth_stat + enumerated type definition: + + enum auth_stat { + ... + /* + * RPCSEC_GSS errors + */ + RPCSEC_GSS_CREDPROBLEM = 13, + RPCSEC_GSS_CTXPROBLEM = 14 + }; + + The descriptions of these two new values are defined later in this + memo. + +5. Elements of the RPCSEC_GSS Security Protocol + + An RPC session based on the RPCSEC_GSS security flavor consists of + three phases: context creation, RPC data exchange, and context + destruction. In the following discussion, protocol elements for + these three phases are described. + + The following description of the RPCSEC_GSS protocol uses some of the + definitions within XDR language description of the RPC protocol. + + Context creation and destruction use control messages that are not + dispatched to service procedures registered by an RPC server. The + program and version numbers used in these control messages are the + same as the RPC service's program and version numbers. The procedure + number used is NULLPROC (zero). A field in the credential + information (the gss_proc field which is defined in the + rpc_gss_cred_t structure below) specifies whether a message is to be + interpreted as a control message or a regular RPC message. If this + field is set to RPCSEC_GSS_DATA, no control action is implied; in + + + +Eisler, et. al. Standards Track [Page 3] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + this case, it is a regular data message. If this field is set to any + other value, a control action is implied. This is described in the + following sections. + + Just as with normal RPC data exchange messages, the transaction + identifier (the xid field in struct rpc_msg), should be set to unique + values on each call for context creation and context destruction. + + The following definitions are used for describing the protocol. + + /* RPCSEC_GSS control procedures */ + + + enum rpc_gss_proc_t { + RPCSEC_GSS_DATA = 0, + RPCSEC_GSS_INIT = 1, + RPCSEC_GSS_CONTINUE_INIT = 2, + RPCSEC_GSS_DESTROY = 3 + }; + + /* RPCSEC_GSS services */ + + enum rpc_gss_service_t { + /* Note: the enumerated value for 0 is reserved. */ + rpc_gss_svc_none = 1, + rpc_gss_svc_integrity = 2, + rpc_gss_svc_privacy = 3 + }; + + /* Credential */ + + /* + * Note: version 0 is reserved for possible future + * definition of a version negotiation protocol + * + */ + #define RPCSEC_GSS_VERS_1 1 + + struct rpc_gss_cred_t { + union switch (unsigned int version) { /* version of + RPCSEC_GSS */ + case RPCSEC_GSS_VERS_1: + struct { + rpc_gss_proc_t gss_proc; /* control procedure */ + unsigned int seq_num; /* sequence number */ + rpc_gss_service_t service; /* service used */ + opaque handle<>; /* context handle */ + } rpc_gss_cred_vers_1_t; + + + +Eisler, et. al. Standards Track [Page 4] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + } + }; + + /* Maximum sequence number value */ + + #define MAXSEQ 0x80000000 + +5.1. Version Selection + + This document defines just one protocol version (RPCSEC_GSS_VERS_1). + The client should assume that the server supports RPCSEC_GSS_VERS_1 + and issue a Context Creation message (as described in the section + RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of + MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of + AUTH_REJECTED_CRED. + +5.2. Context Creation + + Before RPC data is exchanged on a session using the RPCSEC_GSS + flavor, a context must be set up between the client and the server. + Context creation may involve zero or more RPC exchanges. The number + of exchanges depends on the security mechanism. + +5.2.1. Mechanism and QOP Selection + + There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API + mechanism identifiers or QOP values. At minimum, it is expected that + implementations of the RPCSEC_GSS protocol provide a means to: + + * specify mechanism identifiers, QOP values, and RPCSEC_GSS + service values on the client side, and to + + * enforce mechanism identifiers, QOP values, and RPCSEC_GSS + service values on a per-request basis on the server side. + + It is necessary that above capabilities exist so that applications + have the means to conform the required set of required set of + tuples (See the section entitled Set of + GSS-API Mechanisms). An application may negotiate selection within its protocol or via an out of band + protocol. Hence it may be necessary for RPCSEC_GSS implementations to + provide programming interfaces for the specification and enforcement + of . + + Additionally, implementations may depend on negotiation schemes + constructed as pseudo-mechanisms under the GSS-API. Because such + schemes are below the GSS-API layer, the RPCSEC_GSS protocol, as + specified in this document, can make use of them. + + + +Eisler, et. al. Standards Track [Page 5] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.2. Context Creation Requests + + The first RPC request from the client to the server initiates context + creation. Within the RPC message protocol's call_body structure, + rpcvers is set to 2. prog and vers are always those for the service + being accessed. The proc is always set to NULLPROC (zero). + + Within the RPC message protocol's cred structure, flavor is set to + RPCSEC_GSS (6). The opaque data of the cred structure (the body + field) constituting the credential encodes the rpc_gss_cred_t + structure defined previously. + + The values of the fields contained in the rpc_gss_cred_t structure + are set as follows. The version field is set to the version of the + RPCSEC_GSS protocol the client wants to use. The remainder of this + memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the + version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field + must be set to RPCSEC_GSS_INIT for the first creation request. In + subsequent creation requests, the gss_proc field must be set to + RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and + service fields are undefined and both must be ignored by the server. + In the first creation request, the handle field is NULL (opaque data + of zero length). In subsequent creation requests, handle must be + equal to the value returned by the server. The handle field serves + as the identifier for the context, and will not change for the + duration of the context, including responses to + RPCSEC_GSS_CONTINUE_INIT. + + The verifier field in the RPC message header is also described by the + opaque_auth structure. All creation requests have the NULL verifier + (AUTH_NONE flavor with zero length opaque data). + + Following the verifier are the call data (procedure specific + parameters). Note that the proc field of the call_body structure is + set to NULLPROC, and thus normally there would be zero octets + following the verifier. However, since there is no RPC data exchange + during a context creation, it is safe to transfer information + following the verifier. It is necessary to "overload" the call data + in this way, rather than pack the GSS-API token into the RPC header, + because RPC Version 2 restricts the amount of data that can be sent + in the header. The opaque body of the credential and verifier fields + can be each at most 400 octets long, and GSS tokens can be longer + than 800 octets. + + + + + + + + +Eisler, et. al. Standards Track [Page 6] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The call data for a context creation request is described by the + following structure for all creation requests: + + struct rpc_gss_init_arg { + opaque gss_token<>; + }; + + Here, gss_token is the token returned by the call to GSS-API's + GSS_Init_sec_context() routine, opaquely encoded. The value of this + field will likely be different in each creation request, if there is + more than one creation request. If no token is returned by the call + to GSS_Init_sec_context(), the context must have been created + (assuming no errors), and there will not be any more creation + requests. + + When GSS_Init_sec_context() is called, the parameters + replay_det_req_flag and sequence_req_flag must be turned off. The + reasons for this are: + + * ONC RPC can be used over unreliable transports and provides no + layer to reliably re-assemble messages. Thus it is possible for + gaps in message sequencing to occur, as well as out of order + messages. + + * RPC servers can be multi-threaded, and thus the order in which + GSS-API messages are signed or wrapped can be different from the + order in which the messages are verified or unwrapped, even if + the requests are sent on reliable transports. + + * To maximize convenience of implementation, the order in which an + ONC RPC entity will verify the header and verify/unwrap the body + of an RPC call or reply is left unspecified. + + The RPCSEC_GSS protocol provides for protection from replay attack, + yet tolerates out-of-order delivery or processing of messages and + tolerates dropped requests. + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 7] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.3. Context Creation Responses + +5.2.3.1. Context Creation Response - Successful Acceptance + + The response to a successful creation request has an MSG_ACCEPTED + response with a status of SUCCESS. The results field encodes a + response with the following structure: + + struct rpc_gss_init_res { + opaque handle<>; + unsigned int gss_major; + unsigned int gss_minor; + unsigned int seq_window; + opaque gss_token<>; + }; + + Here, handle is non-NULL opaque data that serves as the context + identifier. The client must use this value in all subsequent requests + whether control messages or otherwise). The gss_major and gss_minor + fields contain the results of the call to GSS_Accept_sec_context() + executed by the server. The values for the gss_major field are + defined in Appendix A of this document. The values for the gss_minor + field are GSS-API mechanism specific and are defined in the + mechanism's specification. If gss_major is not one of GSS_S_COMPLETE + or GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case + handle and gss_token must be set to NULL by the server. The value of + gss_minor is dependent on the value of gss_major and the security + mechanism used. The gss_token field contains any token returned by + the GSS_Accept_sec_context() call executed by the server. A token + may be returned for both successful values of gss_major. If the + value is GSS_S_COMPLETE, it indicates that the server is not + expecting any more tokens, and the RPC Data Exchange phase must begin + on the subsequent request from the client. If the value is + GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence + the client must send at least one more creation request (with + gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) + carrying the required token. + + In a successful response, the seq_window field is set to the sequence + window length supported by the server for this context. This window + specifies the maximum number of client requests that may be + outstanding for this context. The server will accept "seq_window" + requests at a time, and these may be out of order. The client may + use this number to determine the number of threads that can + simultaneously send requests on this context. + + + + + + +Eisler, et. al. Standards Track [Page 8] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in + the response) flavor field is set to RPCSEC_GSS, and the body field + set to the checksum of the seq_window (in network order). The QOP + used for this checksum is 0 (zero), which is the default QOP. For + all other values of gss_major, a NULL verifier (AUTH_NONE flavor with + zero-length opaque data) is used. + +5.2.3.1.1. Client Processing of Successful Context Creation Responses + + If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, + then the client, per the GSS-API specification, must invoke + GSS_Init_sec_context() using the token returned in gss_token in the + context creation response. The client must then generate a context + creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. + + If the value of gss_major in the response is GSS_S_COMPLETE, and if + the client's previous invocation of GSS_Init_sec_context() returned a + gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the + GSS-API specification, must invoke GSS_Init_sec_context() using the + token returned in gss_token in the context creation response. If + GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is + successfully set up, and the RPC data exchange phase must begin on + the subsequent request from the client. + +5.2.3.2. Context Creation Response - Unsuccessful Cases + + An MSG_ACCEPTED reply (to a creation request) with an acceptance + status of other than SUCCESS has a NULL verifier (flavor set to + AUTH_NONE, and zero length opaque data in the body field), and is + formulated as usual for different status values. + + An MSG_DENIED reply (to a creation request) is also formulated as + usual. Note that MSG_DENIED could be returned because the server's + RPC implementation does not recognize the RPCSEC_GSS security flavor. + RFC 1831 does not specify the appropriate reply status in this + instance, but common implementation practice appears to be to return + a rejection status of AUTH_ERROR with an auth_stat of + AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_CREDPROBLEM + and RPCSEC_GSS_CTXPROBLEM) have been defined for the auth_stat type, + neither of these two can be returned in responses to context creation + requests. The auth_stat new values can be used for responses to + normal (data) requests. This is described later. + + MSG_DENIED might also be returned if the RPCSEC_GSS version number in + the credential is not supported on the server. In that case, the + server returns a rejection status of AUTH_ERROR, with an auth_stat of + + AUTH_REJECTED_CRED. + + + +Eisler, et. al. Standards Track [Page 9] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3. RPC Data Exchange + + The data exchange phase is entered after a context has been + successfully set up. The format of the data exchanged depends on the + security service used for the request. Although clients can change + the security service and QOP used on a per-request basis, this may + not be acceptable to all RPC services; some RPC services may "lock" + the data exchange phase into using the QOP and service used on the + first data exchange message. For all three modes of service (no data + integrity, data integrity, data privacy), the RPC request header has + the same format. + +5.3.1. RPC Request Header + + The credential has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The credential body is created by + XDR encoding the rpc_gss_cred_t structure listed earlier into an + octet stream, and then opaquely encoding this octet stream as the + body field. + + Values of the fields contained in the rpc_gss_cred_t structure are + set as follows. The version field is set to same version value that + was used to create the context, which within the scope of this memo + will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to + RPCSEC_GSS_DATA. The service field is set to indicate the desired + service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or + rpc_gss_svc_privacy). The handle field is set to the context handle + value received from the RPC server during context creation. The + seq_num field can start at any value below MAXSEQ, and must be + incremented (by one or more) for successive requests. Use of + sequence numbers is described in detail when server processing of the + request is discussed. + + The verifier has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The body field is set as follows. + The checksum of the RPC header (up to and including the credential) + is computed using the GSS_GetMIC() call with the desired QOP. This + returns the checksum as an opaque octet stream and its length. This + is encoded into the body field. Note that the QOP is not explicitly + specified anywhere in the request. It is implicit in the checksum or + encrypted data. The same QOP value as is used for the header + checksum must also be used for the data (for checksumming or + encrypting), unless the service used for the request is + rpc_gss_svc_none. + + + + + + + +Eisler, et. al. Standards Track [Page 10] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.2. RPC Request Data + +5.3.2.1. RPC Request Data - No Data Integrity + + If the service specified is rpc_gss_svc_none, the data (procedure + arguments) are not integrity or privacy protected. They are sent in + exactly the same way as they would be if the AUTH_NONE flavor were + used (following the verifier). Note, however, that since the RPC + header is integrity protected, the sender will still be authenticated + in this case. + +5.3.2.2. RPC Request Data - With Data Integrity + + When data integrity is used, the request data is represented as + follows: + + struct rpc_gss_integ_data { + opaque databody_integ<>; + opaque checksum<>; + }; + + The databody_integ field is created as follows. A structure + consisting of a sequence number followed by the procedure arguments + is constructed. This is shown below as the type rpc_gss_data_t: + + struct rpc_gss_data_t { + unsigned int seq_num; + proc_req_arg_t arg; + }; + + Here, seq_num must have the same value as in the credential. The + type proc_req_arg_t is the procedure specific XDR type describing the + procedure arguments (and so is not specified here). The octet stream + corresponding to the XDR encoded rpc_gss_data_t structure and its + length are placed in the databody_integ field. Note that because the + XDR type of databody_integ is opaque, the XDR encoding of + databody_integ will include an initial four octet length field, + followed by the XDR encoded octet stream of rpc_gss_data_t. + + The checksum field represents the checksum of the XDR encoded octet + stream corresponding to the XDR encoded rpc_gss_data_t structure + (note, this is not the checksum of the databody_integ field). This + is obtained using the GSS_GetMIC() call, with the same QOP as was + used to compute the header checksum (in the verifier). The + + + + + + + +Eisler, et. al. Standards Track [Page 11] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + GSS_GetMIC() call returns the checksum as an opaque octet stream and + its length. The checksum field of struct rpc_gss_integ_data has an + XDR type of opaque. Thus the checksum length from GSS_GetMIC() is + encoded as a four octet length field, followed by the checksum, + padded to a multiple of four octets. + +5.3.2.3. RPC Request Data - With Data Privacy + + When data privacy is used, the request data is represented as + follows: + + struct rpc_gss_priv_data { + opaque databody_priv<> + }; + + The databody_priv field is created as follows. The rpc_gss_data_t + structure described earlier is constructed again in the same way as + for the case of data integrity. Next, the GSS_Wrap() call is invoked + to encrypt the octet stream corresponding to the rpc_gss_data_t + structure, using the same value for QOP (argument qop_req to + GSS_Wrap()) as was used for the header checksum (in the verifier) and + conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() + call returns an opaque octet stream (representing the encrypted + rpc_gss_data_t structure) and its length, and this is encoded as the + databody_priv field. Since databody_priv has an XDR type of opaque, + the length returned by GSS_Wrap() is encoded as the four octet + length, followed by the encrypted octet stream (padded to a multiple + of four octets). + +5.3.3. Server Processing of RPC Data Requests + +5.3.3.1. Context Management + + When a request is received by the server, the following are verified + to be acceptable: + + * the version number in the credential + + * the service specified in the credential + + * the context handle specified in the credential + + * the header checksum in the verifier (via GSS_VerifyMIC()) + + * the sequence number (seq_num) specified in the credential (more + on this follows) + + + + + +Eisler, et. al. Standards Track [Page 12] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The gss_proc field in the credential must be set to RPCSEC_GSS_DATA + for data requests (otherwise, the message will be interpreted as a + control message). + + The server maintains a window of "seq_window" sequence numbers, + starting with the last sequence number seen and extending backwards. + If a sequence number higher than the last number seen is received + (AND if GSS_VerifyMIC() on the header checksum from the verifier + returns GSS_S_COMPLETE), the window is moved forward to the new + sequence number. If the last sequence number seen is N, the server + is prepared to receive requests with sequence numbers in the range N + through (N - seq_window + 1), both inclusive. If the sequence number + received falls below this range, it is silently discarded. If the + sequence number is within this range, and the server has not seen it, + the request is accepted, and the server turns on a bit to "remember" + that this sequence number has been seen. If the server determines + that it has already seen a sequence number within the window, the + request is silently discarded. The server should select a seq_window + value based on the number requests it expects to process + simultaneously. For example, in a threaded implementation seq_window + might be equal to the number of server threads. There are no known + security issues with selecting a large window. The primary issue is + how much space the server is willing to allocate to keep track of + requests received within the window. + + The reason for discarding requests silently is that the server is + unable to determine if the duplicate or out of range request was due + to a sequencing problem in the client, network, or the operating + system, or due to some quirk in routing, or a replay attack by an + intruder. Discarding the request allows the client to recover after + timing out, if indeed the duplication was unintentional or well + intended. Note that a consequence of the silent discard is that + clients may increment the seq_num by more than one. The effect of + this is that the window will move forward more quickly. It is not + believed that there is any benefit to doing this. + + Note that the sequence number algorithm requires that the client + increment the sequence number even if it is retrying a request with + the same RPC transaction identifier. It is not infrequent for + clients to get into a situation where they send two or more attempts + and a slow server sends the reply for the first attempt. With + RPCSEC_GSS, each request and reply will have a unique sequence + number. If the client wishes to improve turn around time on the RPC + call, it can cache the RPCSEC_GSS sequence number of each request it + sends. Then when it receives a response with a matching RPC + transaction identifier, it can compute the checksum of each sequence + number in the cache to try to match the checksum in the reply's + verifier. + + + +Eisler, et. al. Standards Track [Page 13] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The data is decoded according to the service specified in the + credential. In the case of integrity or privacy, the server ensures + that the QOP value is acceptable, and that it is the same as that + used for the header checksum in the verifier. Also, in the case of + integrity or privacy, the server will reject the message (with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS) if the sequence number embedded in the request body is + different from the sequence number in the credential. + +5.3.3.2. Server Reply - Request Accepted + + An MSG_ACCEPTED reply to a request in the data exchange phase will + have the verifier's (the verf element in the response) flavor field + set to RPCSEC_GSS, and the body field set to the checksum (the output + of GSS_GetMIC()) of the sequence number (in network order) of the + corresponding request. The QOP used is the same as the QOP used for + the corresponding request. + + If the status of the reply is not SUCCESS, the rest of the message is + formatted as usual. + + If the status of the message is SUCCESS, the format of the rest of + the message depends on the service specified in the corresponding + request message. Basically, what follows the verifier in this case + are the procedure results, formatted in different ways depending on + the requested service. + + If no data integrity was requested, the procedure results are + formatted as for the AUTH_NONE security flavor. + + If data integrity was requested, the results are encoded in exactly + the same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Integrity.' + The only difference is that the structure representing the + procedure's result - proc_res_arg_t - must be substituted in place of + the request argument structure proc_req_arg_t. The QOP used for the + checksum must be the same as that used for constructing the reply + verifier. + + If data privacy was requested, the results are encoded in exactly the + same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Privacy.' The + QOP used for encryption must be the same as that used for + constructing the reply verifier. + + + + + + + +Eisler, et. al. Standards Track [Page 14] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.3.3. Server Reply - Request Denied + + An MSG_DENIED reply (to a data request) is formulated as usual. Two + new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have + been defined for the auth_stat type. When the reason for denial of + the request is a reject_stat of AUTH_ERROR, one of the two new + auth_stat values could be returned in addition to the existing + values. These two new values have special significance from the + existing reasons for denial of a request. + + The server maintains a list of contexts for the clients that are + currently in session with it. Normally, a context is destroyed when + the client ends the session corresponding to it. However, due to + resource constraints, the server may destroy a context prematurely + (on an LRU basis, or if the server machine is rebooted, for example). + In this case, when a client request comes in, there may not be a + context corresponding to its handle. The server rejects the request, + with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving + this error, the client must refresh the context - that is, + reestablish it after destroying the old one - and try the request + again. This error is also returned if the context handle matches + that of a different context that was allocated after the client's + context was destroyed (this will be detected by a failure in + verifying the header checksum). + + If the GSS_VerifyMIC() call on the header checksum (contained in the + verifier) fails to return GSS_S_COMPLETE, the server rejects the + request and returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. + + When the client's sequence number exceeds the maximum the server will + allow, the server will reject the request with the reason + RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale + while in use (due to ticket expiry in the case of the Kerberos V5 + mechanism, for example), the failures which result cause the + RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, + the client must refresh the context, and retry the request. + + For other errors, retrying will not rectify the problem and the + client must not refresh the context until the problem causing the + client request to be denied is rectified. + + If the version field in the credential does not match the version of + RPCSEC_GSS that was used when the context was created, the + AUTH_BADCRED value is returned. + + If there is a problem with the credential, such a bad length, illegal + control procedure, or an illegal service, the appropriate auth_stat + status is AUTH_BADCRED. + + + +Eisler, et. al. Standards Track [Page 15] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Other errors can be returned as appropriate. + +5.3.3.4. Mapping of GSS-API Errors to Server Responses + + During the data exchange phase, the server may invoke GSS_GetMIC(), + GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these + routines fail to return GSS_S_COMPLETE, then various unsuccessful + responses can be returned. The are described as follows for each of + the aforementioned four interfaces. + +5.3.3.4.1. GSS_GetMIC() Failure + + When GSS_GetMIC() is called to generate the verifier in the response, + a failure results in an RPC response with a reply status of + MSG_DENIED, reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CTXPROBLEM. + + When GSS_GetMIC() is called to sign the call results (service is + rpc_gss_svc_integrity), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + response is sent, the failure indication will be returned to the + server application and it can take appropriate action (such as + logging the error). + +5.3.3.4.2. GSS_VerifyMIC() Failure + + When GSS_VerifyMIC() is called to verify the verifier in request, a + failure results in an RPC response with a reply status of MSG_DENIED, + reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CREDPROBLEM. + + When GSS_VerifyMIC() is called to verify the call arguments (service + is rpc_gss_svc_integrity), a failure results in an RPC response with + a reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.3. GSS_Unwrap() Failure + + When GSS_Unwrap() is called to decrypt the call arguments (service is + rpc_gss_svc_privacy), a failure results in an RPC response with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.4. GSS_Wrap() Failure + + When GSS_Wrap() is called to encrypt the call results (service is + rpc_gss_svc_privacy), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + + + +Eisler, et. al. Standards Track [Page 16] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + response is sent, the failure indication will be returned to the + application and it can take appropriate action (such as logging the + error). + +5.4. Context Destruction + + When the client is done using the session, it must send a control + message informing the server that it no longer requires the context. + This message is formulated just like a data request packet, with the + following differences: the credential has gss_proc set to + RPCSEC_GSS_DESTROY, the procedure specified in the header is + NULLPROC, and there are no procedure arguments. The sequence number + in the request must be valid, and the header checksum in the verifier + must be valid, for the server to accept the message. The server + sends a response as it would to a data request. The client and + server must then destroy the context for the session. + + If the request to destroy the context fails for some reason, the + client need not take any special action. The server must be prepared + to deal with situations where clients never inform the server that + they no longer are in session and so don't need the server to + maintain a context. An LRU mechanism or an aging mechanism should be + employed by the server to clean up in such cases. + +6. Set of GSS-API Mechanisms + + RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and + as such it is inappropriate for the RPCSEC_GSS specification to + enumerate a minimum set of required security mechanisms and/or + quality of protections. + + If an application protocol specification references RPCSEC_GSS, the + protocol specification must list a mandatory set of { mechanism, QOP, + service } triples, such that an implementation cannot claim + conformance to the protocol specification unless it implements the + set of triples. Within each triple, mechanism is a GSS-API security + mechanism, QOP is a valid quality-of-protection within the mechanism, + and service is either rpc_gss_svc_integrity or rpc_gss_svc_privacy. + + For example, a network filing protocol built on RPC that depends on + RPCSEC_GSS for security, might require that Kerberos V5 with the + default QOP using the rpc_gss_svc_integrity service be supported by + implementations conforming to the network filing protocol + specification. + + + + + + + +Eisler, et. al. Standards Track [Page 17] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +7. Security Considerations + +7.1. Privacy of Call Header + + The reader will note that for the privacy option, only the call + arguments and results are encrypted. Information about the + application in the form of RPC program number, program version + number, and program procedure number is transmitted in the clear. + Encrypting these fields in the RPC call header would have changed the + size and format of the call header. This would have required revising + the RPC protocol which was beyond the scope of this proposal. Storing + the encrypted numbers in the credential would have obviated a + protocol change, but would have introduced more overloading of fields + and would have made implementations of RPC more complex. Even if the + fields were encrypted somehow, in most cases an attacker can + determine the program number and version number by examining the + destination address of the request and querying the rpcbind service + on the destination host [Srinivasan-bind]. In any case, even by not + encrypting the three numbers, RPCSEC_GSS still improves the state of + security over what existing RPC services have had available + previously. Implementors of new RPC services that are concerned about + this risk may opt to design in a "sub-procedure" field that is + included in the service specific call arguments. + +7.2. Sequence Number Attacks + +7.2.1. Sequence Numbers Above the Window + + An attacker cannot coax the server into raising the sequence number + beyond the range the legitimate client is aware of (and thus engineer + a denial of server attack) without constructing an RPC request that + will pass the header checksum. If the cost of verifying the header + checksum is sufficiently large (depending on the speed of the + processor doing the checksum and the cost of checksum algorithm), it + is possible to envision a denial of service attack (vandalism, in the + form of wasting processing resources) whereby the attacker sends + requests that are above the window. The simplest method might be for + the attacker to monitor the network traffic and then choose a + sequence number that is far above the current sequence number. Then + the attacker can send bogus requests using the above window sequence + number. + +7.2.2. Sequence Numbers Within or Below the Window + + If the attacker sends requests that are within or below the window, + then even if the header checksum is successfully verified, the server + will silently discard the requests because the server assumes it has + already processed the request. In this case, a server can optimize by + + + +Eisler, et. al. Standards Track [Page 18] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + skipping the header checksum verification if the sequence number is + below the window, or if it is within the window, not attempt the + checksum verification if the sequence number has already been seen. + +7.3. Message Stealing Attacks + + This proposal does not address attacks where an attacker can block or + steal messages without being detected by the server. To implement + such protection would be tantamount to assuming a state in the RPC + service. RPCSEC_GSS does not worsen this situation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 19] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Appendix A. GSS-API Major Status Codes + + The GSS-API definition [Linn] does not include numerical values for + the various GSS-API major status codes. It is expected that this will + be addressed in future RFC. Until then, this appendix defines the + values for each GSS-API major status code listed in the GSS-API + definition. If in the future, the GSS-API definition defines values + for the codes that are different than what follows, then implementors + of RPCSEC_GSS will be obliged to map them into the values defined + below. If in the future, the GSS-API definition defines additional + status codes not defined below, then the RPCSEC_GSS definition will + subsume those additional values. + + Here are the definitions of each GSS_S_* major status that the + implementor of RPCSEC_GSS can expect in the gss_major major field of + rpc_gss_init_res. These definitions are not in RPC description + language form. The numbers are in base 16 (hexadecimal): + + GSS_S_COMPLETE 0x00000000 + GSS_S_CONTINUE_NEEDED 0x00000001 + GSS_S_DUPLICATE_TOKEN 0x00000002 + GSS_S_OLD_TOKEN 0x00000004 + GSS_S_UNSEQ_TOKEN 0x00000008 + GSS_S_GAP_TOKEN 0x00000010 + GSS_S_BAD_MECH 0x00010000 + GSS_S_BAD_NAME 0x00020000 + GSS_S_BAD_NAMETYPE 0x00030000 + GSS_S_BAD_BINDINGS 0x00040000 + GSS_S_BAD_STATUS 0x00050000 + GSS_S_BAD_MIC 0x00060000 + GSS_S_BAD_SIG 0x00060000 + GSS_S_NO_CRED 0x00070000 + GSS_S_NO_CONTEXT 0x00080000 + GSS_S_DEFECTIVE_TOKEN 0x00090000 + GSS_S_DEFECTIVE_CREDENTIAL 0x000a0000 + GSS_S_CREDENTIALS_EXPIRED 0x000b0000 + GSS_S_CONTEXT_EXPIRED 0x000c0000 + GSS_S_FAILURE 0x000d0000 + GSS_S_BAD_QOP 0x000e0000 + GSS_S_UNAUTHORIZED 0x000f0000 + GSS_S_UNAVAILABLE 0x00100000 + GSS_S_DUPLICATE_ELEMENT 0x00110000 + GSS_S_NAME_NOT_MN 0x00120000 + GSS_S_CALL_INACCESSIBLE_READ 0x01000000 + GSS_S_CALL_INACCESSIBLE_WRITE 0x02000000 + GSS_S_CALL_BAD_STRUCTURE 0x03000000 + + + + + +Eisler, et. al. Standards Track [Page 20] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Note that the GSS-API major status is split into three fields as + follows: + + Most Significant Bit Least Significant Bit + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Up to one status in the Calling Error field can be logically ORed + with up to one status in the Routine Error field which in turn can be + logically ORed with zero or more statuses in the Supplementary Info + field. If the resulting major status has a non-zero Calling Error + and/or a non-zero Routine Error, then the applicable GSS-API + operation has failed. For purposes of RPCSEC_GSS, this means that + the GSS_Accept_sec_context() call executed by the server has failed. + + If the major status is equal GSS_S_COMPLETE, then this indicates the + absence of any Errors or Supplementary Info. + + The meanings of most of the GSS_S_* status are defined in the GSS-API + definition, which the exceptions of: + + GSS_S_BAD_MIC This code has the same meaning as GSS_S_BAD_SIG. + + GSS_S_CALL_INACCESSIBLE_READ + A required input parameter could not be read. + + GSS_S_CALL_INACCESSIBLE_WRITE + A required input parameter could not be written. + + GSS_S_CALL_BAD_STRUCTURE + A parameter was malformed. + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 21] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Acknowledgements + + Much of the protocol was based on the AUTH_GSSAPI security flavor + developed by Open Vision Technologies [Jaspan]. In particular, we + acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen + McDermott. + + Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike + Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to + Sun Microsystems' implementation of RPCSEC_GSS. + + Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie + Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the + specification and gave valuable feedback. + + Steve Nahm and Kathy Slattery reviewed various drafts of this + specification. + + Much of content of Appendix A was excerpted from John Wray's Work in + Progress on GSS-API Version 2 C-bindings. + +References + + [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. + (1996). "Security Mechanism Independence in ONC + RPC," Proceedings of the Sixth Annual USENIX + Security Symposium, pp. 51-65. + + [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC + RPC," `95 Proceedings of The Internet Society + Symposium on Network and Distributed System + Security, pp. 144- 151. + + [Linn] Linn, J., "Generic Security Service Application + Program Interface, Version 2", RFC 2078, January + 1997. + + [Srinivasan-bind] Srinivasan, R., "Binding Protocols for + ONC RPC Version 2", RFC 1833, August 1995. + + [Srinivasan-rpc] Srinivasan, R., "RPC: Remote Procedure Call + Protocol Specification Version 2", RFC 1831, + August 1995. + + [Srinivasan-xdr] Srinivasan, R., "XDR: External Data + Representation Standard", RFC 1832, August 1995. + + + + + +Eisler, et. al. Standards Track [Page 22] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Authors' Addresses + + Michael Eisler + Sun Microsystems, Inc. + M/S UCOS03 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (719) 599-9026 + EMail: mre@eng.sun.com + + + Alex Chiu + Sun Microsystems, Inc. + M/S UMPK17-203 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-6465 + EMail: hacker@eng.sun.com + + + Lin Ling + Sun Microsystems, Inc. + M/S UMPK17-201 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-5084 + EMail: lling@eng.sun.com + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 23] + diff --git a/doc/standardisation/rfc1831.txt b/doc/standardisation/rfc1831.txt new file mode 100644 index 000000000..0556c9e83 --- /dev/null +++ b/doc/standardisation/rfc1831.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group R. Srinivasan +Request for Comments: 1831 Sun Microsystems +Category: Standards Track August 1995 + + + RPC: Remote Procedure Call Protocol Specification Version 2 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This document describes the ONC Remote Procedure Call (ONC RPC + Version 2) protocol as it is currently deployed and accepted. "ONC" + stands for "Open Network Computing". + +TABLE OF CONTENTS + + 1. INTRODUCTION 2 + 2. TERMINOLOGY 2 + 3. THE RPC MODEL 2 + 4. TRANSPORTS AND SEMANTICS 4 + 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 + 6. AUTHENTICATION 5 + 7. RPC PROTOCOL REQUIREMENTS 5 + 7.1 RPC Programs and Procedures 6 + 7.2 Authentication 7 + 7.3 Program Number Assignment 8 + 7.4 Other Uses of the RPC Protocol 8 + 7.4.1 Batching 8 + 7.4.2 Broadcast Remote Procedure Calls 8 + 8. THE RPC MESSAGE PROTOCOL 9 + 9. AUTHENTICATION PROTOCOLS 12 + 9.1 Null Authentication 13 + 10. RECORD MARKING STANDARD 13 + 11. THE RPC LANGUAGE 13 + 11.1 An Example Service Described in the RPC Language 13 + 11.2 The RPC Language Specification 14 + 11.3 Syntax Notes 15 + APPENDIX A: SYSTEM AUTHENTICATION 16 + REFERENCES 17 + Security Considerations 18 + Author's Address 18 + + + +Srinivasan Standards Track [Page 1] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +1. INTRODUCTION + + This document specifies version two of the message protocol used in + ONC Remote Procedure Call (RPC). The message protocol is specified + with the eXternal Data Representation (XDR) language [9]. This + document assumes that the reader is familiar with XDR. It does not + attempt to justify remote procedure calls systems or describe their + use. The paper by Birrell and Nelson [1] is recommended as an + excellent background for the remote procedure call concept. + +2. TERMINOLOGY + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that makes the call to a server, + which sends back a reply. 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. A + server may support more than one version of a remote program in order + to be compatible with changing protocols. + + 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 + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms client and server only apply to a particular transaction; a + particular hardware entity (host) or software entity (process or + program) could operate in both roles at different times. For + example, a program that supplies remote execution service could also + be a client of a network file service. + +3. THE RPC MODEL + + The ONC RPC protocol is based on the remote procedure call model, + which 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 register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + + + + + +Srinivasan Standards Track [Page 2] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process, and a + server's process. The caller process first sends a call message to + the server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and caller's + execution is resumed. + + 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. + + 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 ONC 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 separate task to process + an incoming call, so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls: + + 1. Error handling: failures of the remote server or network must + be handled when using remote procedure calls. + + 2. Global variables and side-effects: since the server does not + have access to the client's address space, hidden arguments cannot + be passed as global variables or returned as side effects. + + 3. Performance: remote procedures usually operate one or more + orders of magnitude slower than local procedure calls. + + 4. Authentication: since remote procedure calls can be transported + over unsecured networks, authentication may be necessary. + Authentication prevents one entity from masquerading as some other + entity. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + + + + + + +Srinivasan Standards Track [Page 3] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +4. TRANSPORTS AND SEMANTICS + + The RPC protocol can be implemented on several different transport + protocols. The RPC protocol does not care how a message is passed + from one process to another, but only with specification and + interpretation of messages. However, the application may wish to + obtain information about (and perhaps control over) the transport + layer through an interface not specified in this document. For + example, the transport protocol may impose a restriction on the + maximum size of RPC messages, or it may be stream-oriented like TCP + with no size limit. The client and server must agree on their + transport protocol choices. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to 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 [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 [7], it must implement + its own time-out, retransmission, and duplicate detection policies as + the RPC protocol does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. 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. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + 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 + message. The main use of this transaction ID is by the client RPC + entity in matching replies to calls. However, a client application + may choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls 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. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + + + +Srinivasan Standards Track [Page 4] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + assume that 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. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC + uses both TCP and UDP transport protocols. Section 10 (RECORD + MARKING STANDARD) describes the mechanism employed by ONC RPC to + utilize a connection-oriented, stream-oriented transport such as TCP. + +5. BINDING AND RENDEZVOUS INDEPENDENCE + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. + + Implementors could 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 binding software makes RPC useful, possibly using RPC + to accomplish this task. + +6. AUTHENTICATION + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this 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 is in section 9: "Authentication Protocols". + +7. RPC PROTOCOL REQUIREMENTS + + The RPC protocol must provide for the following: + + (1) Unique specification of a procedure to be called. + (2) Provisions for matching response messages to request messages. + (3) Provisions for authenticating the caller to service and + vice-versa. + + + + + + + + + +Srinivasan Standards Track [Page 5] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + (1) RPC protocol mismatches. + (2) Remote program protocol version mismatches. + (3) Protocol errors (such as misspecification of a procedure's + parameters). + (4) Reasons why remote authentication failed. + (5) Any other reasons why the desired procedure was not called. + +7.1 RPC Programs and Procedures + + The RPC call message has three unsigned integer fields -- remote + program number, remote program version number, and remote procedure + number -- which uniquely identify the procedure to be called. + Program numbers are administered by a central authority + (rpc@sun.com). Once implementors have a program number, they can + implement their remote program; the first implementation would most + likely have the version number 1. Because most new protocols evolve, + a version field of the call message identifies which version of the + protocol the caller is using. Version numbers enable support of both + old and new protocols through the same server process. + + 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". + + 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. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + (1) The remote implementation of RPC does not support protocol + version 2. The lowest and highest supported RPC version numbers + are returned. + + (2) The remote program is not available on the remote system. + + (3) The remote program does not support the requested version + number. The lowest and highest supported remote program version + numbers are returned. + + + + +Srinivasan Standards Track [Page 6] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + (4) The requested procedure number does not exist. (This is + usually a client side protocol or programming error.) + + (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.) + +7.2 Authentication + + 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 credential 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 (in the eXternal Data Representation (XDR) language [9]): + + enum auth_flavor { + AUTH_NONE = 0, + AUTH_SYS = 1, + AUTH_SHORT = 2 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by up to 400 bytes which are opaque to + (uninterpreted by) the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields is specified by individual, independent + authentication protocol specifications. (Section 9 defines the + various authentication protocols.) + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + + + + + + + + + + + +Srinivasan Standards Track [Page 7] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +7.3 Program Number Assignment + + Program numbers are given out in groups of hexadecimal 20000000 + (decimal 536870912) according to the following chart: + + 0 - 1fffffff defined by rpc@sun.com + 20000000 - 3fffffff defined by user + 40000000 - 5fffffff transient + 60000000 - 7fffffff reserved + 80000000 - 9fffffff reserved + a0000000 - bfffffff reserved + c0000000 - dfffffff reserved + e0000000 - ffffffff reserved + + The first group is a range of numbers administered by rpc@sun.com 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. Application + developers may apply for blocks of RPC program numbers in the first + range by sending electronic mail to "rpc@sun.com". The third group + is for applications that generate program numbers dynamically. The + final groups are reserved for future use, and should not be used. + +7.4 Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure call) protocols can be implemented. + +7.4.1 Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) 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 calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + +7.4.2 Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + + + +Srinivasan Standards Track [Page 8] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + that support broadcast protocols usually respond only when the call + is successfully processed and are silent in the face of errors, but + this varies with the application. + + The principles of broadcast RPC also apply to multicasting - an RPC + request can be sent to a multicast address. + +8. THE RPC MESSAGE PROTOCOL + + This section defines the RPC message protocol in the XDR data + description language [9]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + + A reply to a call message can take on two forms: The message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4, /* procedure can't decode params */ + SYSTEM_ERR = 5 /* errors like memory allocation failure */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + Why authentication failed: + + enum auth_stat { + AUTH_OK = 0, /* success */ + + + +Srinivasan Standards Track [Page 9] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * failed at remote end + */ + AUTH_BADCRED = 1, /* bad credential (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5, /* rejected for security reasons */ + /* + * failed locally + */ + AUTH_INVALIDRESP = 6, /* bogus response verifier */ + AUTH_FAILED = 7 /* reason unknown */ + }; + + 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 REPLY message always matches that of the initiating CALL + 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. + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC 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 credential) 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. + + The purpose of the authentication verifier is to validate the + authentication credential. Note that these two items are + + + +Srinivasan Standards Track [Page 10] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + historically separate, but are always used together as one logical + entity. + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, + GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The + PROG_MISMATCH arm specifies the lowest and highest version numbers of + the remote program supported by the server. + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + + + +Srinivasan Standards Track [Page 11] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * GARBAGE_ARGS, and SYSTEM_ERR. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH), or + the server rejects the identity of the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of invalid authentication, + failure status is returned. + + 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; + }; + +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 + "rpc@sun.com". 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. + + + +Srinivasan Standards Track [Page 12] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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; + + + +Srinivasan Standards Track [Page 13] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * 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 "{" + + + +Srinivasan Standards Track [Page 14] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 15] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + 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). + + + +Srinivasan Standards Track [Page 16] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +REFERENCES + + [1] Birrell, A. D. & 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 & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [4] Mills, D., "Network Time Protocol", RFC 1305, 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, RFC 793, USC/Information + Sciences Institute, September 1981. + + [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + USC/Information Sciences Institute, August 1980. + + [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, + RFC 1700, USC/Information Sciences Institute, October 1994. + + [9] Srinivasan, R., "XDR: External Data Representation Standard", + RFC 1832, 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)", RFC 1510, Digital Equipment Corporation, + USC/Information Sciences Institute, September 1993. + + + + + + + + +Srinivasan Standards Track [Page 17] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +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: 415-336-2478 + Fax: 415-336-6015 + EMail: raj@eng.sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 18] + diff --git a/doc/standardisation/rfc2203.txt b/doc/standardisation/rfc2203.txt new file mode 100644 index 000000000..2f6a8a0d0 --- /dev/null +++ b/doc/standardisation/rfc2203.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group M. Eisler +Request for Comments: 2203 A. Chiu +Category: Standards Track L. Ling + September 1997 + + + RPCSEC_GSS Protocol Specification + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This memo describes an ONC/RPC security flavor that allows RPC + protocols to access the Generic Security Services Application + Programming Interface (referred to henceforth as GSS-API). + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. The ONC RPC Message Protocol . . . . . . . . . . . . . . . . . 2 + 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 3 + 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 3 + 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 3 + 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 5 + 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 5 + 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 5 + 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 6 + 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 8 + 5.2.3.1. Context Creation Response - Successful Acceptance . . . 8 + 5.2.3.1.1. Client Processing of Successful Context Creation + Responses . . . . . . . . . . . . . . . . . . . . . . 9 + 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . . 9 + 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 10 + 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 10 + 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 11 + 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 11 + 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 11 + 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 12 + 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 12 + 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 12 + 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 + 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 15 + + + +Eisler, et. al. Standards Track [Page 1] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 16 + 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 + 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 16 + 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 17 + 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 + 7. Security Considerations . . . . . . . . . . . . . . . . . . 18 + 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 18 + 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 + 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 + 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 + 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 19 + Appendix A. GSS-API Major Status Codes . . . . . . . . . . . . . 20 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 + +1. Introduction + + This document describes the protocol used by the RPCSEC_GSS security + flavor. Security flavors have been called authentication flavors for + historical reasons. This memo recognizes that there are two other + security services besides authentication, integrity, and privacy, and + so defines a new RPCSEC_GSS security flavor. + + The protocol is described using the XDR language [Srinivasan-xdr]. + The reader is assumed to be familiar with ONC RPC and the security + flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be + familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security + flavor uses GSS-API interfaces to provide security services that are + independent of the underlying security mechanism. + +2. The ONC RPC Message Protocol + + This memo refers to the following XDR types of the ONC RPC protocol, + which are described in the document entitled Remote Procedure Call + Protocol Specification Version 2 [Srinivasan-rpc]: + + msg_type + reply_stat + auth_flavor + accept_stat + reject_stat + auth_stat + opaque_auth + rpc_msg + call_body + reply_body + + + +Eisler, et. al. Standards Track [Page 2] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + accepted_reply + rejected_reply + +3. Flavor Number Assignment + + The RPCSEC_GSS security flavor has been assigned the value of 6: + + enum auth_flavor { + ... + RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ + }; + +4. New auth_stat Values + + RPCSEC_GSS requires the addition of two new values to the auth_stat + enumerated type definition: + + enum auth_stat { + ... + /* + * RPCSEC_GSS errors + */ + RPCSEC_GSS_CREDPROBLEM = 13, + RPCSEC_GSS_CTXPROBLEM = 14 + }; + + The descriptions of these two new values are defined later in this + memo. + +5. Elements of the RPCSEC_GSS Security Protocol + + An RPC session based on the RPCSEC_GSS security flavor consists of + three phases: context creation, RPC data exchange, and context + destruction. In the following discussion, protocol elements for + these three phases are described. + + The following description of the RPCSEC_GSS protocol uses some of the + definitions within XDR language description of the RPC protocol. + + Context creation and destruction use control messages that are not + dispatched to service procedures registered by an RPC server. The + program and version numbers used in these control messages are the + same as the RPC service's program and version numbers. The procedure + number used is NULLPROC (zero). A field in the credential + information (the gss_proc field which is defined in the + rpc_gss_cred_t structure below) specifies whether a message is to be + interpreted as a control message or a regular RPC message. If this + field is set to RPCSEC_GSS_DATA, no control action is implied; in + + + +Eisler, et. al. Standards Track [Page 3] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + this case, it is a regular data message. If this field is set to any + other value, a control action is implied. This is described in the + following sections. + + Just as with normal RPC data exchange messages, the transaction + identifier (the xid field in struct rpc_msg), should be set to unique + values on each call for context creation and context destruction. + + The following definitions are used for describing the protocol. + + /* RPCSEC_GSS control procedures */ + + + enum rpc_gss_proc_t { + RPCSEC_GSS_DATA = 0, + RPCSEC_GSS_INIT = 1, + RPCSEC_GSS_CONTINUE_INIT = 2, + RPCSEC_GSS_DESTROY = 3 + }; + + /* RPCSEC_GSS services */ + + enum rpc_gss_service_t { + /* Note: the enumerated value for 0 is reserved. */ + rpc_gss_svc_none = 1, + rpc_gss_svc_integrity = 2, + rpc_gss_svc_privacy = 3 + }; + + /* Credential */ + + /* + * Note: version 0 is reserved for possible future + * definition of a version negotiation protocol + * + */ + #define RPCSEC_GSS_VERS_1 1 + + struct rpc_gss_cred_t { + union switch (unsigned int version) { /* version of + RPCSEC_GSS */ + case RPCSEC_GSS_VERS_1: + struct { + rpc_gss_proc_t gss_proc; /* control procedure */ + unsigned int seq_num; /* sequence number */ + rpc_gss_service_t service; /* service used */ + opaque handle<>; /* context handle */ + } rpc_gss_cred_vers_1_t; + + + +Eisler, et. al. Standards Track [Page 4] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + } + }; + + /* Maximum sequence number value */ + + #define MAXSEQ 0x80000000 + +5.1. Version Selection + + This document defines just one protocol version (RPCSEC_GSS_VERS_1). + The client should assume that the server supports RPCSEC_GSS_VERS_1 + and issue a Context Creation message (as described in the section + RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of + MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of + AUTH_REJECTED_CRED. + +5.2. Context Creation + + Before RPC data is exchanged on a session using the RPCSEC_GSS + flavor, a context must be set up between the client and the server. + Context creation may involve zero or more RPC exchanges. The number + of exchanges depends on the security mechanism. + +5.2.1. Mechanism and QOP Selection + + There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API + mechanism identifiers or QOP values. At minimum, it is expected that + implementations of the RPCSEC_GSS protocol provide a means to: + + * specify mechanism identifiers, QOP values, and RPCSEC_GSS + service values on the client side, and to + + * enforce mechanism identifiers, QOP values, and RPCSEC_GSS + service values on a per-request basis on the server side. + + It is necessary that above capabilities exist so that applications + have the means to conform the required set of required set of + tuples (See the section entitled Set of + GSS-API Mechanisms). An application may negotiate selection within its protocol or via an out of band + protocol. Hence it may be necessary for RPCSEC_GSS implementations to + provide programming interfaces for the specification and enforcement + of . + + Additionally, implementations may depend on negotiation schemes + constructed as pseudo-mechanisms under the GSS-API. Because such + schemes are below the GSS-API layer, the RPCSEC_GSS protocol, as + specified in this document, can make use of them. + + + +Eisler, et. al. Standards Track [Page 5] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.2. Context Creation Requests + + The first RPC request from the client to the server initiates context + creation. Within the RPC message protocol's call_body structure, + rpcvers is set to 2. prog and vers are always those for the service + being accessed. The proc is always set to NULLPROC (zero). + + Within the RPC message protocol's cred structure, flavor is set to + RPCSEC_GSS (6). The opaque data of the cred structure (the body + field) constituting the credential encodes the rpc_gss_cred_t + structure defined previously. + + The values of the fields contained in the rpc_gss_cred_t structure + are set as follows. The version field is set to the version of the + RPCSEC_GSS protocol the client wants to use. The remainder of this + memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the + version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field + must be set to RPCSEC_GSS_INIT for the first creation request. In + subsequent creation requests, the gss_proc field must be set to + RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and + service fields are undefined and both must be ignored by the server. + In the first creation request, the handle field is NULL (opaque data + of zero length). In subsequent creation requests, handle must be + equal to the value returned by the server. The handle field serves + as the identifier for the context, and will not change for the + duration of the context, including responses to + RPCSEC_GSS_CONTINUE_INIT. + + The verifier field in the RPC message header is also described by the + opaque_auth structure. All creation requests have the NULL verifier + (AUTH_NONE flavor with zero length opaque data). + + Following the verifier are the call data (procedure specific + parameters). Note that the proc field of the call_body structure is + set to NULLPROC, and thus normally there would be zero octets + following the verifier. However, since there is no RPC data exchange + during a context creation, it is safe to transfer information + following the verifier. It is necessary to "overload" the call data + in this way, rather than pack the GSS-API token into the RPC header, + because RPC Version 2 restricts the amount of data that can be sent + in the header. The opaque body of the credential and verifier fields + can be each at most 400 octets long, and GSS tokens can be longer + than 800 octets. + + + + + + + + +Eisler, et. al. Standards Track [Page 6] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The call data for a context creation request is described by the + following structure for all creation requests: + + struct rpc_gss_init_arg { + opaque gss_token<>; + }; + + Here, gss_token is the token returned by the call to GSS-API's + GSS_Init_sec_context() routine, opaquely encoded. The value of this + field will likely be different in each creation request, if there is + more than one creation request. If no token is returned by the call + to GSS_Init_sec_context(), the context must have been created + (assuming no errors), and there will not be any more creation + requests. + + When GSS_Init_sec_context() is called, the parameters + replay_det_req_flag and sequence_req_flag must be turned off. The + reasons for this are: + + * ONC RPC can be used over unreliable transports and provides no + layer to reliably re-assemble messages. Thus it is possible for + gaps in message sequencing to occur, as well as out of order + messages. + + * RPC servers can be multi-threaded, and thus the order in which + GSS-API messages are signed or wrapped can be different from the + order in which the messages are verified or unwrapped, even if + the requests are sent on reliable transports. + + * To maximize convenience of implementation, the order in which an + ONC RPC entity will verify the header and verify/unwrap the body + of an RPC call or reply is left unspecified. + + The RPCSEC_GSS protocol provides for protection from replay attack, + yet tolerates out-of-order delivery or processing of messages and + tolerates dropped requests. + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 7] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.3. Context Creation Responses + +5.2.3.1. Context Creation Response - Successful Acceptance + + The response to a successful creation request has an MSG_ACCEPTED + response with a status of SUCCESS. The results field encodes a + response with the following structure: + + struct rpc_gss_init_res { + opaque handle<>; + unsigned int gss_major; + unsigned int gss_minor; + unsigned int seq_window; + opaque gss_token<>; + }; + + Here, handle is non-NULL opaque data that serves as the context + identifier. The client must use this value in all subsequent requests + whether control messages or otherwise). The gss_major and gss_minor + fields contain the results of the call to GSS_Accept_sec_context() + executed by the server. The values for the gss_major field are + defined in Appendix A of this document. The values for the gss_minor + field are GSS-API mechanism specific and are defined in the + mechanism's specification. If gss_major is not one of GSS_S_COMPLETE + or GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case + handle and gss_token must be set to NULL by the server. The value of + gss_minor is dependent on the value of gss_major and the security + mechanism used. The gss_token field contains any token returned by + the GSS_Accept_sec_context() call executed by the server. A token + may be returned for both successful values of gss_major. If the + value is GSS_S_COMPLETE, it indicates that the server is not + expecting any more tokens, and the RPC Data Exchange phase must begin + on the subsequent request from the client. If the value is + GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence + the client must send at least one more creation request (with + gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) + carrying the required token. + + In a successful response, the seq_window field is set to the sequence + window length supported by the server for this context. This window + specifies the maximum number of client requests that may be + outstanding for this context. The server will accept "seq_window" + requests at a time, and these may be out of order. The client may + use this number to determine the number of threads that can + simultaneously send requests on this context. + + + + + + +Eisler, et. al. Standards Track [Page 8] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in + the response) flavor field is set to RPCSEC_GSS, and the body field + set to the checksum of the seq_window (in network order). The QOP + used for this checksum is 0 (zero), which is the default QOP. For + all other values of gss_major, a NULL verifier (AUTH_NONE flavor with + zero-length opaque data) is used. + +5.2.3.1.1. Client Processing of Successful Context Creation Responses + + If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, + then the client, per the GSS-API specification, must invoke + GSS_Init_sec_context() using the token returned in gss_token in the + context creation response. The client must then generate a context + creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. + + If the value of gss_major in the response is GSS_S_COMPLETE, and if + the client's previous invocation of GSS_Init_sec_context() returned a + gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the + GSS-API specification, must invoke GSS_Init_sec_context() using the + token returned in gss_token in the context creation response. If + GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is + successfully set up, and the RPC data exchange phase must begin on + the subsequent request from the client. + +5.2.3.2. Context Creation Response - Unsuccessful Cases + + An MSG_ACCEPTED reply (to a creation request) with an acceptance + status of other than SUCCESS has a NULL verifier (flavor set to + AUTH_NONE, and zero length opaque data in the body field), and is + formulated as usual for different status values. + + An MSG_DENIED reply (to a creation request) is also formulated as + usual. Note that MSG_DENIED could be returned because the server's + RPC implementation does not recognize the RPCSEC_GSS security flavor. + RFC 1831 does not specify the appropriate reply status in this + instance, but common implementation practice appears to be to return + a rejection status of AUTH_ERROR with an auth_stat of + AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_CREDPROBLEM + and RPCSEC_GSS_CTXPROBLEM) have been defined for the auth_stat type, + neither of these two can be returned in responses to context creation + requests. The auth_stat new values can be used for responses to + normal (data) requests. This is described later. + + MSG_DENIED might also be returned if the RPCSEC_GSS version number in + the credential is not supported on the server. In that case, the + server returns a rejection status of AUTH_ERROR, with an auth_stat of + + AUTH_REJECTED_CRED. + + + +Eisler, et. al. Standards Track [Page 9] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3. RPC Data Exchange + + The data exchange phase is entered after a context has been + successfully set up. The format of the data exchanged depends on the + security service used for the request. Although clients can change + the security service and QOP used on a per-request basis, this may + not be acceptable to all RPC services; some RPC services may "lock" + the data exchange phase into using the QOP and service used on the + first data exchange message. For all three modes of service (no data + integrity, data integrity, data privacy), the RPC request header has + the same format. + +5.3.1. RPC Request Header + + The credential has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The credential body is created by + XDR encoding the rpc_gss_cred_t structure listed earlier into an + octet stream, and then opaquely encoding this octet stream as the + body field. + + Values of the fields contained in the rpc_gss_cred_t structure are + set as follows. The version field is set to same version value that + was used to create the context, which within the scope of this memo + will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to + RPCSEC_GSS_DATA. The service field is set to indicate the desired + service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or + rpc_gss_svc_privacy). The handle field is set to the context handle + value received from the RPC server during context creation. The + seq_num field can start at any value below MAXSEQ, and must be + incremented (by one or more) for successive requests. Use of + sequence numbers is described in detail when server processing of the + request is discussed. + + The verifier has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The body field is set as follows. + The checksum of the RPC header (up to and including the credential) + is computed using the GSS_GetMIC() call with the desired QOP. This + returns the checksum as an opaque octet stream and its length. This + is encoded into the body field. Note that the QOP is not explicitly + specified anywhere in the request. It is implicit in the checksum or + encrypted data. The same QOP value as is used for the header + checksum must also be used for the data (for checksumming or + encrypting), unless the service used for the request is + rpc_gss_svc_none. + + + + + + + +Eisler, et. al. Standards Track [Page 10] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.2. RPC Request Data + +5.3.2.1. RPC Request Data - No Data Integrity + + If the service specified is rpc_gss_svc_none, the data (procedure + arguments) are not integrity or privacy protected. They are sent in + exactly the same way as they would be if the AUTH_NONE flavor were + used (following the verifier). Note, however, that since the RPC + header is integrity protected, the sender will still be authenticated + in this case. + +5.3.2.2. RPC Request Data - With Data Integrity + + When data integrity is used, the request data is represented as + follows: + + struct rpc_gss_integ_data { + opaque databody_integ<>; + opaque checksum<>; + }; + + The databody_integ field is created as follows. A structure + consisting of a sequence number followed by the procedure arguments + is constructed. This is shown below as the type rpc_gss_data_t: + + struct rpc_gss_data_t { + unsigned int seq_num; + proc_req_arg_t arg; + }; + + Here, seq_num must have the same value as in the credential. The + type proc_req_arg_t is the procedure specific XDR type describing the + procedure arguments (and so is not specified here). The octet stream + corresponding to the XDR encoded rpc_gss_data_t structure and its + length are placed in the databody_integ field. Note that because the + XDR type of databody_integ is opaque, the XDR encoding of + databody_integ will include an initial four octet length field, + followed by the XDR encoded octet stream of rpc_gss_data_t. + + The checksum field represents the checksum of the XDR encoded octet + stream corresponding to the XDR encoded rpc_gss_data_t structure + (note, this is not the checksum of the databody_integ field). This + is obtained using the GSS_GetMIC() call, with the same QOP as was + used to compute the header checksum (in the verifier). The + + + + + + + +Eisler, et. al. Standards Track [Page 11] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + GSS_GetMIC() call returns the checksum as an opaque octet stream and + its length. The checksum field of struct rpc_gss_integ_data has an + XDR type of opaque. Thus the checksum length from GSS_GetMIC() is + encoded as a four octet length field, followed by the checksum, + padded to a multiple of four octets. + +5.3.2.3. RPC Request Data - With Data Privacy + + When data privacy is used, the request data is represented as + follows: + + struct rpc_gss_priv_data { + opaque databody_priv<> + }; + + The databody_priv field is created as follows. The rpc_gss_data_t + structure described earlier is constructed again in the same way as + for the case of data integrity. Next, the GSS_Wrap() call is invoked + to encrypt the octet stream corresponding to the rpc_gss_data_t + structure, using the same value for QOP (argument qop_req to + GSS_Wrap()) as was used for the header checksum (in the verifier) and + conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() + call returns an opaque octet stream (representing the encrypted + rpc_gss_data_t structure) and its length, and this is encoded as the + databody_priv field. Since databody_priv has an XDR type of opaque, + the length returned by GSS_Wrap() is encoded as the four octet + length, followed by the encrypted octet stream (padded to a multiple + of four octets). + +5.3.3. Server Processing of RPC Data Requests + +5.3.3.1. Context Management + + When a request is received by the server, the following are verified + to be acceptable: + + * the version number in the credential + + * the service specified in the credential + + * the context handle specified in the credential + + * the header checksum in the verifier (via GSS_VerifyMIC()) + + * the sequence number (seq_num) specified in the credential (more + on this follows) + + + + + +Eisler, et. al. Standards Track [Page 12] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The gss_proc field in the credential must be set to RPCSEC_GSS_DATA + for data requests (otherwise, the message will be interpreted as a + control message). + + The server maintains a window of "seq_window" sequence numbers, + starting with the last sequence number seen and extending backwards. + If a sequence number higher than the last number seen is received + (AND if GSS_VerifyMIC() on the header checksum from the verifier + returns GSS_S_COMPLETE), the window is moved forward to the new + sequence number. If the last sequence number seen is N, the server + is prepared to receive requests with sequence numbers in the range N + through (N - seq_window + 1), both inclusive. If the sequence number + received falls below this range, it is silently discarded. If the + sequence number is within this range, and the server has not seen it, + the request is accepted, and the server turns on a bit to "remember" + that this sequence number has been seen. If the server determines + that it has already seen a sequence number within the window, the + request is silently discarded. The server should select a seq_window + value based on the number requests it expects to process + simultaneously. For example, in a threaded implementation seq_window + might be equal to the number of server threads. There are no known + security issues with selecting a large window. The primary issue is + how much space the server is willing to allocate to keep track of + requests received within the window. + + The reason for discarding requests silently is that the server is + unable to determine if the duplicate or out of range request was due + to a sequencing problem in the client, network, or the operating + system, or due to some quirk in routing, or a replay attack by an + intruder. Discarding the request allows the client to recover after + timing out, if indeed the duplication was unintentional or well + intended. Note that a consequence of the silent discard is that + clients may increment the seq_num by more than one. The effect of + this is that the window will move forward more quickly. It is not + believed that there is any benefit to doing this. + + Note that the sequence number algorithm requires that the client + increment the sequence number even if it is retrying a request with + the same RPC transaction identifier. It is not infrequent for + clients to get into a situation where they send two or more attempts + and a slow server sends the reply for the first attempt. With + RPCSEC_GSS, each request and reply will have a unique sequence + number. If the client wishes to improve turn around time on the RPC + call, it can cache the RPCSEC_GSS sequence number of each request it + sends. Then when it receives a response with a matching RPC + transaction identifier, it can compute the checksum of each sequence + number in the cache to try to match the checksum in the reply's + verifier. + + + +Eisler, et. al. Standards Track [Page 13] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The data is decoded according to the service specified in the + credential. In the case of integrity or privacy, the server ensures + that the QOP value is acceptable, and that it is the same as that + used for the header checksum in the verifier. Also, in the case of + integrity or privacy, the server will reject the message (with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS) if the sequence number embedded in the request body is + different from the sequence number in the credential. + +5.3.3.2. Server Reply - Request Accepted + + An MSG_ACCEPTED reply to a request in the data exchange phase will + have the verifier's (the verf element in the response) flavor field + set to RPCSEC_GSS, and the body field set to the checksum (the output + of GSS_GetMIC()) of the sequence number (in network order) of the + corresponding request. The QOP used is the same as the QOP used for + the corresponding request. + + If the status of the reply is not SUCCESS, the rest of the message is + formatted as usual. + + If the status of the message is SUCCESS, the format of the rest of + the message depends on the service specified in the corresponding + request message. Basically, what follows the verifier in this case + are the procedure results, formatted in different ways depending on + the requested service. + + If no data integrity was requested, the procedure results are + formatted as for the AUTH_NONE security flavor. + + If data integrity was requested, the results are encoded in exactly + the same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Integrity.' + The only difference is that the structure representing the + procedure's result - proc_res_arg_t - must be substituted in place of + the request argument structure proc_req_arg_t. The QOP used for the + checksum must be the same as that used for constructing the reply + verifier. + + If data privacy was requested, the results are encoded in exactly the + same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Privacy.' The + QOP used for encryption must be the same as that used for + constructing the reply verifier. + + + + + + + +Eisler, et. al. Standards Track [Page 14] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.3.3. Server Reply - Request Denied + + An MSG_DENIED reply (to a data request) is formulated as usual. Two + new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have + been defined for the auth_stat type. When the reason for denial of + the request is a reject_stat of AUTH_ERROR, one of the two new + auth_stat values could be returned in addition to the existing + values. These two new values have special significance from the + existing reasons for denial of a request. + + The server maintains a list of contexts for the clients that are + currently in session with it. Normally, a context is destroyed when + the client ends the session corresponding to it. However, due to + resource constraints, the server may destroy a context prematurely + (on an LRU basis, or if the server machine is rebooted, for example). + In this case, when a client request comes in, there may not be a + context corresponding to its handle. The server rejects the request, + with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving + this error, the client must refresh the context - that is, + reestablish it after destroying the old one - and try the request + again. This error is also returned if the context handle matches + that of a different context that was allocated after the client's + context was destroyed (this will be detected by a failure in + verifying the header checksum). + + If the GSS_VerifyMIC() call on the header checksum (contained in the + verifier) fails to return GSS_S_COMPLETE, the server rejects the + request and returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. + + When the client's sequence number exceeds the maximum the server will + allow, the server will reject the request with the reason + RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale + while in use (due to ticket expiry in the case of the Kerberos V5 + mechanism, for example), the failures which result cause the + RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, + the client must refresh the context, and retry the request. + + For other errors, retrying will not rectify the problem and the + client must not refresh the context until the problem causing the + client request to be denied is rectified. + + If the version field in the credential does not match the version of + RPCSEC_GSS that was used when the context was created, the + AUTH_BADCRED value is returned. + + If there is a problem with the credential, such a bad length, illegal + control procedure, or an illegal service, the appropriate auth_stat + status is AUTH_BADCRED. + + + +Eisler, et. al. Standards Track [Page 15] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Other errors can be returned as appropriate. + +5.3.3.4. Mapping of GSS-API Errors to Server Responses + + During the data exchange phase, the server may invoke GSS_GetMIC(), + GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these + routines fail to return GSS_S_COMPLETE, then various unsuccessful + responses can be returned. The are described as follows for each of + the aforementioned four interfaces. + +5.3.3.4.1. GSS_GetMIC() Failure + + When GSS_GetMIC() is called to generate the verifier in the response, + a failure results in an RPC response with a reply status of + MSG_DENIED, reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CTXPROBLEM. + + When GSS_GetMIC() is called to sign the call results (service is + rpc_gss_svc_integrity), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + response is sent, the failure indication will be returned to the + server application and it can take appropriate action (such as + logging the error). + +5.3.3.4.2. GSS_VerifyMIC() Failure + + When GSS_VerifyMIC() is called to verify the verifier in request, a + failure results in an RPC response with a reply status of MSG_DENIED, + reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CREDPROBLEM. + + When GSS_VerifyMIC() is called to verify the call arguments (service + is rpc_gss_svc_integrity), a failure results in an RPC response with + a reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.3. GSS_Unwrap() Failure + + When GSS_Unwrap() is called to decrypt the call arguments (service is + rpc_gss_svc_privacy), a failure results in an RPC response with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.4. GSS_Wrap() Failure + + When GSS_Wrap() is called to encrypt the call results (service is + rpc_gss_svc_privacy), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + + + +Eisler, et. al. Standards Track [Page 16] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + response is sent, the failure indication will be returned to the + application and it can take appropriate action (such as logging the + error). + +5.4. Context Destruction + + When the client is done using the session, it must send a control + message informing the server that it no longer requires the context. + This message is formulated just like a data request packet, with the + following differences: the credential has gss_proc set to + RPCSEC_GSS_DESTROY, the procedure specified in the header is + NULLPROC, and there are no procedure arguments. The sequence number + in the request must be valid, and the header checksum in the verifier + must be valid, for the server to accept the message. The server + sends a response as it would to a data request. The client and + server must then destroy the context for the session. + + If the request to destroy the context fails for some reason, the + client need not take any special action. The server must be prepared + to deal with situations where clients never inform the server that + they no longer are in session and so don't need the server to + maintain a context. An LRU mechanism or an aging mechanism should be + employed by the server to clean up in such cases. + +6. Set of GSS-API Mechanisms + + RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and + as such it is inappropriate for the RPCSEC_GSS specification to + enumerate a minimum set of required security mechanisms and/or + quality of protections. + + If an application protocol specification references RPCSEC_GSS, the + protocol specification must list a mandatory set of { mechanism, QOP, + service } triples, such that an implementation cannot claim + conformance to the protocol specification unless it implements the + set of triples. Within each triple, mechanism is a GSS-API security + mechanism, QOP is a valid quality-of-protection within the mechanism, + and service is either rpc_gss_svc_integrity or rpc_gss_svc_privacy. + + For example, a network filing protocol built on RPC that depends on + RPCSEC_GSS for security, might require that Kerberos V5 with the + default QOP using the rpc_gss_svc_integrity service be supported by + implementations conforming to the network filing protocol + specification. + + + + + + + +Eisler, et. al. Standards Track [Page 17] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +7. Security Considerations + +7.1. Privacy of Call Header + + The reader will note that for the privacy option, only the call + arguments and results are encrypted. Information about the + application in the form of RPC program number, program version + number, and program procedure number is transmitted in the clear. + Encrypting these fields in the RPC call header would have changed the + size and format of the call header. This would have required revising + the RPC protocol which was beyond the scope of this proposal. Storing + the encrypted numbers in the credential would have obviated a + protocol change, but would have introduced more overloading of fields + and would have made implementations of RPC more complex. Even if the + fields were encrypted somehow, in most cases an attacker can + determine the program number and version number by examining the + destination address of the request and querying the rpcbind service + on the destination host [Srinivasan-bind]. In any case, even by not + encrypting the three numbers, RPCSEC_GSS still improves the state of + security over what existing RPC services have had available + previously. Implementors of new RPC services that are concerned about + this risk may opt to design in a "sub-procedure" field that is + included in the service specific call arguments. + +7.2. Sequence Number Attacks + +7.2.1. Sequence Numbers Above the Window + + An attacker cannot coax the server into raising the sequence number + beyond the range the legitimate client is aware of (and thus engineer + a denial of server attack) without constructing an RPC request that + will pass the header checksum. If the cost of verifying the header + checksum is sufficiently large (depending on the speed of the + processor doing the checksum and the cost of checksum algorithm), it + is possible to envision a denial of service attack (vandalism, in the + form of wasting processing resources) whereby the attacker sends + requests that are above the window. The simplest method might be for + the attacker to monitor the network traffic and then choose a + sequence number that is far above the current sequence number. Then + the attacker can send bogus requests using the above window sequence + number. + +7.2.2. Sequence Numbers Within or Below the Window + + If the attacker sends requests that are within or below the window, + then even if the header checksum is successfully verified, the server + will silently discard the requests because the server assumes it has + already processed the request. In this case, a server can optimize by + + + +Eisler, et. al. Standards Track [Page 18] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + skipping the header checksum verification if the sequence number is + below the window, or if it is within the window, not attempt the + checksum verification if the sequence number has already been seen. + +7.3. Message Stealing Attacks + + This proposal does not address attacks where an attacker can block or + steal messages without being detected by the server. To implement + such protection would be tantamount to assuming a state in the RPC + service. RPCSEC_GSS does not worsen this situation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 19] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Appendix A. GSS-API Major Status Codes + + The GSS-API definition [Linn] does not include numerical values for + the various GSS-API major status codes. It is expected that this will + be addressed in future RFC. Until then, this appendix defines the + values for each GSS-API major status code listed in the GSS-API + definition. If in the future, the GSS-API definition defines values + for the codes that are different than what follows, then implementors + of RPCSEC_GSS will be obliged to map them into the values defined + below. If in the future, the GSS-API definition defines additional + status codes not defined below, then the RPCSEC_GSS definition will + subsume those additional values. + + Here are the definitions of each GSS_S_* major status that the + implementor of RPCSEC_GSS can expect in the gss_major major field of + rpc_gss_init_res. These definitions are not in RPC description + language form. The numbers are in base 16 (hexadecimal): + + GSS_S_COMPLETE 0x00000000 + GSS_S_CONTINUE_NEEDED 0x00000001 + GSS_S_DUPLICATE_TOKEN 0x00000002 + GSS_S_OLD_TOKEN 0x00000004 + GSS_S_UNSEQ_TOKEN 0x00000008 + GSS_S_GAP_TOKEN 0x00000010 + GSS_S_BAD_MECH 0x00010000 + GSS_S_BAD_NAME 0x00020000 + GSS_S_BAD_NAMETYPE 0x00030000 + GSS_S_BAD_BINDINGS 0x00040000 + GSS_S_BAD_STATUS 0x00050000 + GSS_S_BAD_MIC 0x00060000 + GSS_S_BAD_SIG 0x00060000 + GSS_S_NO_CRED 0x00070000 + GSS_S_NO_CONTEXT 0x00080000 + GSS_S_DEFECTIVE_TOKEN 0x00090000 + GSS_S_DEFECTIVE_CREDENTIAL 0x000a0000 + GSS_S_CREDENTIALS_EXPIRED 0x000b0000 + GSS_S_CONTEXT_EXPIRED 0x000c0000 + GSS_S_FAILURE 0x000d0000 + GSS_S_BAD_QOP 0x000e0000 + GSS_S_UNAUTHORIZED 0x000f0000 + GSS_S_UNAVAILABLE 0x00100000 + GSS_S_DUPLICATE_ELEMENT 0x00110000 + GSS_S_NAME_NOT_MN 0x00120000 + GSS_S_CALL_INACCESSIBLE_READ 0x01000000 + GSS_S_CALL_INACCESSIBLE_WRITE 0x02000000 + GSS_S_CALL_BAD_STRUCTURE 0x03000000 + + + + + +Eisler, et. al. Standards Track [Page 20] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Note that the GSS-API major status is split into three fields as + follows: + + Most Significant Bit Least Significant Bit + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Up to one status in the Calling Error field can be logically ORed + with up to one status in the Routine Error field which in turn can be + logically ORed with zero or more statuses in the Supplementary Info + field. If the resulting major status has a non-zero Calling Error + and/or a non-zero Routine Error, then the applicable GSS-API + operation has failed. For purposes of RPCSEC_GSS, this means that + the GSS_Accept_sec_context() call executed by the server has failed. + + If the major status is equal GSS_S_COMPLETE, then this indicates the + absence of any Errors or Supplementary Info. + + The meanings of most of the GSS_S_* status are defined in the GSS-API + definition, which the exceptions of: + + GSS_S_BAD_MIC This code has the same meaning as GSS_S_BAD_SIG. + + GSS_S_CALL_INACCESSIBLE_READ + A required input parameter could not be read. + + GSS_S_CALL_INACCESSIBLE_WRITE + A required input parameter could not be written. + + GSS_S_CALL_BAD_STRUCTURE + A parameter was malformed. + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 21] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Acknowledgements + + Much of the protocol was based on the AUTH_GSSAPI security flavor + developed by Open Vision Technologies [Jaspan]. In particular, we + acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen + McDermott. + + Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike + Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to + Sun Microsystems' implementation of RPCSEC_GSS. + + Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie + Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the + specification and gave valuable feedback. + + Steve Nahm and Kathy Slattery reviewed various drafts of this + specification. + + Much of content of Appendix A was excerpted from John Wray's Work in + Progress on GSS-API Version 2 C-bindings. + +References + + [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. + (1996). "Security Mechanism Independence in ONC + RPC," Proceedings of the Sixth Annual USENIX + Security Symposium, pp. 51-65. + + [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC + RPC," `95 Proceedings of The Internet Society + Symposium on Network and Distributed System + Security, pp. 144- 151. + + [Linn] Linn, J., "Generic Security Service Application + Program Interface, Version 2", RFC 2078, January + 1997. + + [Srinivasan-bind] Srinivasan, R., "Binding Protocols for + ONC RPC Version 2", RFC 1833, August 1995. + + [Srinivasan-rpc] Srinivasan, R., "RPC: Remote Procedure Call + Protocol Specification Version 2", RFC 1831, + August 1995. + + [Srinivasan-xdr] Srinivasan, R., "XDR: External Data + Representation Standard", RFC 1832, August 1995. + + + + + +Eisler, et. al. Standards Track [Page 22] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Authors' Addresses + + Michael Eisler + Sun Microsystems, Inc. + M/S UCOS03 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (719) 599-9026 + EMail: mre@eng.sun.com + + + Alex Chiu + Sun Microsystems, Inc. + M/S UMPK17-203 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-6465 + EMail: hacker@eng.sun.com + + + Lin Ling + Sun Microsystems, Inc. + M/S UMPK17-201 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-5084 + EMail: lling@eng.sun.com + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 23] +