xref: /dports/sysutils/vector/vector-0.10.0/cargo-crates/krb5-src-0.2.4+1.18.2/krb5/doc/rpc/design.tex

\documentstyle[fullpage,12pt]{article}

\title{GSS-API Extensions to Sun RPC}
\date{Draft---\today}
\author{Barry Jaspan}

\setlength{\parskip}{.7\baselineskip}
\setlength{\parindent}{0pt}

\makeatletter
\newcount\savecnt\savecnt=0
\def\saveenum#1{\global\savecnt=\csname c@enum#1\endcsname}
\def\restoreenum#1{\csname c@enum#1\endcsname=\savecnt}
\makeatother

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Make _ actually generate an _, and allow line-breaking after it.
\let\underscore=\_
\catcode`_=13
\def_{\underscore\penalty75\relax}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}


{\setlength{\parskip}{0pt}\maketitle\tableofcontents}

\section{Introduction}

This document describes the integration of GSS-API authentication and
security with Sun RPC.

\section{Requirements}

The requirements of the GSS-API authentication system for Sun RPC are:

\begin{enumerate}
\item It must provide mutual authentication between RPC clients and
servers.

\item It must provide for integrity checking and encryption of all
procedure arguments and results passed over the network.
\saveenum{i}
\end{enumerate}

The following features are desired, but not mandatory:

\begin{enumerate}
\restoreenum{i}
\item It should provide for integrity checking and encryption of all
``header information'' that specifies the program and procedure being
called.

\item It should obey the Sun RPC protocol so that clients using
it can interoperate with existing servers.  In this case,
``interoperate'' means that existing servers will return an error code
indicating that they do not understand the authentication flavor, but
not that they do not understand the request at all.

\item It should require minimal or no changes to the standard Sun RPC
programming paradigm for either clients or servers so that existing
code can use it with little or no effort.

\item It should operate correctly with all the standard Sun RPC
transport mechansims (e.g. UDP and TCP).
\saveenum{i}
\end{enumerate}

\section{Functional Specification}

This section describes the programmer's interface to the GSS-API
authentication flavor.   Knowledge of standard Sun RPC programming is
assumed.

\subsection{Client Side}

A RPC client can select the GSS-API authentication flavor in the same
way it can select any other authentication flavor, by setting the
cl_auth field of the CLIENT structure to the appropriate value:

\begin{verbatim}
    clnt = clnt_create(server_host, PROG_NUM, PROG_VERS, protocol);
    clnt->cl_auth = auth_gssapi_create(clnt, ...);
\end{verbatim}

There are two functions that create GSS-API authentication flavor
structures for the cl_auth field, auth_gssapi_create and
auth_gssapi_create_default.

\begin{verbatim}
AUTH *auth_gssapi_create(CLIENT         *clnt,
                        OM_uint32       *major_status,
                        OM_uint32       *minor_status,
                        gss_cred_id_t   claimant_cred_handle,
                        gss_name_t      target_name,
                        gss_OID         mech_type,
                        int             req_flags,
                        int             time_req,
                        gss_OID         *actual_mech_type,
                        int             *ret_flags,
                        OM_uint32       *time_rec);
\end{verbatim}

auth_gssapi_create creates a GSS-API authentication structure and
provides most of the flexibility of gss_init_sec_context.  The
arguments have the same interpretation as those of
gss_init_sec_context with the same name, except:

\begin{description}
\item[clnt] The CLIENT structure returned by client_create or one of
its relatives.  It is not modified.
\end{description}

auth_gssapi_create calls gss_init_sec_context as needed, passing each
generated token to and processing each token returned from the RPC
server specified by the RPC handle clnt.  On return, if major_status
is GSS_S_COMPLETE, the context has been established, the returned AUTH
structure is valid, and all of the arguments filled in by
gss_init_sec_context have the correct values.  If major_status is not
GSS_S_COMPLETE then it and minor_status contain error codes that can
be passed to gss_display_status and the returned value is NULL.

\begin{verbatim}
AUTH *auth_gssapi_create_default(CLIENT *clnt, char *service_name);
\end{verbatim}

auth_gssapi_create_default is a shorthand for auth_gssapi_create that
attempts to create a context that provides procedure call and result
integrity, using the default credentials and GSS-API mechanism.
service_name is parsed as a GSS-API ``service'' name and used as the
target name.  The other arguments to auth_gssapi_create are as follows:

\begin{verbatim}
auth_gssapi_create(clnt,
                   &dummy,
                   &dummy,
                   GSS_C_NO_CREDENTIAL,
                   target_name,
                   GSS_C_NULL_OID,
                   GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG,
                   0,
                   NULL,
                   NULL,
                   NULL);
\end{verbatim}

Note that if the underlying default mechanism does not support data
integrity (e.g. the trust mechanism), this function will fail.

The GSS-API major and minor status codes can be interpreted with
auth_gssapi_display_status:

\begin{verbatim}
void auth_gssapi_display_status(char *msg, OM_uint32 major,
                                OM_uint32 minor);
\end{verbatim}

All of the error messages associated with the major and minor status
are displated on the standard error output, preceeded by the message
``GSS-API authentication error $<$msg$>$:''.

\subsection{Server Side}

\subsubsection{Service Name Registration}

An application server must register the service name(s) that it will
use for GSS-API connections before any AUTH_GSSAPI requests will
succeed.

\begin{verbatim}
typedef struct _auth_gssapi_name {
     char *name;
     gss_OID type;
} auth_gssapi_name;

bool_t _svcauth_gssapi_set_names(auth_gssapi_name *names, int num);
\end{verbatim}

names is an array of name specifications, each of which consists of a
null-terminated ASCII representation of a name and the GSS-API name
type that should be used to import it with gss_import_name.  The
name type ``gss_nt_service_name'' is recommended.

\subsubsection{Calling Client and Service Identification}

Each application server's dispatch function is passed two arguments,
the transport mechanism (transp) and the RPC service request (rqstp).
If the service request's credential flavor (rq_cred.oa_flavor) is
AUTH_GSSAPI (300001)\footnote{The value 4 was originally used, but
300001 has been officially assigned by the IETF.}, then the call has
been authenticated.  The rq_clntcred field of transp contains the
gss_name_t of the authenticated caller and can be passed to
gss_display_name to obtain a string represtation or gss_compare_name
to compare it with other names.  The rq_svccred field of transp
contains the GSS-API context established with the caller and can be
passed to gss_inquire_context.

\subsubsection{Error Logging}

An application server can register a function to be called when a
failure occurs during GSS-API context establishment with
_svcauth_set_log_badauth_func.

\begin{verbatim}
typedef void (*auth_gssapi_log_badauth_func)(OM_uint32 major,
                                             OM_uint32 minor,
                                             struct sockaddr_in *raddr,
                                             caddr_t data);

void _svcauth_set_log_badauth_func(auth_gssapi_log_badauth_func func,
                                   caddr_t data);
\end{verbatim}

The function func is called each time gss_accept_sec_context fails.
The major and minor arguments indicate the GSS-API major and minor
status codes returned.  The raddr field contains the INET socket that
the request came from, and the data field contains the data argument
of _svcauth_gssapi_set_log_badauth_func.

An application server can register a function to be called when an RPC
request with an invalid verifier arrives with
_svcauth_set_log_badverf_func.

\begin{verbatim}
typedef void (*auth_gssapi_log_badverf_func)(gss_name_t client,
                                             gss_name_t server,
                                             struct svc_req *rqst,
                                             struct rpc_msg *msg,
                                             caddr_t data);

void _svcauth_set_log_badverf_func(auth_gssapi_log_badverf_func func,
                                   caddr_t data);
\end{verbatim}

The function specified in func is called each time an invalid verifier
is received.  The client and server fields identify the (falsely
claimed) originating client and the server it originally authenticated
to.  The raddr and addrlen fields contain the INET socket that the
request (claims to have) come from, and data contains the data
argument of _svcauth_set_log_badverf_func.

\section{Modifications to Sun RPC}

The Sun RPC extensible authentication mechanism is designed to allow
different authentication systems to be integrated into Sun RPC easily.
Unfortunately, it has two drawbacks.  First, the existing system has a
number of non-general design properties that are intended specifically
for Sun's Secure RPC, and second, the existing system has no concept
of or ability to perform authentication-flavor-specific operations on
function arguments and results passed over the wire.  The first
problem merely makes the system confusing, since a number of features
touted as ``general'' do not make any sense for arbitrary
authentication systems.  The second problem is more substantial, and
can only be corrected by modifications to Sun RPC internals.

The following sections describe the necessary modifications to Sun
RPC.

\subsection{Client Side Authentication, AUTH Structure}

The AUTH structure (figure \ref{fig:auth}) encapsulates the data and
function pointers for an authentication flavor instance.  It has been
changed in two ways.

\begin{figure}[htbp]
\begin{verbatim}
typedef struct {
        struct  opaque_auth     ah_cred;
        struct  opaque_auth     ah_verf;
        union   des_block       ah_key;
        struct auth_ops {
                void    (*ah_nextverf)();
                int     (*ah_marshal)();        /* nextverf & serialize */
                int     (*ah_validate)();       /* validate varifier */
                int     (*ah_refresh)();        /* refresh credentials */
                int     (*ah_wrap)();           /* encode data for wire */
                int     (*ah_unwrap)();         /* decode data from wire */
                void    (*ah_destroy)();        /* destroy this structure */
        } *ah_ops;
        caddr_t ah_private;
} AUTH;
\end{verbatim}
\caption{The AUTH structure, with the new function pointers ah_wrap
and ah_unwrap.}
\label{fig:auth}
\end{figure}

First, the new functions ah_wrap and ah_unwrap prepare function
arguments and results for transmission over the wire.  The
authentication mechanism can use them to sign, encrypt, or perform any
other operation on the data.  Their prototype is:

\begin{verbatim}
bool_t ah_wrap(AUTH *auth, XDR *out_xdrs, xdrproc_t func, caddr_t ptr);
bool_t ah_unwrap(AUTH *auth, XDR *in_xdrs, xdrproc_t func, caddr_t ptr);
\end{verbatim}

ah_wrap encodes function arguments for transmission.  func and ptr are
the XDR procedure and pointer that serialize the arguments, and
out_xdrs is the xdr stream that the encoded arguments should be
written to.  ah_unwrap decodes function arguments received from the
network.  Its arguments are the converse of those to ah_wrap.

It is the responsibility of RPC transport mechanisms to call an
authorization flavor's ah_wrap and ah_unwrap functions when function
arguments or results would normally be written to or read from the
wire.  Authorization flavors that do not need to perform any encoding
or decoding can use the provided function authany_wrap for ah_wrap
and ah_unwrap; it consists of the single statement ``return
(*func)(out_xdrs, ptr)'' (or in_xdrs, as appropriate).

Second, the function ah_refresh has been changed to take the RPC error
message that resulted in its being called as an argument.  This is
necessary since the contents of the error message may dictate how
ah_refresh should go about correcting the authentication failure.

\subsection{Client Side Transport Mechanisms}

Each client side transport mechanism must be modified to call the
ah_wrap and ah_unwrap functions from the cl_auth field of the CLIENT
structure during the call and reply process.  The modification is
fairly simple.  For example, the UDP transport mechanism used to
encode procedure calls like this:

\begin{verbatim}
        if ((! XDR_PUTLONG(xdrs, (long *)&proc)) ||
            (! AUTH_MARSHALL(cl->cl_auth, xdrs)) ||
            (! (*xargs)(xdrs, argsp)))
                return (cu->cu_error.re_status = RPC_CANTENCODEARGS);
\end{verbatim}

The last function call in the conditional serializes the arguments
onto the xdr stream.  This must be replaced with a call to the
appropriate ah_wrap function:

\begin{verbatim}
        if ((! XDR_PUTLONG(xdrs, (long *)&proc)) ||
            (! AUTH_MARSHALL(cl->cl_auth, xdrs)) ||
            (! AUTH_WRAP(cl->cl_auth, xdrs, xargs, argsp)))
                return (cu->cu_error.re_status = RPC_CANTENCODEARGS);
\end{verbatim}

AUTH_WRAP is a macro that takes the four arguments for an ah_wrap
function and extracts and calls the function pointer from the cl_auth
structure with the specified arguments.

Similarly, the transport mechanism must unwrap procedure results.
Again, the UDP mechanism will be instructive.  It used to deserialize
function results like this:

\begin{verbatim}
        reply_msg.acpted_rply.ar_results.where = resultsp;
        reply_msg.acpted_rply.ar_results.proc = xresults;

        ok = xdr_replymsg(&reply_xdrs, &reply_msg);
\end{verbatim}

The problem here is that xdr_replymsg deserializes an entire reply
message, including the results.  Since xresults and resultsp are the
function and pointer to decode the results, they will be automatically
deserialized {\it without} ah_unwrap being invoked.  The simplest
solution (which is also the normal method used by the TCP mechanism)
is to arrange to deserialize the function results explicitly:

\begin{verbatim}
        reply_msg.acpted_rply.ar_results.where = NULL;
        reply_msg.acpted_rply.ar_results.proc = xdr_void;

        if ((! xdr_replymsg(&reply_xdrs, &reply_msg)) ||
            (! AUTH_UNWRAP(cl->cl_auth, reply_xdrs, xresults,
                           resultsp))) {
                return (cu->cu_error.re_status = RPC_CANTENCODEARGS);
        }
\end{verbatim}

Since xdr_void does not read any data from the XDR stream, the
function results are still available when AUTH_UNWRAP is called.  Note
that AUTH_UNWRAP should only be called on {\it successful} calls; if
the reply message status is not RPC_SUCCESS there are no arguments to
read.

Currently, the UDP and TCP transport mechanisms has been
converted.\footnote{The ``raw'' mechanism, for direct connections, has
not been.}

\subsection{Service Side Authentication, SVCAUTH and XPRT}

Standard Sun RPC service-side authentication consists of a single
function per authentication flavor; there is no concept of an AUTH
structure containing function pointers and private data as with the
client side.  Previously, nothing else was necessary, because each
flavor only did a single thing (authenticated individual calls in a
stateless manner).  More functions and state are now required,
however; they are stored in the SVCAUTH structure, see figure
\ref{fig:svcauth}.

\begin{figure}[htbp]
\begin{verbatim}
typedef struct {
     struct svc_auth_ops {
          int   (*svc_ah_wrap)();
          int   (*svc_ah_unwrap)();
     } *svc_ah_ops;
     caddr_t svc_ah_private;
} SVCAUTH;
\end{verbatim}
\caption{The new SVCAUTH structure.}
\label{fig:svcauth}
\end{figure}

There is one SVCAUTH structure per authentication flavor (there is a
default, svc_auth_any, for existing authentication flavors that do not
need the extra functionality).  The svc_ah_wrap and svc_ah_unwrap
perform the same logical function as their client-side counterparts.

Just as with the client side, it is the responsibility of the
transport mechanism to call the svc_ah_wrap and svc_ah_unwrap
functions associated with the authentication flavor associated with
each RPC call at the appropriate time.  Unfortunately, the transport
mechanism code does not have access to the RPC call structure
containing the authenticator flavor because the RPC call structure
itself is not passed as an argument to the necessary functions.  The
present solution is to add another argument to the transport mechanism
structure, xp_auth, that stores the SVCAUTH of the {\it current} call
on that mechanism; see figure \ref{fig:xprt}.  xp_auth is initialized
to svc_auth_any so that existing authentication mechanisms that do not
set the field will still operate correctly.  \footnote{This is not an
great solution, because it forces each transport mechanism to be
single threaded.  The correct solution is to store the SVCAUTH
associated with each RPC call in the RPC call structure; however,
doing so would require changing a lot of code to pass around the RPC
call structure that currently does not do so.  Since other parts of
Sun RPC use the XPRT structure in a non-reentrant way, the present
solution does not make the situation any
worse.}$^{\mbox{,}}$\footnote{A somewhat irrelevant side effect of
adding SVCAUTH to XPRT is that the standard include file
$<$rpc/rpc.h$>$ had to be changed to include $<$rpc/svc_auth$>$ before
$<$rpc/svc.h$>$, whereas they used to be in the opposite order.}

\begin{figure}[htbp]
\begin{verbatim}
typedef struct {
        int             xp_sock;
        u_short         xp_port;         /* associated port number */
        struct xp_ops {
            bool_t      (*xp_recv)();    /* receive incomming requests */
            enum xprt_stat (*xp_stat)(); /* get transport status */
            bool_t      (*xp_getargs)(); /* get arguments */
            bool_t      (*xp_reply)();   /* send reply */
            bool_t      (*xp_freeargs)();/* free mem allocated for args */
            void        (*xp_destroy)(); /* destroy this struct */
        } *xp_ops;
        int             xp_addrlen;      /* length of remote address */
        struct sockaddr_in xp_raddr;     /* remote address */
        struct opaque_auth xp_verf;      /* raw response verifier */
        SVCAUTH         *xp_auth;        /* auth flavor of current req */
        caddr_t         xp_p1;           /* private */
        caddr_t         xp_p2;           /* private */
} SVCXPRT;
\end{verbatim}
\caption{The modified XPRT structure, with the xp_auth field.}
\label{fig:xprt}
\end{figure}

Finally, with the modified XPRT structure carrying around the
authentication flavor structure, the functions that serialize and
deserialize function arguments and results must be modified to use the
svc_ah_wrap and svc_ah_unwrap functions.  Each service-side transport
mechanism has getargs and reply functions that must be modified to use
the SVCAUTH_UNWRAP and SVCAUTH_WRAP macros, respectively, in a manner
completely parallel to the client side.

\subsection{Authenticated Service Identification, svc_req}

Sun RPC provides the authenticated credentials of a client to the
application server via rq_clntcred (``cooked credentials'') field of
the service request (svc_req) structure.  In many authentication
systems, services are also named entities, and there is no reason that
an RPC should be restricted to accepting connections as a single
authenticated service name.  However, access control decisions may be
based on the service name a client authenticated to, so that
information must be available to the application server.

Figure \ref{fig:svc-req} shows the modified service request structure
that contains a single new field, rq_svccred.  Like rq_clntcred, the
authentication flavor is responsible for setting rq_svccred to the
``cooked'' service credentials associated with a given RPC call.
Authentication flavors that do not have the concept of service names
can of course leave this field blank.

\begin{figure}[htbp]
\begin{verbatim}
struct svc_req {
        u_long          rq_prog;        /* service program number */
        u_long          rq_vers;        /* service protocol version */
        u_long          rq_proc;        /* the desired procedure */
        struct opaque_auth rq_cred;     /* raw creds from the wire */
        caddr_t         rq_clntcred;    /* read only cooked client cred */
        caddr_t         rq_svccred;     /* read only cooked svc cred */
        SVCXPRT         *rq_xprt;       /* associated transport */
};
\end{verbatim}
\caption{The modified svc_req structure, with the rq_svccred field.}
\label{fig:svc-req}
\end{figure}



\subsection{Authentication Negotiation, no_dispatch}

In order to avoid having to transmit a full set of authentication
information with every call, the service-side authentication mechanism
must save state between calls.  Establishing that state may require
multiple messages between the client-side and service-side
authentication mechanisms.  The client-side authentication mechanism
can make arbitrary RPC calls to the server simply by requiring the
programmer to specify the CLIENT structure to the authentication
flavor initialization routine.  The service side, however, is more
complex.  In the normal course of events, an RPC call comes in, is
authenticated, and is then dispatched to the appropriate procedure.
For client- and service-side authentication flavors to communicate
independent of the server implemented above the RPC layer, the
service-side flavor must be able to send a reply to the client
directly and {\it prevent} the call from being dispatched.

This is implemented by a simple modification to the _authenticate
routine, which dispatches each RPC call to the appropriate
authentication flavor; see figure \ref{fig:authenticate}.  It takes an
additional argument, no_dispatch, that instructs the mechanism not to
dispatch the RPC call to the specified procedure.

\begin{figure}[htbp]
\begin{verbatim}
                why=_authenticate(&r, &msg, &no_dispatch);
                if (why != AUTH_OK) {
                     svcerr_auth(xprt, why);
                     goto call_done;
                } else if (no_dispatch) {
                     goto call_done;
                }
\end{verbatim}
\caption{A call to the modified _authenticate.}
\label{fig:authenticate}
\end{figure}

If _authenticate sets no_dispatch to true, the call is considered
finished and no procedure dispatch takes place.  Presumably, an
authentication flavor that sets no_dispatch to true also replies to
the RPC call with svc_sendreply.  Authentication flavors that do not
modify no_dispatch implicitly leave it set to false, so the normal
dispatch takes place.

\subsection{Affected Files}

Table \ref{tab:modfiles} lists the files that were
affected for each of the modifications described in previous sections.

\begin{table}[htbp]
\centering
\caption{Files modified for each change to Sun RPC.}
\label{tab:modfiles}
\begin{tabular}{ll}
AUTH structure                  & auth.h \\
                                & auth_none.c \\
                                & auth_exit.c \\
                                & auth_any.c \\
Client Transport Mechanisms     & clnt_udp.c \\
                                & clnt_tcp.c \\
SVCAUTH and XPRT structures     & rpc.h \\
                                & svc.h \\
                                & svc_auth.h \\
                                & svc.c \\
                                & svc_auth.c \\
                                & svc_auth_any.c \\
                                & svc_auth_unix.c \\
Server Transport Mechanisms     & svc_udp.c \\
                                & svc_tcp.c
\end{tabular}
\end{table}

\section{GSS-API Authentication Flavor}

The following sections describe the implementation of the GSS-API
authentication flavor for Sun RPC.

\subsection{Authentication Algorithms}
\label{sec:algorithms}

\subsubsection{Context Initiation}

The client creates a GSS-API context with the server each time it
calls auth_gssapi_create.  The context is created using the standard
gss_init_sec_context and gss_accept_sec_context function calls.  The
generated tokens are passed between the client and server as arguments
and results of normal RPC calls.

The client side, in auth_gssapi_create, performs the following steps
to initiate a context:

\begin{enumerate}
\item\label{item:process-token} The client calls gss_init_sec_context.
On the first such call, no input token is provided; on subsequent
calls, the token received from the server is provided.

\item If gss_init_sec_context produces an output token:

\begin{enumerate}
\item The client transmits the token to the server, identifying itself
with client_handle if it has already been received (see next step).
The return value from the server will contain a client_handle and one
or both of a token and a signed initial sequence number.

\item If this is the first response from the server, the client_handle
is stored for subsequent calls.  Otherwise, the client_handle should be
the same as returned on the previous call.

\item If the response contains a signed initian sequence number but
the context is not yet established, then the response also contains a
token that will established the context.  The signed initial sequence
number is stored.

\item If the response contains a token, step \ref{item:process-token}
repeated.
\end{enumerate}

\item The signed initial sequence number is verified using the
established context.
\end{enumerate}

The server side, in _svcauth_gssapi, performs the following steps to
initiate a context:

\begin{enumerate}
\item If a call arrives with no client_handle, a new client_handle is
allocated and stored in the database.  Otherwise, the client's
previous state is is looked up in the database.

\item The received token is passed to gss_accept_sec_context.  If an
output token is generated, it is returned to the client.  Note that
since the application server may have registered multiple service
names and there is no way to determine {\it a priori} which service a
token is for, _svcauth_gssapi calls gss_accept_sec_context once for
each registered credential until one of them succeeds.  The code
assumes that GSS_S_FAILURE is the only error that can result from a
credential mismatch, so any other error terminates the loop
immediately.

\item If the context is established, the server signs an initial
sequence number and returns it to the client.
\end{enumerate}

Note that these algorithms require context establishment to be
synchronous.  If gss_init_sec_context returns GSS_S_COMPLETE upon
processing a token, it will either produce a token or not.  If it
does, then gss_accept_sec_context will return GSS_S_COMPLETE when that
token is processed; if it does not, then gss_accept_sec_context
already returned GSS_S_COMPLETE (and presumably returned the token
that caused gss_init_sec_context to return GSS_S_COMPLETE when
processed).  The reverse is also true.

\subsubsection{RPC Calls}

After the GSS-API context is established, both the server and the
client possess a client handle and a corresponding sequence number.
Each call from the client contains the client handle as the
``credential'' so that the server can identify which context to apply
to the call.

Each client call and server response includes a ``verifier'' that
contains the sealed current sequence number.\footnote{In a future
version, the verifier will also contain a signature block for the call
header, including the procedure number called.} The sequence number
prevents replay attacks\footnote{Although some GSS-API mechanisms
provide replay detection themselves, not all of them do; explicitly
including the sequence number in the RPC therefore provides better
end-to-end security}, but by itself it does not prevent splicing
attacks.

Each procedure argument and result block consists of the current
sequence number and the actual serialized argument string, all sealed
with gss_seal.  Combining the sequence number with the argument/result
data prevents splicing attacks.

The sequence number is incremented by one for each RPC call and by one
for each response.  The client and server will both reject messages
that do not contain the expected sequence number.  Packets
retransmitted by the client should use the {\it same} sequence number
as the original packet, since even if the server receives multiple
copies only one will be honored.

\subsection{RPC Call Credential Structure}

Every message transmitted from the client to the server has a
credentials (cb_cred) field of the type auth_gssapi_creds:

\begin{verbatim}
typedef struct _auth_gssapi_creds {
        bool_t       auth_msg;
        gss_buffer_desc client_handle;
};
\end{verbatim}

The auth_msg field indicates whether the message is intended for the
authentication mechanism for the actual server.  Any message whose
auth_msg field is true is processed by the authentication mechanism;
any message whose auth_msg is false is passed to the application
server's dispatch function if authentication succeeds.  All messages
must have an auth_msg of true until the context is established, since
authentication cannot succeed until it is.

The client_handle field contains the client handle obtained from the
first call to the server.  On the first call, this field is empty.

\subsection{GSS-API Authentication Flavor Procedures}

The GSS-API authentication flavor uses standard RPC calls over the
client handle it is provided for the interactions described in
\ref{sec:algorithms}.  All of the following procedures require the
auth_msg field in the credentials to be true; otherwise, the
server-side authentication flavor will simply attempt to authenticate
the caller and pass the call to the application server.  The
server-side authentication flavor uses the no_dispatch variable to
indicate that it has handled the call.

\subsubsection{AUTH_GSSAPI_INIT, AUTH_GSSAPI_CONTINUE_INIT}

Context initiation is performed via AUTH_GSSAPI_INIT and
AUTH_GSSAPI_CONTINUE_INIT.  The former is used to transfer the first
token generated by gss_init_sec_context, when no client handle is
included in the credentials; the latter is used on subsequent calls,
when a client handle is included.

Both procedures take an argument of type auth_gssapi_init_arg and
return results of the type auth_gssapi_init_res.

\begin{verbatim}
typedef struct _auth_gssapi_init_arg {
        u_long       version;
        gss_buffer_desc token;
} auth_gssapi_init_arg;
\end{verbatim}

\begin{description}
\item[version]  Three versions are presently defined.

\begin{description}
\item[1] The original version, as described in this document

\item[2] In earlier versions of Secure there was a bug in the GSS-API
library that affected the contents of accept_sec_context output
tokens.  A client specifies version 2 to indicate that it expects the
correct (fixed) behavior.  If the server indicates AUTH_BADCRED or
AUTH_FAILED it does not understand this version, so the client should
fall back to version 1.

\item[3] Version three indicates that channel bindings are in use.
The client must specify channel bindings with the version, and the
server will as well.  If the server indicates AUTH_BADCRED or
AUTH_FAILED it does not understand this version, so the client should
fall back to version 2 (and cease specifying channel bindings).

\item[4] The previous versions all used the old GSS-API krb5 mechanism
oid; this version uses the new one specified in the RFC.
\end{description}

\item[token] The token field contains the token generated by
gss_init_sec_context.
\end{description}

\begin{verbatim}
typedef struct _auth_gssapi_init_res {
        u_long       version;
        gss_buffer_desc client_handle;
        gss_buffer_desc token;
        OM_uint32 gss_major, gss_minor;
        gss_buffer_desc signed_isn;
} auth_gssapi_init_res;
\end{verbatim}

\begin{description}
\item[version] There are two versions currently defined.
\begin{description}
\item[1] The original version, as described in this document.  This is
the response version for {\it both} versions 1 and 2.  The Secure 1.1
server will always return this version.

\item[3] Version three indicates that the server specified channel
bindings in response to a call arg version number of three.  The
server must not specify this version unless the client does.
\end{description}

\item[client_handle] The client_handle field contains the client
handle that the client must use in the credentials field in all
subsequent RPC calls.  In response to AUTH_GSSAPI_CONTINUE_INIT, it is
the same client handle that arrived in the credentials.

\item[gss_major, gss_minor] The GSS-API error codes that resulted from
processing the auth_gssapi_init_arg.  If gss_major is GSS_S_COMPLETE,
the argument token was processed successfully.  Otherwise, gss_major
and gss_minor contain the relevant major and minor status codes, and
the context currently being negotiated is no longer valid.

\item[token] In any response that the client is expecting another
token (i.e.: gss_init_sec_context last returned GSS_S_CONTINUE), the
token field contains the output token from gss_accept_sec_context.  If
the client is not expecting a token and this field is not empty, an
error has occurred.

\item[signed_isn]  If the client is not expecting another token (i.e.:
the previous call to gss_init_sec_context yielded a token and returned
GSS_S_COMPLETE) or the supplied token completes the context, the
signed_isn field contains the signed initial sequence number.  The
server expects the first RPC call to have a sequence number one
greater than the initial sequence number (so that the signed_isn block
cannot be replayed).  If the client is expecting another token and the
signed_isn field is not empty, an error has occurred.
\end{description}

\subsubsection{AUTH_GSSAPI_DESTROY}

Context tear-down is performed via AUTH_GSSAPI_DESTROY.  This
procedure takes no arguments and returns no results; it merely informs
the server that the client wishes to destroy the established context.

When a client wishes to tear down an established context between
itself and a server, auth_gssapi_destroy first calls the
AUTH_GSSAPI_DESTROY procedure.  The server authenticates the message
and immediately sends a ``success'' response with no results.  The
client and server then both independently call gss_delete_sec_context
and discard the context-destruction token that is generated.

No RPC error checking is performed by either the client or the server.
The client waits a brief time for a success response from the server,
but if none arrives it destroys the context anyway since presumably
the user is waiting for the application to exit.  The server similar
ignores any RPC errors since it knows that the client will ignore any
errors that are reported.

\subsection{RPC Call Authentication Implementation}

Once the context has been established, all subsequent RPC calls are
authenticated via the verifier described in section
\ref{sec:algorithms}.

auth_gssapi_marshall, invoked via AUTH_MARSHALL while the RPC call is
being created on the client side, serializes the client_handle
obtained during context initiation {\it in plaintext} as the
credentials and serializes the current sequence number, sealed with
gss_seal, as the verifier.

auth_gssapi_wrap, invoked next via AUTH_WRAP, serializes a sealed
token containing both the sequence number of the current call and the
serialized arguments.

_svcauth_gssapi, invoked on the server side by _authenticate, uses the
client_handle contained in the credentials to look up the correct
context and verifies the sequence number provided in the verifier; if
the sequence number is not correct, it declares a potential replay
attack.\footnote{Retransmitted packets will appear as replay attacks,
of course.} The response verifier is set to the serialized sealed
incremented sequence number.

svc_auth_gssapi_unwrap, invoked when either the application server or
_svcauth_gssapi (in response to an AUTH_GSSAPI authentication flavor
message) attempts to read its arguments, deserialzes and unseals the
block containing the current sequence number and serialized arguments.
If the sequence number is incorrect, it declares a splicing attack;
otherwise, it unserializes the arguments into the original structure.

svc_auth_gssapi_wrap, invoked when either the application server or
_svcauth_gssapi attempts to write its response, performs the same
operation as auth_gssapi_wrap.

auth_gssapi_validate, invoked by the client-side RPC mechanism when
an RPC_SUCCESS response is received, verifies that the returned sequence
number is one greater than the previous value sent by
auth_gssapi_marshall.

Finally, auth_gssapi_unwrap, invoked by the client-side RPC mechanism
after auth_gssapi_validate succeeds, performs the same operation as
svc_auth_gssapi_unwrap.

If an RPC request generates an error message (a status of other than
RPC_SUCCESS), auth_gssapi_refresh is called.  If the error status is
AUTH_REJECTEDVERF, then the server rejected the sequence number as
invalid or replayed.  The client guesses that, on some previous call,
the server received a message but the server's response did not make
it back to the client; this could happen if the packet got lost or if
the server was being debugged and the client timed out waiting for it.
As a result, the server is expected a higher sequence number than the
client sent.  auth_gssapi_refresh increments the sequence number and
returns true so that the call will be tried again.  The transport
mechanism will only call auth_gssapi_refresh twice for each RPC
request, so if some other error occurred an infinite loop will not
result; however, it is unlikely the the client and server will be able
to resynchronize after such an event.

\subsection{Client State Information}

The client-side GSS-API authentication flavor maintains an
auth_gssapi_data structure for each authentication instance:

\begin{verbatim}
struct auth_gssapi_data {
     bool_t established;
     CLIENT *clnt;
     gss_ctx_id_t context;
     gss_buffer_desc client_handle;
     u_long seq_num;
     int def_cred;

     /* pre-serialized ah_cred */
     u_char cred_buf[MAX_AUTH_BYTES];
     u_long cred_len;
};
\end{verbatim}

The established field indicates whether the authentication context
between the client and server has been established.  It is set to true
when gss_init_sec_context returns GSS_S_COM\-PLETE.  When this field is
false, the auth_gssapi functions marshall, validate, wrap, and unwrap
mimic the ``no authentication'' flavor since there is no context with
which to perform authentication functions.\footnote{This field is
necessary because, when auth_gssapi_create calls clnt_call to make an
RPC call, it has to have set the client's authentication flavor to
AUTH_GSSAPI; otherwise, the service-side RPC mechanism will not know
to dispatch the call to _svcauth_gssapi.  However, with the client's
authentication flavor set, all of the authentication flavor's
functions will be automatically invoked, even though they are not
ready to operate.}

The clnt field contains the RPC client structure that can be used to
communicate with the GSS-API authentication flavor on the server.

The context field contains the context structure created by
gss_init_sec_context.

The client_handle field contains the client handle used on all RPC
calls except the first one; the handle is obtained as the result of
the first call.

The sequence_number field contains the sequence number that will be
used when transmitting RPC calls to the server and verifying the
server's responses after the context is initialized.

The def_cred field is true if gss_init_sec_context created a default
credential, in which case the authentication mechanism is responsible
for releasing the default credential that gets automatically
allocated.

The cred_buf and cred_len fields contain the pre-serialized
credentials structure used in each call.  This provides a small
performance enhancement since the credentials structure does not
change very often; the same pre-serialized version can be used on
virtually every call.

\subsection{Server State Information}
\label{sec:server-state}

The server-side GSS-API authentication flavor maintains an
svcauth_gssapi_data structure for each established or partially
established context:

\begin{verbatim}
typedef struct _svc_auth_gssapi_data {
     bool_t established;
     gss_ctx_id_t context;
     gss_name_t client_name, server_name;
     gss_cred_id_t server_creds;

     u_long expiration;
     u_long seq_num;
     u_long key;

     SVCAUTH svcauth;
} svc_auth_gssapi_data;
\end{verbatim}

The established field indicates whether the context is fully
established.

The context field contains the context created by
gss_accept_sec_context.

The client_name field contains the client's authenticated name, as
returned by gss_accept_sec_context.  _svcauth_gssapi sets the ``cooked
credentials'' field of the RPC call structure to this value after the
call is authenticated; the application server can use it to perform
authorization.

The server_name field contains the service name that the client
established a context with.  This is useful if the application server
registered more than one service name with the library; it allows the
server to determine which service the client chose.

The server_creds field contains the service credentials that the
client established a context with.  It is used to avoid having to scan
through the server_creds_list multiple times in the case that context
establishment requires more than one round-trip to the server.

The expiration field contains the expiration time of the context, as a
Unix timestamp.  If a context has no expiration (time_rec is
GSS_C_INDEFINITE), the expiration time is set to 24 hours in the
future.  When the structure is created, before the context is
established, the expiration time is initialized to small duration
(currently 5 minutes) so that partially created and abandoned contexts
will be expired quickly.

The seq_num field is the current sequence number for the client.

The key field is the client's key into the hash table (see below).
The client_handle field sent to the client is the key treated as an
arbitrary four-byte string.

The svcauth field is a kludge that allows the svc_auth_gssapi
functions to access the per-client data structure while processing a
call.  One SVCAUTH structure is allocated for each client structure,
and the svc_ah_private field is set to the corresponding client.  The
client's svcauth field is then set to the new SVCAUTH structure, so
that client_data->svcauth->svc_ah_private == client_data.  As each
request is processed, the transport mechanism's xp_auth field is set
to the client's svcauth field; thus, the server-side functions that
dispatch to server-side authentication flavors can access an
appropriate SVCAUTH structure, and the server-side authentication
function that is called can determine the appropriate per-client
structure from the SVCAUTH structure.

The per-client structures are all stored both in a BSD 4.4 db library
hash table and b-tree.  The hash table maps client handles (key
fields) the client structures, and is used to look up client
structures based on the client_handle field of a call's credentials
structure.  The b-tree stores the client structures as keys, sorted by
their expiration time.  Each time _svcauth_gssapi is activated, it
traverses the tree and destroys all client structures that have
expired.

\end{document}