'\" te
.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH RPC_GSS_GETCRED 3NSL "Feb 5, 2002"
.SH NAME
rpc_gss_getcred \- get credentials of client
.SH SYNOPSIS
.LP
.nf
#include <rpc/rpcsec_gss.h>

\fBbool_t\fR \fBrpc_gss_getcred\fR(\fBstruct svc_req\fR \fI*req\fR, \fBrpc_gss_rawcred_ t\fR \fI**rcred\fR,
     \fBrpc_gss_ucred\fR \fI**ucred\fR, \fBvoid\fR \fI**cookie\fR);
.fi

.SH DESCRIPTION
.sp
.LP
\fBrpc_gss_getcred()\fR is used by a server to fetch the credentials of a
client.  These credentials may either be network credentials (in the form of a
\fBrpc_gss_rawcred_t\fR structure) or UNIX credentials.
.sp
.LP
For more information on \fBRPCSEC_GSS\fR data types, see the
\fBrpcsec_gss\fR(3NSL) man page.
.SH PARAMETERS
.sp
.LP
Essentially,  \fBrpc_gss_getcred()\fR passes a pointer to a request
(\fBsvc_req\fR) as well as pointers to two credential structures and a
user-defined cookie; if \fBrpc_gss_getcred()\fR is successful, at least one
credential structure is "filled out" with values, as is, optionally, the
cookie.
.sp
.ne 2
.na
\fB\fIreq\fR \fR
.ad
.RS 11n
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
.na
\fB\fIrcred\fR \fR
.ad
.RS 11n
A pointer to an \fBrpc_gss_rawcred_t\fR structure pointer. This structure
contains the version number of the \fBRPCSEC_GSS\fR protocol being used; the
security mechanism and QOPs for this session (as strings); principal names for
the client (as a \fBrpc_gss_principal_t\fR structure) and server (as a string);
and the security service (integrity, privacy, etc., as an enum).  If an
application is not interested in these values, it may pass \fINULL\fR for this
parameter.
.RE

.sp
.ne 2
.na
\fB\fIucred\fR \fR
.ad
.RS 11n
The caller's UNIX credentials, in the form of a pointer to a pointer to a
\fBrpc_gss_ucred_t\fR structure, which includes the client's uid and gids.  If
an application is not interested in these values, it may pass \fINULL\fR for
this parameter.
.RE

.sp
.ne 2
.na
\fB\fIcookie\fR \fR
.ad
.RS 11n
A four-byte quantity that an application may use in any manner it wants to; RPC
does not interpret it.  (For example, a cookie may be a pointer or index to a
structure that represents a context initiator.) See also
\fBrpc_gss_set_callback\fR(3NSL).
.RE

.SH RETURN VALUES
.sp
.LP
\fBrpc_gss_getcred()\fR returns  TRUE if it is successful; otherwise, use
\fBrpc_gss_get_error()\fR to get the error associated with the failure.
.SH ATTRIBUTES
.sp
.LP
See  \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBrpc\fR(3NSL), \fBrpc_gss_set_callback\fR(3NSL), \fBrpc_gss_set_svc_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5)
.sp
.LP
\fIONC+ Developer\&'s Guide\fR
.sp