A server's principal name is always specified as a NULL-terminated ASCII string of the form service@host. One example is firstname.lastname@example.org.
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 represents, it uses rpc_gss_set_svc_name(). This function takes a principal name in this format as an argument.
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 in the rpcsec_gss(3NSL) man page.
A server needs to be told the names of the principals it represents when it starts up. A server can act as more than one principal. rpc_gss_set_svc_name() sets the name of the principals, as shown in the following code example.
char *principal, *mechanism; u_int req_time; principal = "email@example.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 might use it.
For more information, see the rpc_gss_set_svc_name(3NSL) man page.
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.
Use the free() library call to free principal names.