Next: Miscellaneous Routines, Previous: Per-Message Routines, Up: Standard GSS API
GSS-API Name manipulation Routines
Routine Function
------- --------
gss_import_name Convert a contiguous string name
to internal-form.
gss_display_name Convert internal-form name to
text.
gss_compare_name Compare two internal-form names.
gss_release_name Discard an internal-form name.
gss_inquire_names_for_mech List the name-types supported by.
the specified mechanism.
gss_inquire_mechs_for_name List mechanisms that support the
specified name-type.
gss_canonicalize_name Convert an internal name to an MN.
gss_export_name Convert an MN to export form.
gss_duplicate_name Create a copy of an internal name.
minor_status: (Integer, modify) Mechanism specific status code.
input_name_buffer: (buffer, octet-string, read) Buffer containing contiguous string name to convert.
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.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAMETYPE: The input_name_type was unrecognized.
GSS_S_BAD_NAME: The input_name parameter could not be interpreted as a name of the specified type.
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.
minor_status: (Integer, modify) Mechanism specific status code.
input_name: (gss_name_t, read) Name to be displayed.
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().
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAME: @input_name was ill-formed.
minor_status: (Integer, modify) Mechanism specific status code.
name1: (gss_name_t, read) Internal-form name.
name2: (gss_name_t, read) Internal-form name.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAMETYPE: The two names were of incomparable types.
GSS_S_BAD_NAME: One or both of name1 or name2 was ill-formed.
minor_status: (Integer, modify) Mechanism specific status code.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAME: The name parameter did not contain a valid name.
minor_status: (Integer, modify) Mechanism specific status code.
mechanism: (gss_OID, read) The mechanism to be interrogated.
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:
GSS_S_COMPLETE: Successful completion.
minor_status: (Integer, modify) Mechanism specific status code.
input_name: (gss_name_t, read) The name to which the inquiry relates.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAME: The input_name parameter was ill-formed.
GSS_S_BAD_NAMETYPE: The input_name parameter contained an invalid or unsupported type of name.
minor_status: (Integer, modify) Mechanism specific status code.
input_name: (gss_name_t, read) The name for which a canonical form is desired.
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.
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:
GSS_S_COMPLETE: Successful completion.
minor_status: (Integer, modify) Mechanism specific status code.
input_name: (gss_name_t, read) The MN to be exported.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_NAME_NOT_MN: The provided internal name was not a mechanism name.
GSS_S_BAD_NAME: The provided internal name was ill-formed.
GSS_S_BAD_NAMETYPE: The internal name was of a type not supported by the GSS-API implementation.
minor_status: (Integer, modify) Mechanism specific status code.
src_name: (gss_name_t, read) Internal name to be duplicated.
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:
GSS_S_COMPLETE: Successful completion.
GSS_S_BAD_NAME: The src_name parameter was ill-formed.