doc/texi/name.c.texi

@subheading gss_import_name
@anchor{gss_import_name}
@deftypefun {OM_uint32} {gss_import_name} (OM_uint32 * @var{minor_status}, const gss_buffer_t @var{input_name_buffer}, const gss_OID @var{input_name_type}, gss_name_t * @var{output_name})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{input_name_buffer}: (buffer, octet-string, read) Buffer containing
contiguous string name to convert.

@var{input_name_type}: (Object ID, read, optional) Object ID specifying
type of printable name.  Applications may specify either
GSS_C_NO_OID to use a mechanism-specific default printable
syntax, or an OID recognized by the GSS-API implementation to
name a specific namespace.

@var{output_name}: (gss_name_t, modify) Returned name in internal form.
Storage associated with this name must be freed by the
application after use with a call to gss_release_name().


Convert a contiguous string name to internal form.  In general, the
internal name returned (via the @@output_name parameter) will not
be an MN; the exception to this is if the @@input_name_type
indicates that the contiguous string provided via the
@@input_name_buffer parameter is of type GSS_C_NT_EXPORT_NAME, in
which case the returned internal name will be an MN for the
mechanism that exported the name.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAMETYPE}: The input_name_type was unrecognized.


@code{GSS_S_BAD_NAME}: The input_name parameter could not be interpreted
as a name of the specified type.


@code{GSS_S_BAD_MECH}: The input name-type was GSS_C_NT_EXPORT_NAME, but
the mechanism contained within the input-name is not supported.
@end deftypefun

@subheading gss_display_name
@anchor{gss_display_name}
@deftypefun {OM_uint32} {gss_display_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{input_name}, gss_buffer_t @var{output_name_buffer}, gss_OID * @var{output_name_type})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{input_name}: (gss_name_t, read) Name to be displayed.

@var{output_name_buffer}: (buffer, character-string, modify) Buffer to
receive textual name string.  The application must free storage
associated with this name after use with a call to
gss_release_buffer().

@var{output_name_type}: (Object ID, modify, optional) The type of the
returned name.  The returned gss_OID will be a pointer into
static storage, and should be treated as read-only by the caller
(in particular, the application should not attempt to free
it). Specify NULL if not required.


Allows an application to obtain a textual representation of an
opaque internal-form name for display purposes.  The syntax of a
printable name is defined by the GSS-API implementation.


If input_name denotes an anonymous principal, the implementation
should return the gss_OID value GSS_C_NT_ANONYMOUS as the
output_name_type, and a textual name that is syntactically distinct
from all valid supported printable names in output_name_buffer.


If input_name was created by a call to gss_import_name, specifying
GSS_C_NO_OID as the name-type, implementations that employ lazy
conversion between name types may return GSS_C_NO_OID via the
output_name_type parameter.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAME}: @@input_name was ill-formed.
@end deftypefun

@subheading gss_compare_name
@anchor{gss_compare_name}
@deftypefun {OM_uint32} {gss_compare_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{name1}, const gss_name_t @var{name2}, int * @var{name_equal})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{name1}: (gss_name_t, read) Internal-form name.

@var{name2}: (gss_name_t, read) Internal-form name.

@var{name_equal}: (boolean, modify) Non-zero - names refer to same
entity. Zero - names refer to different entities (strictly, the
names are not known to refer to the same identity).


Allows an application to compare two internal-form names to
determine whether they refer to the same entity.


If either name presented to gss_compare_name denotes an anonymous
principal, the routines should indicate that the two names do not
refer to the same identity.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAMETYPE}: The two names were of incomparable types.


@code{GSS_S_BAD_NAME}: One or both of name1 or name2 was ill-formed.
@end deftypefun

@subheading gss_release_name
@anchor{gss_release_name}
@deftypefun {OM_uint32} {gss_release_name} (OM_uint32 * @var{minor_status}, gss_name_t * @var{name})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{name}: (gss_name_t, modify) The name to be deleted.


Free GSSAPI-allocated storage associated with an internal-form
name.  The name is set to GSS_C_NO_NAME on successful completion of
this call.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAME}: The name parameter did not contain a valid name.
@end deftypefun

@subheading gss_inquire_names_for_mech
@anchor{gss_inquire_names_for_mech}
@deftypefun {OM_uint32} {gss_inquire_names_for_mech} (OM_uint32 * @var{minor_status}, const gss_OID @var{mechanism}, gss_OID_set * @var{name_types})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{mechanism}: (gss_OID, read) The mechanism to be interrogated.

