rpc_gss_get_principal_name(3n) [hpux man page]

rpc_gss_get_principal_name(3N)											    rpc_gss_get_principal_name(3N)

NAME

       rpc_gss_get_principal_name() - get principal names at server

SYNOPSIS


DESCRIPTION

       Servers need to be able to operate on a client's principal name.  Such a name is stored by the server as a 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 structures from known entities.

       takes as input a security mechanism, a pointer to a 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 structure type.

   Notes
       Principal names may be freed up by a call to See the free(3C) manpage.  A principal name need only be freed in instances where the name was
       constructed by the application.	Values returned by other routines need not be freed because they point to structures that already exist in
       a context.

PARAMETERS

       How many of the identifying paramaters (name, node, and domain) to specify depends on the mechanism being used.	Kerberos V5, for  example,
       requires  only  the  user  name	parameter but can accept the node and domain too.  An application can choose to set unneeded parameters to
       NULL.

       For additional information on data types for parameters, see the rpcsec_gss(3N) manpage.

       principal An opaque, mechanism-dependent structure representing the client's principal name.

       mech	 An ASCII string representing the security mechanism in use.  Valid strings may be found in the file, or by using

       name	 A UNIX login name (for example, 'gwashington') or service name, such as 'nfs'.

       node	 A node in a domain; typically, this would be a machine name (for example, 'valleyforge').

       domain	 A security domain, for example, a DNS or NIS domain name (for example, 'eng.company.com').

MULTITHREAD USAGE

       Thread Safe:	     Yes
       Cancel Safe:	     Yes
       Fork Safe:	     No
       Async-cancel Safe:    No
       Async-signal Safe:    No

       These functions can be called safely in a multithreaded environment.  They may be cancellation points in that they call functions that  are
       cancel points.

       In a multithreaded environment, these functions are not safe to be called by a child process after and before These functions should not be
       called by a multithreaded application that supports asynchronous cancellation or asynchronous signals.

RETURN VALUES

       returns if it is successful; otherwise, use to get the error associated with the failure.

FILES

       File containing valid security mechanisms.

SEE ALSO

       free(3C), rpc(3N), rpc_gss_set_svc_name(3N), rpc_gss_get_mechanisms(3N), rpcsec_gss(3N), mech(4).

														    rpc_gss_get_principal_name(3N)

rpc_gss_get_principal_name(3NSL)		       Networking Services Library Functions			  rpc_gss_get_principal_name(3NSL)

NAME

       rpc_gss_get_principal_name - Get principal names at server

SYNOPSIS

       #include <rpc/rpcsec_gss.h>

       bool_t rpc_gss_get_principal_name(rpc_gss_principal_ *principal,
	    char *mech, char *name, char *node, char *domain);

DESCRIPTION

       Servers	need  to be able to operate on a client's principal name. Such a name is stored by the server as a  rpc_gss_principal_t 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 rpc_gss_principal_t structures from known entities.

       rpc_gss_get_principal_name() takes as input a security mechanism, a pointer to a  rpc_gss_principal_t  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 con-
       structs a unique, mechanism-dependent principal name of the rpc_gss_principal_t structure type.

PARAMETERS

       How many of the identifying parameters  (name ,	node, and  domain) are necessary to specify depends on the mechanism being used. For exam-
       ple,  Kerberos  V5 requires only a user name but can accept a node and domain name. An application can choose to set unneeded parameters to
       NULL.

       Information on RPCSEC_GSS data types for parameters may be found on the rpcsec_gss(3NSL) man page.

       principal     An opaque, mechanism-dependent structure representing the client's principal name.

       mech	     An ASCII string representing the security mechanism in use.  Valid strings may be found in  the  /etc/gss/mech  file,  or	by
		     using rpc_gss_get_mechanisms().

       name	     A	UNIX login name (for example, 'gwashington') or service name, such as 'nfs'.

       node	     A node in a domain; typically, this would be a machine name (for example, 'valleyforge').

       domain	     A security domain; for example, a DNS, NIS, or NIS+ domain name ('eng.company.com').

RETURN VALUES

       rpc_gss_get_principal_name()  returns   TRUE  if it is successful; otherwise, use  rpc_gss_get_error() to get the error associated with the
       failure.

FILES

       /etc/gss/mech	 File containing valid security mechanisms

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWrsg (32-bit)		   |
       +-----------------------------+-----------------------------+
       |			     |SUNWrsgx (64-bit) 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       free(3C), rpc(3NSL), rpc_gss_get_mechanisms(3NSL), rpc_gss_set_svc_name(3NSL), rpcsec_gss(3NSL), mech(4), attributes(5)

       ONC+ Developer's Guide

       Linn, J. RFC 2078, Generic Security Service Application Program Interface, Version 2. Network Working Group. January 1997.

NOTES

       Principal names may be freed up by a call to free(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.)

SunOS 5.11							    5 Feb 2002					  rpc_gss_get_principal_name(3NSL)