Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > R


HP-UX 11i Version 3: February 2007

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index


rpc_gss_get_principal_name() — get principal names at server


#include <rpc/rpcsec_gss.h>

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


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 constructs a unique, mechanism-dependent principal name of the rpc_gss_principal_t structure type.


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


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 RPCSEC_GSS data types for parameters, see the rpcsec_gss(3N) manpage.


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


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().


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


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


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


Thread Safe:


Cancel Safe:


Fork Safe:


Async-cancel Safe:


Async-signal Safe:


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 fork() and before exec(). These functions should not be called by a multithreaded application that supports asynchronous cancellation or asynchronous signals.


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.



File containing valid security mechanisms.


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

ONC+ Developer's Guide

Network Working Group RFC 2078

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.