Next: Optional Parameters, Previous: Simple Data Types, Up: Standard GSS API
A credential handle is a caller-opaque atomic datum that identifies a
GSS-API credential data structure. It is represented by the caller-
opaque type gss_cred_id_t.
GSS-API credentials can contain mechanism-specific principal authentication data for multiple mechanisms. A GSS-API credential is composed of a set of credential-elements, each of which is applicable to a single mechanism. A credential may contain at most one credential-element for each supported mechanism. A credential-element identifies the data needed by a single mechanism to authenticate a single principal, and conceptually contains two credential-references that describe the actual mechanism-specific authentication data, one to be used by GSS-API for initiating contexts, and one to be used for accepting contexts. For mechanisms that do not distinguish between acceptor and initiator credentials, both references would point to the same underlying mechanism-specific authentication data.
Credentials describe a set of mechanism-specific principals, and give their holder the ability to act as any of those principals. All principal identities asserted by a single GSS-API credential should belong to the same entity, although enforcement of this property is an implementation-specific matter. The GSS-API does not make the actual credentials available to applications; instead a credential handle is used to identify a particular credential, held internally by GSS-API. The combination of GSS-API credential handle and mechanism identifies the principal whose identity will be asserted by the credential when used with that mechanism.
The gss_init_sec_context and gss_accept_sec_context
routines allow the value GSS_C_NO_CREDENTIAL to be specified as
their credential handle parameter. This special credential-handle
indicates a desire by the application to act as a default principal.
The gss_ctx_id_t data type contains a caller-opaque atomic
value that identifies one end of a GSS-API security context.
The security context holds state information about each end of a peer communication, including cryptographic state information.
A token is a caller-opaque type that GSS-API uses to maintain
synchronization between the context data structures at each end of a
GSS-API security context. The token is a cryptographically protected
octet-string, generated by the underlying mechanism at one end of a
GSS-API security context for use by the peer mechanism at the other
end. Encapsulation (if required) and transfer of the token are the
responsibility of the peer applications. A token is passed between
the GSS-API and the application using the gss_buffer_t
conventions.
Certain GSS-API routines are intended to transfer data between
processes in multi-process programs. These routines use a
caller-opaque octet-string, generated by the GSS-API in one process
for use by the GSS-API in another process. The calling application is
responsible for transferring such tokens between processes in an
OS-specific manner. Note that, while GSS-API implementors are
encouraged to avoid placing sensitive information within interprocess
tokens, or to cryptographically protect them, many implementations
will be unable to avoid placing key material or other sensitive data
within them. It is the application's responsibility to ensure that
interprocess tokens are protected in transit, and transferred only to
processes that are trustworthy. An interprocess token is passed
between the GSS-API and the application using the gss_buffer_t
conventions.
A name is used to identify a person or entity. GSS-API authenticates the relationship between a name and the entity claiming the name.
Since different authentication mechanisms may employ different namespaces for identifying their principals, GSSAPI's naming support is necessarily complex in multi-mechanism environments (or even in some single-mechanism environments where the underlying mechanism supports multiple namespaces).
Two distinct representations are defined for names:
gss_name_t type. It is opaque to
GSS-API callers. A single gss_name_t object may contain
multiple names from different namespaces, but all names should refer
to the same entity. An example of such an internal name would be the
name returned from a call to the gss_inquire_cred routine, when
applied to a credential containing credential elements for multiple
authentication mechanisms employing different namespaces. This
gss_name_t object will contain a distinct name for the entity
for each authentication mechanism.
For GSS-API implementations supporting multiple namespaces, objects of
type gss_name_t must contain sufficient information to
determine the namespace to which each primitive name belongs.
Routines (gss_import_name and gss_display_name) are
provided to convert names between contiguous string representations
and the internal gss_name_t type. gss_import_name may
support multiple syntaxes for each supported namespace, allowing users
the freedom to choose a preferred name
representation. gss_display_name should use an
implementation-chosen printable syntax for each supported name-type.
If an application calls gss_display_name, passing the internal
name resulting from a call to gss_import_name, there is no
guarantee the the resulting contiguous string name will be the same as
the original imported string name. Nor do name-space identifiers
necessarily survive unchanged after a journey through the internal
name-form. An example of this might be a mechanism that authenticates
X.500 names, but provides an algorithmic mapping of Internet DNS names
into X.500. That mechanism's implementation of gss_import_name
might, when presented with a DNS name, generate an internal name that
contained both the original DNS name and the equivalent X.500 name.
Alternatively, it might only store the X.500 name. In the latter
case, gss_display_name would most likely generate a printable
X.500 name, rather than the original DNS name.
The process of authentication delivers to the context acceptor an
internal name. Since this name has been authenticated by a single
mechanism, it contains only a single name (even if the internal name
presented by the context initiator to gss_init_sec_context had
multiple components). Such names are termed internal mechanism names,
or "MN"s and the names emitted by gss_accept_sec_context are
always of this type. Since some applications may require MNs without
wanting to incur the overhead of an authentication operation, a second
function, gss_canonicalize_name, is provided to convert a
general internal name into an MN.
Comparison of internal-form names may be accomplished via the
gss_compare_name routine, which returns true if the two names
being compared refer to the same entity. This removes the need for
the application program to understand the syntaxes of the various
printable names that a given GSS-API implementation may support.
Since GSS-API assumes that all primitive names contained within a
given internal name refer to the same entity, gss_compare_name
can return true if the two names have at least one primitive name in
common. If the implementation embodies knowledge of equivalence
relationships between names taken from different namespaces, this
knowledge may also allow successful comparison of internal names
containing no overlapping primitive elements.
When used in large access control lists, the overhead of invoking
gss_import_name and gss_compare_name on each name from
the ACL may be prohibitive. As an alternative way of supporting this
case, GSS-API defines a special form of the contiguous string name
which may be compared directly (e.g. with memcmp()). Contiguous names
suitable for comparison are generated by the gss_export_name
routine, which requires an MN as input. Exported names may be re-
imported by the gss_import_name routine, and the resulting
internal name will also be an MN. The gss_OID constant
GSS_C_NT_EXPORT_NAME indentifies the "export name" type, and
the value of this constant is given in Appendix A. Structurally, an
exported name object consists of a header containing an OID
identifying the mechanism that authenticated the name, and a trailer
containing the name itself, where the syntax of the trailer is defined
by the individual mechanism specification. The precise format of an
export name is defined in the language-independent GSS-API
specification [GSSAPI].
Note that the results obtained by using gss_compare_name will
in general be different from those obtained by invoking
gss_canonicalize_name and gss_export_name, and then
comparing the exported names. The first series of operation
determines whether two (unauthenticated) names identify the same
principal; the second whether a particular mechanism would
authenticate them as the same principal. These two operations will in
general give the same results only for MNs.
The gss_name_t datatype should be implemented as a pointer
type. To allow the compiler to aid the application programmer by
performing type-checking, the use of (void *) is discouraged. A
pointer to an implementation-defined type is the preferred choice.
Storage is allocated by routines that return gss_name_t
values. A procedure, gss_release_name, is provided to free
storage associated with an internal-form name.
GSS-API supports the use of user-specified tags to identify a given context to the peer application. These tags are intended to be used to identify the particular communications channel that carries the context. Channel bindings are communicated to the GSS-API using the following structure:
typedef struct gss_channel_bindings_struct {
OM_uint32 initiator_addrtype;
gss_buffer_desc initiator_address;
OM_uint32 acceptor_addrtype;
gss_buffer_desc acceptor_address;
gss_buffer_desc application_data;
} *gss_channel_bindings_t;
The initiator_addrtype and acceptor_addrtype fields denote the type of addresses contained in the initiator_address and acceptor_address buffers. The address type should be one of the following:
GSS_C_AF_UNSPEC Unspecified address type GSS_C_AF_LOCAL Host-local address type GSS_C_AF_INET Internet address type (e.g. IP) GSS_C_AF_IMPLINK ARPAnet IMP address type GSS_C_AF_PUP pup protocols (eg BSP) address type GSS_C_AF_CHAOS MIT CHAOS protocol address type GSS_C_AF_NS XEROX NS address type GSS_C_AF_NBS nbs address type GSS_C_AF_ECMA ECMA address type GSS_C_AF_DATAKIT datakit protocols address type GSS_C_AF_CCITT CCITT protocols GSS_C_AF_SNA IBM SNA address type GSS_C_AF_DECnet DECnet address type GSS_C_AF_DLI Direct data link interface address type GSS_C_AF_LAT LAT address type GSS_C_AF_HYLINK NSC Hyperchannel address type GSS_C_AF_APPLETALK AppleTalk address type GSS_C_AF_BSC BISYNC 2780/3780 address type GSS_C_AF_DSS Distributed system services address type GSS_C_AF_OSI OSI TP4 address type GSS_C_AF_X25 X.25 GSS_C_AF_NULLADDR No address specified
Note that these symbols name address families rather than specific addressing formats. For address families that contain several alternative address forms, the initiator_address and acceptor_address fields must contain sufficient information to determine which address form is used. When not otherwise specified, addresses should be specified in network byte-order (that is, native byte-ordering for the address family).
Conceptually, the GSS-API concatenates the initiator_addrtype,
initiator_address, acceptor_addrtype, acceptor_address and
application_data to form an octet string. The mechanism calculates a
MIC over this octet string, and binds the MIC to the context
establishment token emitted by gss_init_sec_context. The same bindings
are presented by the context acceptor to gss_accept_sec_context, and a
MIC is calculated in the same way. The calculated MIC is compared with
that found in the token, and if the MICs differ,
gss_accept_sec_context will return a GSS_S_BAD_BINDINGS error, and the
context will not be established. Some mechanisms may include the
actual channel binding data in the token (rather than just a MIC);
applications should therefore not use confidential data as
channel-binding components.
Individual mechanisms may impose additional constraints on addresses
and address types that may appear in channel bindings. For example, a
mechanism may verify that the initiator_address field of the channel
bindings presented to gss_init_sec_context contains the correct
network address of the host system. Portable applications should
therefore ensure that they either provide correct information for the
address fields, or omit addressing information, specifying
GSS_C_AF_NULLADDR as the address-types.