usr/src/man/man3nsl/rpc_gss_get_principal_name.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_GET_PRINCIPAL_NAME 3NSL "Feb 25, 2017"
   7 .SH NAME
   8 rpc_gss_get_principal_name \- Get principal names at server
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <rpc/rpcsec_gss.h>
  13
  14 \fBbool_t\fR \fBrpc_gss_get_principal_name\fR(\fBrpc_gss_principal_t\fR \fI*principal\fR,
  15      \fBchar\fR \fI*mech\fR, \fBchar\fR \fI*name\fR, \fBchar\fR \fI*node\fR, \fBchar\fR \fI*domain\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 Servers need to be able to operate on a client's principal name. Such a name is
  21 stored by the server as a  \fBrpc_gss_principal_t\fR structure, an opaque byte
  22 string which can be used either directly in access control lists or as database
  23 indices which can be used to look up a UNIX credential. A server may, for
  24 example, need to compare a principal name it has received with the principal
  25 name of a known entity, and to do that, it must be able to generate
  26 \fBrpc_gss_principal_t\fR structures from known entities.
  27 .sp
  28 .LP
  29 \fBrpc_gss_get_principal_name()\fR takes as input a security mechanism, a
  30 pointer to a \fBrpc_gss_principal_t\fR structure, and several parameters which
  31 uniquely identify an entity on a network: a user or service name, a node name,
  32 and a domain name.  From these parameters it constructs a unique,
  33 mechanism-dependent principal name of the \fBrpc_gss_principal_t\fR structure
  34 type.
  35 .SH PARAMETERS
  36 .LP
  37 How many of the identifying parameters  (\fIname \fR,  \fInode\fR, and \fI
  38 \fRdomain\fI)\fR are necessary to specify depends on the mechanism being used.
  39 For example, Kerberos V5 requires only a user name but can accept a node and
  40 domain name. An application can choose to set unneeded parameters to
  41 \fINULL.\fR
  42 .sp
  43 .LP
  44 Information on RPCSEC_GSS data types for parameters may be found on the
  45 \fBrpcsec_gss\fR(3NSL) man page.
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIprincipal\fR \fR
  50 .ad
  51 .RS 14n
  52 An opaque, mechanism-dependent structure representing the client's principal
  53 name.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fImech\fR \fR
  60 .ad
  61 .RS 14n
  62 An ASCII string representing the security mechanism in use.  Valid strings may
  63 be found in the \fB/etc/gss/mech\fR file, or by using
  64 \fBrpc_gss_get_mechanisms()\fR.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIname\fR \fR
  71 .ad
  72 .RS 14n
  73 A  UNIX login name (for example, 'gwashington') or service name, such as 'nfs'.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fInode\fR \fR
  80 .ad
  81 .RS 14n
  82 A node in a domain; typically, this would be a machine name (for
  83 example, 'valleyforge').
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIdomain\fR \fR
  90 .ad
  91 .RS 14n
  92 A security domain; for example, a DNS or NIS domain name
  93 ('eng.company.com').
  94 .RE
  95
  96 .SH RETURN VALUES
  97 .LP
  98 \fBrpc_gss_get_principal_name()\fR returns  TRUE if it is successful;
  99 otherwise, use  \fBrpc_gss_get_error()\fR to get the error associated with the
 100 failure.
 101 .SH FILES
 102 .ne 2
 103 .na
 104 \fB\fB/etc/gss/mech\fR \fR
 105 .ad
 106 .RS 18n
 107 File containing valid security mechanisms
 108 .RE
 109
 110 .SH ATTRIBUTES
 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 .LP
 127 \fBfree\fR(3C), \fBrpc\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL),
 128 \fBrpc_gss_set_svc_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4),
 129 \fBattributes\fR(5)
 130 .sp
 131 .LP
 132 \fIONC+ Developer\&'s Guide\fR
 133 .sp
 134 .LP
 135 Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997.