Two types of principal names are needed to establish and maintain a security context:
A server principal name. A server's principal name is always specified as a NULL-terminated ASCII string of the form service@host -- for example, nfs@eng.acme.com.
When a client creates a security context, it specifies the server principal name in this format (see "Creating a Context"). Similarly, when a server needs to set the name of a principal it will represent, it uses rpc_gss_set_svc_name(), which takes a principal name in this format as an argument.
A client principal name. The principal name of a client, as received by a server, takes the form of an rpc_gss_principal_t structure: a counted, opaque byte string determined by the mechanism being used. This structure is described on the rpcsec_gss(3N) man page.
A server needs to be told the names of the principals it will represent when it starts up. (A server may act as more than one principal.) rpc_gss_set_svc_name() sets the name of the principal(s):
char *principal, *mechanism; u_int req_time; principal = "nfs@eng.acme.com"; mechanism = "kerberos_v5"; req_time = 10000; /* time for which credential should be valid */ rpc_gss_set_svc_name(principal, mechanism, req_time, SERV_PROG, SERV_VERS);
(Kerberos ignores the req_time parameter. Other authentication systems may use it.)
For more information, see the rpc_gss_set_svc_name(3N) man page.
Servers need to be able to operate on a client's principal name -- for example, 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(3N) man page for more on rpc_gss_principal_t.) If a server wants to compare a principal name it has received with the name of a known entity, it 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:
rpc_gss_principal_t *principal; rpc_gss_get_principal_name(principal, mechanism, name, node, domain); . . .
The arguments to rpc_gss_get_principal_name() are as follows:
principal is a pointer to the rpc_gss_principal_t structure to be set.
mechanism is the security mechanism being used (remember, 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 (in Kerberos terms, host and realm names).
For more information, see the rpc_gss_get_principal_name(3N) man page.
Principal names are freed up using the free() library call.