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

\fBbool_t\fR \fBrpc_gss_get_principal_name\fR(\fBrpc_gss_principal_\fR \fI*principal\fR,
     \fBchar\fR \fI*mech\fR, \fBchar\fR \fI*name\fR, \fBchar\fR \fI*node\fR, \fBchar\fR \fI*domain\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Servers need to be able to operate on a client's principal name. Such a name is stored by the server as a  \fBrpc_gss_principal_t\fR structure, an opaque byte string which can be used either directly in access control lists or as database indices which can be used to look up a UNIX credential. A server may, for example, need to compare a principal name it has received with the principal name of a known entity, and to do that, it must be able to generate \fBrpc_gss_principal_t\fR structures from known entities.
.sp
.LP
\fBrpc_gss_get_principal_name()\fR takes as input a security mechanism, a pointer to a \fBrpc_gss_principal_t\fR structure, and several parameters which uniquely identify an entity on a network: a user or service name, a node name, and a domain name.  From these parameters it constructs a unique, mechanism-dependent principal name of the \fBrpc_gss_principal_t\fR structure type.
.SH PARAMETERS
.sp
.LP
How many of the identifying parameters  (\fIname \fR,  \fInode\fR, and \fI \fRdomain\fI)\fR are necessary to specify depends on the mechanism being used. For example, Kerberos V5 requires only a user name but can accept a node and domain name. An application can choose to set unneeded parameters to  \fINULL.\fR 
.sp
.LP
Information on RPCSEC_GSS data types for parameters may be found on the \fBrpcsec_gss\fR(3NSL) man page.
.sp
.ne 2
.mk
.na
\fB\fIprincipal\fR \fR
.ad
.RS 14n
.rt  
An opaque, mechanism-dependent structure representing the client's principal name.
.RE

.sp
.ne 2
.mk
.na
\fB\fImech\fR \fR
.ad
.RS 14n
.rt  
An ASCII string representing the security mechanism in use.  Valid strings may be found in the \fB/etc/gss/mech\fR file, or by using \fBrpc_gss_get_mechanisms()\fR. 
.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR \fR
.ad
.RS 14n
.rt  
A  UNIX login name (for example, 'gwashington') or service name, such as 'nfs'.
.RE

.sp
.ne 2
.mk
.na
\fB\fInode\fR \fR
.ad
.RS 14n
.rt  
A node in a domain; typically, this would be a machine name (for example, 'valleyforge').
.RE

.sp
.ne 2
.mk
.na
\fB\fIdomain\fR \fR
.ad
.RS 14n
.rt  
A security domain; for example, a DNS or NIS domain name ('eng.company.com').
.RE

.SH RETURN VALUES
.sp
.LP
\fBrpc_gss_get_principal_name()\fR returns  TRUE if it is successful; otherwise, use  \fBrpc_gss_get_error()\fR to get the error associated with the failure.
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/gss/mech\fR \fR
.ad
.RS 18n
.rt  
File containing valid security mechanisms
.RE

.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
\fBfree\fR(3C), \fBrpc\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpc_gss_set_svc_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \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
Principal names may be freed up by a call to \fBfree\fR(3C). A principal name need only be freed in those instances where it was constructed by the application. (Values returned by other routines point to structures already existing in a  context, and need not be freed.)