@var{name_types}: (gss_OID_set, modify) Set of name-types supported by
the specified mechanism.  The returned OID set must be freed by
the application after use with a call to gss_release_oid_set().


Returns the set of nametypes supported by the specified mechanism.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.
@end deftypefun

@subheading gss_inquire_mechs_for_name
@anchor{gss_inquire_mechs_for_name}
@deftypefun {OM_uint32} {gss_inquire_mechs_for_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{input_name}, gss_OID_set * @var{mech_types})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{input_name}: (gss_name_t, read) The name to which the inquiry
relates.

@var{mech_types}: (gss_OID_set, modify) Set of mechanisms that may
support the specified name.  The returned OID set must be freed
by the caller after use with a call to gss_release_oid_set().


Returns the set of mechanisms supported by the GSS-API
implementation that may be able to process the specified name.


Each mechanism returned will recognize at least one element within
the name.  It is permissible for this routine to be implemented
within a mechanism-independent GSS-API layer, using the type
information contained within the presented name, and based on
registration information provided by individual mechanism
implementations.  This means that the returned mech_types set may
indicate that a particular mechanism will understand the name when
in fact it would refuse to accept the name as input to
gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or
gss_add_cred (due to some property of the specific name, as opposed
to the name type).  Thus this routine should be used only as a
prefilter for a call to a subsequent mechanism-specific routine.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAME}: The input_name parameter was ill-formed.


@code{GSS_S_BAD_NAMETYPE}: The input_name parameter contained an invalid
or unsupported type of name.
@end deftypefun

@subheading gss_export_name
@anchor{gss_export_name}
@deftypefun {OM_uint32} {gss_export_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{input_name}, gss_buffer_t @var{exported_name})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{input_name}: (gss_name_t, read) The MN to be exported.

@var{exported_name}: (gss_buffer_t, octet-string, modify) The canonical
contiguous string form of @@input_name.  Storage associated with
this string must freed by the application after use with
gss_release_buffer().


To produce a canonical contiguous string representation of a
mechanism name (MN), suitable for direct comparison (e.g. with
memcmp) for use in authorization functions (e.g. matching entries
in an access-control list).  The @@input_name parameter must specify
a valid MN (i.e. an internal name generated by
gss_accept_sec_context() or by gss_canonicalize_name()).

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_NAME_NOT_MN}: The provided internal name was not a mechanism
name.


@code{GSS_S_BAD_NAME}: The provided internal name was ill-formed.


@code{GSS_S_BAD_NAMETYPE}: The internal name was of a type not supported
by the GSS-API implementation.
@end deftypefun

@subheading gss_canonicalize_name
@anchor{gss_canonicalize_name}
@deftypefun {OM_uint32} {gss_canonicalize_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{input_name}, const gss_OID @var{mech_type}, gss_name_t * @var{output_name})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{input_name}: (gss_name_t, read) The name for which a canonical form
is desired.

@var{mech_type}: (Object ID, read) The authentication mechanism for
which the canonical form of the name is desired.  The desired
mechanism must be specified explicitly; no default is provided.

@var{output_name}: (gss_name_t, modify) The resultant canonical name.
Storage associated with this name must be freed by the
application after use with a call to gss_release_name().


Generate a canonical mechanism name (MN) from an arbitrary internal
name.  The mechanism name is the name that would be returned to a
context acceptor on successful authentication of a context where
the initiator used the input_name in a successful call to
gss_acquire_cred, specifying an OID set containing @@mech_type as
its only member, followed by a call to gss_init_sec_context(),
specifying @@mech_type as the authentication mechanism.

Return value:


@code{GSS_S_COMPLETE}: Successful completion.
@end deftypefun

@subheading gss_duplicate_name
@anchor{gss_duplicate_name}
@deftypefun {OM_uint32} {gss_duplicate_name} (OM_uint32 * @var{minor_status}, const gss_name_t @var{src_name}, gss_name_t * @var{dest_name})
@var{minor_status}: (Integer, modify) Mechanism specific status code.

@var{src_name}: (gss_name_t, read) Internal name to be duplicated.

@var{dest_name}: (gss_name_t, modify) The resultant copy of @@src_name.
Storage associated with this name must be freed by the application
after use with a call to gss_release_name().


Create an exact duplicate of the existing internal name @@src_name.
The new @@dest_name will be independent of src_name (i.e. @@src_name
and @@dest_name must both be released, and the release of one shall
not affect the validity of the other).

Return value:


@code{GSS_S_COMPLETE}: Successful completion.


@code{GSS_S_BAD_NAME}: The src_name parameter was ill-formed.
@end deftypefun