'\" te
.\" Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH rpc_gss_getcred 3NSL "22 Aug 2011" "SunOS 5.11" "Networking Services Library Functions"
.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
.mk
.na
\fB\fIreq\fR \fR
.ad
.RS 11n
.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\fIrcred\fR \fR
.ad
.RS 11n
.rt  
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
.mk
.na
\fB\fIucred\fR \fR
.ad
.RS 11n
.rt  
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
.mk
.na
\fB\fIcookie\fR \fR
.ad
.RS 11n
.rt  
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
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_set_callback\fR(3NSL), \fBrpc_gss_set_svc_name\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.