rpc_gss_set_callback(3) [freebsd man page]
RPC_GSS_SET_CALLBACK(3) BSD Library Functions Manual RPC_GSS_SET_CALLBACK(3) NAME
rpc_gss_set_callback -- Register a security context creation callback LIBRARY
RPC GSS-API Authentication Library (librpcsec_gss, -lrpcsec_gss) SYNOPSIS
#include <rpc/rpcsec_gss.h> bool_t (*callback)(struct svc_req *req, gss_cred_id_t deleg, gss_ctx_id_t gss_context, rpc_gss_lock_t *lock, void **cookie); bool_t rpc_gss_set_callback(rpc_gss_callback_t *cb); DESCRIPTION
Register a function which will be called when new security contexts are created on a server. This function will be called on the first RPC request which uses that context and has the opportunity of rejecting the request (for instance after matching the request credentials to an access control list). To accept the new security context, the callback should return TRUE, otherwise FALSE. If the callback accepts a con- text, it becomes responsible for the lifetime of the delegated client credentials (if any). It is also possible to 'lock' the values of service and quality of protection used by the context. If a context is locked, any subsequent requests which use different values for service and quality of protection will be rejected. PARAMETERS
cb A structure containing the RPC program and version for this callback and a function which will be called when new contexts are created for the given RPC program and version req The RPC request using the new context deleg GSS-API delegated credentials (if any) gss_context The GSS-API context lock A structure used to enforce a particular QOP and service. Set lock->locked to TRUE to lock the service and QOP values cookie The callback function may set *cookie to any pointer sized value. This value can be accessed during the lifetime of the context via rpc_gss_getcred(). RETURN VALUES
Returns TRUE if the callback was registered successfully or FALSE otherwise SEE ALSO
gssapi(3), rpc(3), rpc_gss_getcred(3), rpcset_gss(3) HISTORY
The rpc_gss_set_callback function first appeared in FreeBSD 8.0. AUTHORS
This manual page was written by Doug Rabson <dfr@FreeBSD.org>. BUGS
There is no mechanism for informing a server when a security context has been deleted. This makes it difficult to allocate resources (e.g. to return via the callback's cookie argument). BSD
January 26, 2010 BSD
Check Out this Related Man Page
rpc_gss_set_callback(3NSL) Networking Services Library Functions rpc_gss_set_callback(3NSL) NAME
rpc_gss_set_callback - specify callback for context SYNOPSIS
#include <rpc/rpcsec_gss.h> bool_t rpc_gss_set_callback(struct rpc_gss_callback_t *cb); DESCRIPTION
A server may want to specify a callback routine so that it knows when a context gets first used. This user-defined callback may be speci- fied through the rpc_gss_set_callback() routine. The callback routine is invoked the first time a context is used for data exchanges, after the context is established for the specified program and version. The user-defined callback routine should take the following form: bool_t callback(struct svc_req *req, gss_cred_id_t deleg, gss_ctx_id_t gss_context, rpc_gss_lock_t *lock, void **cookie); PARAMETERS
rpc_gss_set_callback() takes one argument: a pointer to a rpc_gss_callback_t structure. This structure contains the RPC program and ver- sion number as well as a pointer to a user-defined callback() routine. (For a description of rpc_gss_callback_t and other RPCSEC_GSS data types, see the rpcsec_gss(3NSL) man page.) The user-defined callback() routine itself takes the following arguments: req Pointer to the received service request. svc_req is an RPC structure containing information on the context of an RPC invocation, such as program, version, and transport information. deleg Delegated credentials, if any. (See NOTES, below.) gss_context GSS context (allows server to do GSS operations on the context to test for acceptance criteria). See NOTES, below. lock This parameter is used to enforce a particular QOP and service for a session. This parameter points to a RPCSEC_GSS rpc_gss_lock_t structure. When the callback is invoked, the rpc_gss_lock_t.locked field is set to TRUE, thus locking the context. A locked context will reject all requests having different values for QOP or service than those specified by the raw_cred field of the rpc_gss_lock_t structure. cookie A four-byte quantity that an application may use in any manner it wants to -- RPC does not interpret it. (For example, the cookie could be a pointer or index to a structure that represents a context initiator.) The cookie is returned, along with the caller's credentials, with each invocation of rpc_gss_getcred(). RETURN VALUES
rpc_gss_set_callback() returns TRUE if the use of the context is accepted; false otherwise. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |MT-Level |MT-Safe | +-----------------------------+-----------------------------+ |Availability |SUNWrsg (32-bit) | +-----------------------------+-----------------------------+ | |SUNWrsgx (64-bit) | +-----------------------------+-----------------------------+ SEE ALSO
rpc(3NSL), rpc_gss_getcred(3NSL), rpcsec_gss(3NSL), attributes(5) ONC+ Developer's Guide Linn, J. RFC 2078, Generic Security Service Application Program Interface, Version 2. Network Working Group. January 1997. NOTES
If a server does not specify a callback, all incoming contexts will be accepted. Because the GSS-API is not currently exposed, the deleg and gss_context arguments are mentioned for informational purposes only, and the user-defined callback function may choose to do nothing with them. SunOS 5.10 5 Feb 2002 rpc_gss_set_callback(3NSL)