Servers need to be able to operate on a client's principal name. For example, you might need to compare a client's principal name to an access control list, or look up a UNIX credential for that client, if such a credential exists. Such principal names are kept in the form of a rpc_gss_principal_t structure pointer. See the rpcsec_gss(3NSL) man page for more on rpc_gss_principal_t. If a server is to compare a principal name it has received with the name of a known entity, the server needs to be able to generate a principal name in that form.
The rpc_gss_get_principal_name() call takes as input several parameters that uniquely identify an individual on a network, and generates a principal name as a rpc_gss_principal_t structure pointer, as shown in the following code example.
rpc_gss_principal_t *principal; rpc_gss_get_principal_name(principal, mechanism, name, node, domain); . . .
The arguments to rpc_gss_get_principal_name() are:
principal is a pointer to the rpc_gss_principal_t structure to be set.
mechanism is the security mechanism being used. The principal name being generated is mechanism dependent.
name is an individual or service name, such as joeh or nfs, or even the name of a user-defined application.
node might be, for example, a UNIX machine name.
domain might be, for example, a DNS, NIS, or NIS+ domain name, or a Kerberos realm.
Each security mechanism requires different identifying parameters. For example, Kerberos V5 requires a user name and, only optionally, qualified node and domain names, which in Kerberos terms are host and realm names.
For more information, see the rpc_gss_get_principal_name(3NSL) man page.