include/gssrpc/svc.h

0001 /* @(#)svc.h    2.2 88/07/29 4.0 RPCSRC; from 1.20 88/02/08 SMI */
0002 /*
0003  * Copyright (c) 2010, Oracle America, Inc.
0004  *
0005  * All rights reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions are met:
0009  *
0010  *     * Redistributions of source code must retain the above copyright
0011  *       notice, this list of conditions and the following disclaimer.
0012  *
0013  *     * Redistributions in binary form must reproduce the above copyright
0014  *       notice, this list of conditions and the following disclaimer in
0015  *       the documentation and/or other materials provided with the
0016  *       distribution.
0017  *
0018  *     * Neither the name of the "Oracle America, Inc." nor the names of
0019  *       its contributors may be used to endorse or promote products
0020  *       derived from this software without specific prior written permission.
0021  *
0022  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
0023  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
0024  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
0025  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
0026  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0027  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
0028  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
0029  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
0030  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
0031  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
0032  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0033  */
0034
0035 /*
0036  * svc.h, Server-side remote procedure call interface.
0037  */
0038
0039 #ifndef GSSRPC_SVC_H
0040 #define GSSRPC_SVC_H
0041
0042 #include <gssrpc/svc_auth.h>
0043
0044 GSSRPC__BEGIN_DECLS
0045 /*
0046  * This interface must manage two items concerning remote procedure calling:
0047  *
0048  * 1) An arbitrary number of transport connections upon which rpc requests
0049  * are received.  The two most notable transports are TCP and UDP;  they are
0050  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
0051  * they in turn call xprt_register and xprt_unregister.
0052  *
0053  * 2) An arbitrary number of locally registered services.  Services are
0054  * described by the following four data: program number, version number,
0055  * "service dispatch" function, a transport handle, and a boolean that
0056  * indicates whether or not the exported program should be registered with a
0057  * local binder service;  if true the program's number and version and the
0058  * port number from the transport handle are registered with the binder.
0059  * These data are registered with the rpc svc system via svc_register.
0060  *
0061  * A service's dispatch function is called whenever an rpc request comes in
0062  * on a transport.  The request's program and version numbers must match
0063  * those of the registered service.  The dispatch function is passed two
0064  * parameters, struct svc_req * and SVCXPRT *, defined below.
0065  */
0066
0067 enum xprt_stat {
0068     XPRT_DIED,
0069     XPRT_MOREREQS,
0070     XPRT_IDLE
0071 };
0072
0073 /*
0074  * Server side transport handle
0075  */
0076 typedef struct SVCXPRT {
0077 #ifdef _WIN32
0078         SOCKET          xp_sock;
0079 #else
0080     int     xp_sock;
0081 #endif
0082     u_short     xp_port;     /* associated port number */
0083     struct xp_ops {
0084         /* receive incoming requests */
0085         bool_t  (*xp_recv)(struct SVCXPRT *, struct rpc_msg *);
0086         /* get transport status */
0087         enum xprt_stat (*xp_stat)(struct SVCXPRT *);
0088         /* get arguments */
0089         bool_t  (*xp_getargs)(struct SVCXPRT *, xdrproc_t,
0090                       void *);
0091         /* send reply */
0092         bool_t  (*xp_reply)(struct SVCXPRT *,
0093                     struct rpc_msg *);
0094             /* free mem allocated for args */
0095         bool_t  (*xp_freeargs)(struct SVCXPRT *, xdrproc_t,
0096                        void *);
0097         /* destroy this struct */
0098         void    (*xp_destroy)(struct SVCXPRT *);
0099     } *xp_ops;
0100     int     xp_addrlen;  /* length of remote address */
0101     struct sockaddr_in xp_raddr;     /* remote address */
0102     struct opaque_auth xp_verf;  /* raw response verifier */
0103     SVCAUTH     *xp_auth;    /* auth flavor of current req */
0104     void        *xp_p1;      /* private */
0105     void        *xp_p2;      /* private */
0106     int     xp_laddrlen;     /* length of local address */
0107     struct sockaddr_in xp_laddr;     /* local address */
0108 } SVCXPRT;
0109
0110 /*
0111  *  Approved way of getting address of caller
0112  */
0113 #define svc_getcaller(x) (&(x)->xp_raddr)
0114
0115 /*
0116  * Operations defined on an SVCXPRT handle
0117  *
0118  * SVCXPRT      *xprt;
0119  * struct rpc_msg   *msg;
0120  * xdrproc_t         xargs;
0121  * caddr_t       argsp;
0122  */
0123 #define SVC_RECV(xprt, msg)             \
0124     (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
0125 #define svc_recv(xprt, msg)             \
0126     (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
0127
0128 #define SVC_STAT(xprt)                  \
0129     (*(xprt)->xp_ops->xp_stat)(xprt)
0130 #define svc_stat(xprt)                  \
0131     (*(xprt)->xp_ops->xp_stat)(xprt)
0132
0133 #define SVC_GETARGS(xprt, xargs, argsp)         \
0134     (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
0135 #define svc_getargs(xprt, xargs, argsp)         \
0136     (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
0137
0138 #define SVC_GETARGS_REQ(xprt, req, xargs, argsp)    \
0139     (*(xprt)->xp_ops->xp_getargs_req)((xprt), (req), (xargs), (argsp))
0140 #define svc_getargs_req(xprt, req, xargs, argsp)    \
0141     (*(xprt)->xp_ops->xp_getargs_req)((xprt), (req), (xargs), (argsp))
0142
0143 #define SVC_REPLY(xprt, msg)                \
0144     (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
0145 #define svc_reply(xprt, msg)                \
0146     (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
0147
0148 #define SVC_REPLY_REQ(xprt, req, msg)           \
0149     (*(xprt)->xp_ops->xp_reply_req) ((xprt), (req), (msg))
0150 #define svc_reply_req(xprt, msg)            \
0151     (*(xprt)->xp_ops->xp_reply_req) ((xprt), (req), (msg))
0152
0153 #define SVC_FREEARGS(xprt, xargs, argsp)        \
0154     (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
0155 #define svc_freeargs(xprt, xargs, argsp)        \
0156     (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
0157
0158 #define SVC_DESTROY(xprt)               \
0159     (*(xprt)->xp_ops->xp_destroy)(xprt)
0160 #define svc_destroy(xprt)               \
0161     (*(xprt)->xp_ops->xp_destroy)(xprt)
0162
0163
0164 /*
0165  * Service request
0166  */
0167 struct svc_req {
0168     rpcprog_t       rq_prog;    /* service program number */
0169     rpcvers_t       rq_vers;    /* service protocol version */
0170     rpcproc_t       rq_proc;    /* the desired procedure */
0171     struct opaque_auth rq_cred; /* raw creds from the wire */
0172     void *      rq_clntcred;    /* read only cooked client cred */
0173     void *      rq_svccred; /* read only svc cred/context */
0174     void *      rq_clntname;    /* read only client name */
0175     SVCXPRT     *rq_xprt;   /* associated transport */
0176     /* The request's auth flavor *should* be here, but the svc_req  */
0177     /* isn't passed around everywhere it is necessary.  The     */
0178     /* transport *is* passed around, so the auth flavor it stored   */
0179     /* there.  This means that the transport must be single     */
0180     /* threaded, but other parts of SunRPC already require that.    */
0181     /*SVCAUTH       *rq_auth;    associated auth flavor */
0182 };
0183
0184
0185 /*
0186  * Service registration
0187  *
0188  * svc_register(xprt, prog, vers, dispatch, protocol)
0189  *  SVCXPRT *xprt;
0190  *  rpcprog_t prog;
0191  *  rpcvers_t vers;
0192  *  void (*dispatch)();
0193  *  int protocol;  like IPPROTO_TCP or _UDP; zero means do not register
0194  *
0195  * registerrpc(prog, vers, proc, routine, inproc, outproc)
0196  *  returns 0 upon success, -1 if error.
0197  */
0198 extern bool_t   svc_register(SVCXPRT *, rpcprog_t, rpcvers_t,
0199                  void (*)(struct svc_req *, SVCXPRT *), int);
0200
0201 extern int registerrpc(rpcprog_t, rpcvers_t, rpcproc_t,
0202                char *(*)(void *),
0203                xdrproc_t, xdrproc_t);
0204
0205 /*
0206  * Service un-registration
0207  *
0208  * svc_unregister(prog, vers)
0209  *  rpcprog_t prog;
0210  *  rpcvers_t vers;
0211  */
0212 extern void svc_unregister(rpcprog_t, rpcvers_t);
0213
0214 /*
0215  * Transport registration.
0216  *
0217  * xprt_register(xprt)
0218  *  SVCXPRT *xprt;
0219  */
0220 extern void xprt_register(SVCXPRT *);
0221
0222 /*
0223  * Transport un-register
0224  *
0225  * xprt_unregister(xprt)
0226  *  SVCXPRT *xprt;
0227  */
0228 extern void xprt_unregister(SVCXPRT *);
0229
0230
0231 /*
0232  * When the service routine is called, it must first check to see if
0233  * it knows about the procedure; if not, it should call svcerr_noproc
0234  * and return.  If so, it should deserialize its arguments via
0235  * SVC_GETARGS or the new SVC_GETARGS_REQ (both defined above).  If
0236  * the deserialization does not work, svcerr_decode should be called
0237  * followed by a return.  Successful decoding of the arguments should
0238  * be followed the execution of the procedure's code and a call to
0239  * svc_sendreply or the new svc_sendreply_req.
0240  *
0241  * Also, if the service refuses to execute the procedure due to too-
0242  * weak authentication parameters, svcerr_weakauth should be called.
0243  * Note: do not confuse access-control failure with weak authentication!
0244  *
0245  * NB: In pure implementations of rpc, the caller always waits for a reply
0246  * msg.  This message is sent when svc_sendreply is called.
0247  * Therefore pure service implementations should always call
0248  * svc_sendreply even if the function logically returns void;  use
0249  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
0250  * for the abuse of pure rpc via batched calling or pipelining.  In the
0251  * case of a batched call, svc_sendreply should NOT be called since
0252  * this would send a return message, which is what batching tries to avoid.
0253  * It is the service/protocol writer's responsibility to know which calls are
0254  * batched and which are not.  Warning: responding to batch calls may
0255  * deadlock the caller and server processes!
0256  */
0257
0258 extern bool_t   svc_sendreply(SVCXPRT *, xdrproc_t, caddr_t);
0259 extern void svcerr_decode(SVCXPRT *);
0260 extern void svcerr_weakauth(SVCXPRT *);
0261 extern void svcerr_noproc(SVCXPRT *);
0262 extern void svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t);
0263 extern void svcerr_auth(SVCXPRT *, enum auth_stat);
0264 extern void svcerr_noprog(SVCXPRT *);
0265 extern void svcerr_systemerr(SVCXPRT *);
0266
0267 /*
0268  * Lowest level dispatching -OR- who owns this process anyway.
0269  * Somebody has to wait for incoming requests and then call the correct
0270  * service routine.  The routine svc_run does infinite waiting; i.e.,
0271  * svc_run never returns.
0272  * Since another (co-existant) package may wish to selectively wait for
0273  * incoming calls or other events outside of the rpc architecture, the
0274  * routine svc_getreq is provided.  It must be passed readfds, the
0275  * "in-place" results of a select system call (see select, section 2).
0276  */
0277
0278 /*
0279  * Global keeper of rpc service descriptors in use
0280  * dynamic; must be inspected before each call to select
0281  */
0282 extern int svc_maxfd;
0283 #ifdef FD_SETSIZE
0284 extern fd_set svc_fdset;
0285 /* RENAMED */
0286 #define gssrpc_svc_fds gsssrpc_svc_fdset.fds_bits[0]    /* compatibility */
0287 #else
0288 extern int svc_fds;
0289 #endif /* def FD_SETSIZE */
0290 extern int svc_maxfd;
0291
0292 extern void svc_getreq(int);
0293 #ifdef FD_SETSIZE
0294 extern void svc_getreqset(fd_set *);/* takes fdset instead of int */
0295 #else
0296 extern void svc_getreqset(int *);
0297 #endif
0298 extern void svc_run(void);   /* never returns */
0299
0300 /*
0301  * Socket to use on svcxxx_create call to get default socket
0302  */
0303 #define RPC_ANYSOCK -1
0304
0305 /*
0306  * These are the existing service side transport implementations
0307  */
0308
0309 /*
0310  * Memory based rpc for testing and timing.
0311  */
0312 extern SVCXPRT *svcraw_create(void);
0313
0314 /*
0315  * Udp based rpc.
0316  */
0317 extern SVCXPRT *svcudp_create(int);
0318 extern SVCXPRT *svcudp_bufcreate(int, u_int, u_int);
0319 extern int svcudp_enablecache(SVCXPRT *, uint32_t);
0320
0321 /*
0322  * Tcp based rpc.
0323  */
0324 extern SVCXPRT *svctcp_create(int, u_int, u_int);
0325
0326 /*
0327  * Like svtcp_create(), except the routine takes any *open* UNIX file
0328  * descriptor as its first input.
0329  */
0330 extern SVCXPRT *svcfd_create(int, u_int, u_int);
0331
0332 /* XXX add auth_gsapi_log_*? */
0333
0334 GSSRPC__END_DECLS
0335
0336 #endif /* !defined(GSSRPC_SVC_H) */