usr/src/man/man3nsl/rpc_gss_set_callback.3nsl

   1 '\" te
   2 .\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH RPC_GSS_SET_CALLBACK 3NSL "Feb 5, 2002"
   7 .SH NAME
   8 rpc_gss_set_callback \- specify callback for context
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <rpc/rpcsec_gss.h>
  13
  14 \fBbool_t\fR \fBrpc_gss_set_callback\fR(\fBstruct rpc_gss_callback_t\fR \fI*cb\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 A server may want to specify a callback routine so that it knows when a context
  21 gets first used. This user-defined callback may be specified through the
  22 \fBrpc_gss_set_callback()\fR routine.  The callback routine is invoked the
  23 first time a context is used for data exchanges, after the context is
  24 established for the specified program and version.
  25 .sp
  26 .LP
  27 The user-defined callback routine should take the following form:
  28 .sp
  29 .in +2
  30 .nf
  31 bool_t callback(struct svc_req\fI *req\fR, gss_cred_id_t\fI deleg\fR,
  32      gss_ctx_id_t\fI gss_context\fR, rpc_gss_lock_t\fI *lock\fR, void\fI **cookie\fR);
  33 .fi
  34 .in -2
  35
  36 .SH PARAMETERS
  37 .sp
  38 .LP
  39 \fBrpc_gss_set_callback()\fR takes one argument:  a pointer to a
  40 \fBrpc_gss_callback_t\fR structure.  This structure contains the RPC program
  41 and version number as well as a pointer to a user-defined \fBcallback()\fR
  42 routine.  (For a description of \fBrpc_gss_callback_t\fR and other
  43 \fBRPCSEC_GSS\fR data types, see the \fBrpcsec_gss\fR(3NSL) man page.)
  44 .sp
  45 .LP
  46 The user-defined \fBcallback()\fR routine itself takes the following arguments:
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIreq\fR \fR
  51 .ad
  52 .RS 16n
  53 Pointer to the received service request.   \fBsvc_req\fR is an RPC structure
  54 containing information on the context of an RPC invocation, such as program,
  55 version, and transport information.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIdeleg\fR \fR
  62 .ad
  63 .RS 16n
  64 Delegated credentials, if any. (See \fBNOTES,\fR below.)
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIgss_context\fR \fR
  71 .ad
  72 .RS 16n
  73 GSS context (allows server to do GSS operations on the context to test for
  74 acceptance criteria). See \fBNOTES,\fR below.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIlock\fR \fR
  81 .ad
  82 .RS 16n
  83 This parameter is used to enforce a particular QOP and service for a session.
  84 This parameter points to a \fBRPCSEC_GSS\fR \fBrpc_gss_lock_t\fR structure.
  85 When the callback is invoked, the \fBrpc_gss_lock_t.locked\fR field is set to
  86 TRUE, thus locking the context.  A locked context will reject all requests
  87 having different values for QOP or service than those specified by the
  88 \fBraw_cred\fR field of the  \fBrpc_gss_lock_t\fR structure.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIcookie\fR \fR
  95 .ad
  96 .RS 16n
  97 A four-byte quantity that an application may use in any manner it wants to \(em
  98 RPC does not interpret it.  (For example, the cookie could be a pointer or
  99 index to a structure that represents a context initiator.) The cookie is
 100 returned, along with the caller's credentials, with each invocation of
 101 \fBrpc_gss_getcred()\fR.
 102 .RE
 103
 104 .SH RETURN VALUES
 105 .sp
 106 .LP
 107 \fBrpc_gss_set_callback()\fR returns  TRUE if the use of the context is
 108 accepted; false otherwise.
 109 .SH ATTRIBUTES
 110 .sp
 111 .LP
 112 See \fBattributes\fR(5) for descriptions of the following attributes:
 113 .sp
 114
 115 .sp
 116 .TS
 117 box;
 118 c | c
 119 l | l .
 120 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 121 _
 122 MT-Level        MT-Safe
 123 .TE
 124
 125 .SH SEE ALSO
 126 .sp
 127 .LP
 128 \fBrpc\fR(3NSL), \fBrpc_gss_getcred\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5)
 129 .sp
 130 .LP
 131 \fIONC+ Developer\&'s Guide\fR
 132 .sp
 133 .LP
 134 Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997.
 135 .SH NOTES
 136 .sp
 137 .LP
 138 If a server does not specify a callback, all incoming contexts will be accepted.
 139 .sp