gss_import_name(3)gss_import_name(3)NAMEgss_import_name - Convert text name to internal form name.
SYNOPSIS
#include <gssapi/gssapi.h>
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 * const output_name );
PARAMETERS
Kerberos 5 error code. Buffer containing the text name to be con‐
verted. Object identifier (OID) specifying the type of printable name.
Applications may specify any OID recognized by the HP implementation of
the GSS-API.
Specify GSS_C_NO_OID to use the Kerberos 5 default that is name
type GSS_KRB5_NT_PRINCIPAL_NAME. Specify NULL if input_name_buf‐
fer contains an exported name.
The supported name types are: GSS_C_NT_ANONYMOUS -- This name
type is not supported by the HP Application Security SDK.
GSS_C_NT_EXPORT_NAME -- This name type indicates a mechanism-
specific name. GSS_C_NT_HOSTBASED_SERVICE -- Same as
GSS_KRB5_NT_HOSTBASED_SERVICE_NAME. GSS_C_NT_MACHINE_UID_NAME
-- Same as GSS_KRB5_NT_MACHINE_UID_NAME.
GSS_C_NT_STRING_UID_NAME -- Same as GSS_KRB5_NT_STRING_UID_NAME.
GSS_C_NT_USER_NAME -- Same as GSS_KRB5_NT_USER_NAME.
GSS_KRB5_NT_HOSTBASED_SERVICE_NAME -- This name type indicates
that input_name_buffer contains a string representing a host
service. Its form is service@host where host is the name of the
host.
Kerberos 5 transforms the string into the service/fqdn@TAR‐
GET_REALM principal, where fqdn is the host's fully qualified
domain name and TARGET_REALM is the realm the host is in. For
example, telnet@joe would be transformed into the tel‐
net/joe.company.com@COMPANY.COM principal.
HP Application Security SDK has extended this name type to per‐
mit the optional prefix service: for compatibility with older
Kerberos implementations (service: is stripped).
GSS_KRB5_NT_MACHINE_UID_NAME -- This name type indicates that
input_name_buffer contains a UID representing a user on the
local system. Its implementation and interpretation is UNIX-spe‐
cific.
Kerberos 5 transforms the UID into the user@LOCAL_REALM princi‐
pal, where user is the login account that corresponds to the UID
and LOCAL_REALM is the local system's default realm.
HP Application Security SDK implementation of gss_import_name()
transforms the UID to a string and calls gss_import_name() a
second time, specifying GSS_KRB5_NT_STRING_UID_NAME as the name
type OID. GSS_KRB5_NT_PRINCIPAL -- Same as GSS_KRB5_NT_PRINCI‐
PAL_NAME. GSS_KRB5_NT_PRINCIPAL_NAME -- This name type indi‐
cates that input_name_buffer contains a string representing a
Kerberos 5 principal. Same as rfc_krb5_c_OID.
The Kerberos 5 principal must contain a minimum of one name com‐
ponent, up to a maximum of 255 name components, each separated
by a forward slash (/). The Kerberos 5 principal has only one
realm component, separated by an ampersand (@). If the realm is
not specified, the default realm is assigned.
For example, host/carl.company.com@COMPANY.COM is a string that
represents a Kerberos 5 principal. rfc_krb5_c_OID -- Treated
the same as GSS_KRB5_NT_PRINCIPAL_NAME. Because there is no
officially designated variable name to hold the Kerberos Version
5 mechanism OID, HP has defined this variable to hold the OID.
Its use, however, as the use of a similar variable in other
implementations, results in code that is not source-level porta‐
ble. GSS_KRB5_NT_STRING_UID_NAME -- This name type indicates
that input_name_buffer contains a digit string representing the
numeric identifier of a user on the local system. Its implemen‐
tation and interpretation is UNIX-specific. The digit string
corresponds to a UID.
Kerberos 5 mechanism transforms the UID into the
user@LOCAL_REALM principal where user is the login account that
corresponds to the numeric identifier and LOCAL_REALM is the
local system's default realm. GSS_KRB5_NT_USER_NAME -- This
name type indicates that input_name_buffer contains a string
representing a user on the local system.
Kerberos 5 mechanism transforms the user's name into the
user@LOCAL_REALM principal where user was specified in
input_name_buffer and LOCAL_REALM is the local system's default
realm. Returned name in internal form.
Storage associated with this name must be freed by the applica‐
tion after use with a call to gss_release_name().
DESCRIPTION
The gss_import_name() function converts a text name into an internal
form name. The name type describes the parsing syntax, or rule, to use
with the text name.
The internal form of the name is returned in a structure that must be
released by calling gss_release_name() once the application is finished
using it.
Use this function to convert the external form of an application name
into the internal form required by GSS-API functions. External form
names are text strings. Internal form names are opaque, that is, unin‐
telligible. The application passes in an object identifier, called
name type, that specifies how to interpret its name. The default name
type OID is a synonym for GSS_KRB5_NT_PRINCIPAL_NAME.
The default principal name cannot be specified as the text name for
conversion. It can only be used for acquiring credentials with
gss_acquire_cred().
The HP Application Security SDK supports the following generic name
types: GSS_C_NT_EXPORT_NAME GSS_C_NT_HOSTBASED_SERVICE
GSS_C_NT_MACHINE_UID_NAME GSS_C_NT_STRING_UID_NAME GSS_C_NT_USER_NAME
Supported Kerberos 5 name types are: GSS_KRB5_NT_HOSTBASED_SERVICE_NAME
GSS_KRB5_NT_MACHINE_UID_NAME GSS_KRB5_NT_PRINCIPAL GSS_KRB5_NT_PRINCI‐
PAL_NAME GSS_KRB5_NT_STRING_UID_NAME GSS_KRB5_NT_USER_NAME
RETURN VALUES
GSS_S_BAD_MECH xx01xxxx
GSS_S_BAD_NAME xx02xxxx
GSS_S_BAD_NAMETYPE xx03xxxx
GSS_S_CALL_BAD_STRUCTURE 03xxxxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_FAILURE xx0Dxxxx
PORTABILITY CONSIDERATIONS
Using Kerberos 5 name types may limit the portability of the applica‐
tion. Generic name types should be used instead.
Name type GSS_C_NT_ANONYMOUS is not supported.
SEE ALSO
Functions: csf_gss_acq_user(3), gss_canonicalize_name(3), gss_com‐
pare_name(3), gss_display_name(3), gss_duplicate_name(3),
gss_export_name(3), gss_release_name(3)gss_import_name(3)