'\" te
.\" Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH rpc_gss_set_callback 3NSL "22 Aug 2011" "SunOS 5.11" "Networking Services Library Functions"
.SH NAME
rpc_gss_set_callback \- specify callback for context
.SH SYNOPSIS
.LP
.nf
#include <rpc/rpcsec_gss.h> 

\fBbool_t\fR \fBrpc_gss_set_callback\fR(\fBstruct rpc_gss_callback_t\fR \fI*cb\fR);
.fi

.SH DESCRIPTION
.sp
.LP
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 specified through the \fBrpc_gss_set_callback()\fR 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.
.sp
.LP
The user-defined callback routine should take the following form:
.sp
.in +2
.nf
bool_t callback(struct svc_req\fI *req\fR, gss_cred_id_t\fI deleg\fR,
     gss_ctx_id_t\fI gss_context\fR, rpc_gss_lock_t\fI *lock\fR, void\fI **cookie\fR);
.fi
.in -2

.SH PARAMETERS
.sp
.LP
\fBrpc_gss_set_callback()\fR takes one argument:  a pointer to a \fBrpc_gss_callback_t\fR structure.  This structure contains the RPC program and version number as well as a pointer to a user-defined \fBcallback()\fR routine.  (For a description of \fBrpc_gss_callback_t\fR and other \fBRPCSEC_GSS\fR data types, see the \fBrpcsec_gss\fR(3NSL) man page.)
.sp
.LP
The user-defined \fBcallback()\fR routine itself takes the following arguments:
.sp
.ne 2
.mk
.na
\fB\fIreq\fR \fR
.ad
.RS 16n
.rt  
Pointer to the received service request.   \fBsvc_req\fR is an RPC structure containing information on the context of an RPC invocation, such as program, version, and transport information.  
.RE

.sp
.ne 2
.mk
.na
\fB\fIdeleg\fR \fR
.ad
.RS 16n
.rt  
Delegated credentials, if any. (See \fBNOTES,\fR below.)
.RE

.sp
.ne 2
.mk
.na
\fB\fIgss_context\fR \fR
.ad
.RS 16n
.rt  
GSS context (allows server to do GSS operations on the context to test for acceptance criteria). See \fBNOTES,\fR below.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlock\fR \fR
.ad
.RS 16n
.rt  
This parameter is used to enforce a particular QOP and service for a session. This parameter points to a \fBRPCSEC_GSS\fR \fBrpc_gss_lock_t\fR structure.  When the callback is invoked, the \fBrpc_gss_lock_t.locked\fR 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 \fBraw_cred\fR field of the  \fBrpc_gss_lock_t\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcookie\fR \fR
.ad
.RS 16n
.rt  
A four-byte quantity that an application may use in any manner it wants to \(em 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 \fBrpc_gss_getcred()\fR. 
.RE

.SH RETURN VALUES
.sp
.LP
\fBrpc_gss_set_callback()\fR returns  TRUE if the use of the context is accepted; false otherwise.    
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/library/security/rpcsec
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBrpc\fR(3NSL), \fBrpc_gss_getcred\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5) 
.sp
.LP
\fIONC+ RPC Developer\&'s Guide\fR
.sp
.LP
Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. 
.SH NOTES
.sp
.LP
If a server does not specify a callback, all incoming contexts will be accepted.
.sp
.LP
Because the \fBGSS-API\fR is not currently exposed, the \fIdeleg\fR and \fIgss_context\fR arguments are mentioned for informational purposes only, and the user-defined callback function may choose to do nothing with them.