3.2.1 Credentials

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.

3.2.2 Contexts

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.

3.2.3 Authentication tokens

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.

3.2.4 Interprocess tokens

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.

3.2.5 Names

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:

• An internal form. This is the GSS-API "native" format for names, represented by the implementation-specific 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.

• Mechanism-specific contiguous octet-string forms. A format capable of containing a single name (from a single namespace). Contiguous string names are always accompanied by an object identifier specifying the namespace to which the name belongs, and their format is dependent on the authentication mechanism that employs the name. Many, but not all, contiguous string names will be printable, and may therefore be used by GSS-API applications for communication with their users.

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 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.

3.2.6 Channel Bindings

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.