Names

A name refers to a principal — that is, a person, a machine, or an application, such as joe@company or nfs@machinename. In the GSS-API, names are stored as a gss_name_t object, which is opaque to the application. Names are converted from gss_buffer_t objects to the gss_name_t form by the gss_import_name() function. Every imported name has an associated name type, which indicates what kind of format the name is in. (See under OIDs for more about name types, and see Name Types for a list of valid name types).

gss_import_name() looks like this:

OM_uint32 gss_import_name (
       OM_uint32          *minor_status,
       const gss_buffer_t input_name_buffer,
       const gss_OID      input_name_type,
       gss_name_t         *output_name)

minor_status

Status code returned by the underlying mechanism. (See Status Codes.)

input_name_buffer

The gss_buffer_desc structure containing the name to be imported. The application must allocate this explicitly (see Strings and Similar Data as well as Example 1–2.) This argument must be deallocated with gss_release_buffer() when the application is finished with it.

input_name_type

A gss_OID that specifies the format that the input_name_buffer is in. (See Name Types; also, Name Types contains a table of valid name types.)

output_name

The gss_name_t structure to receive the name.

Slightly modifying the generic example shown in Example 1–1, here is how you can use gss_import_name(). First, the regular string is inserted into a gss_buffer_desc structure, and then gss_import_name() places it into a gss_name_t structure.

Example 1–2 Using gss_import_name()

char *name_string;
gss_buffer_desc input_name_buffer;
gss_name_t      output_name_buffer;

input_name_buffer.value = name_string;
input_name_buffer.length = strlen(input_name_buffer.value) + 1;

gss_import_name(&minor_status, input_name_buffer, 
                    GSS_C_NT_HOSTBASED_SERVICE, &output_name);

gss_release_buffer(input_name_buffer);

An imported name can be put back into a gss_buffer_t object for display in human-readable form with gss_display_name(); however, gss_display_name() does not guarantee that the resulting string will be the same as the original, because of the way the underlying mechanisms store names. The GSS-API includes several other functions for manipulating names; see GSS-API Functions.

A gss_name_t structure can contain several versions of a single name — one version produced for each mechanism supported by the GSS-API. That is, a gss_name_t structure for “joe@company” might contain one version of that name as rendered by Kerberos v5, another version as given by a different mechanism, and so on. The GSS-API provides a function, gss_canonicalize_name(), that takes as its input an internal name (that is, a gss_name_t structure) and a mechanism and yields a second internal name (also a gss_name_t) that contains only a single version of the name, specific to that mechanism.

Such a mechanism-specific name is called a Mechanism Name (MN). “Mechanism Name” is a slightly confusing label, since it refers not to the name of a mechanism, but to the name of a principal as produced by a given mechanism. This process is illustrated by Figure 1–3.

Figure 1–3 Internal Names and Mechanism Names