GSSAPI routines as read-only.  In particular, the application should
   not attempt to deallocate them.  The gss_OID_desc datatype is
   equivalent to the X/Open OM_object_identifier datatype [2].

2.1.5. Object Identifier Sets

   Certain GSSAPI procedures take parameters of the type gss_OID_set.
   This type represents one or more object identifiers (section 2.1.4).
   A gss_OID_set object has the following structure:

                 typedef struct gss_OID_set_desc_struct {
                    int       count;
                    gss_OID   elements;
                 } gss_OID_set_desc, *gss_OID_set;

   The count field contains the number of OIDs within the set.  The
   elements field is a pointer to an array of gss_OID_desc objects, each
   of which describes a single OID. gss_OID_set values are used to name
   the available mechanisms supported by the GSSAPI, to request the use
   of specific mechanisms, and to indicate which mechanisms a given
   credential supports.  Storage associated with gss_OID_set values
   returned to the application by the GSSAPI may be deallocated by the
   gss_release_oid_set routine.

2.1.6. Credentials

   A credential handle is a caller-opaque atomic datum that identifies a
   GSSAPI credential data structure.  It is represented by the caller-
   opaque type gss_cred_id_t, which may be implemented as either an
   arithmetic or a pointer type.  Credentials describe a principal, and
   they give their holder the ability to act as that principal.  The
   GSSAPI does not make the actual credentials available to
   applications; instead the credential handle is used to identify a
   particular credential, held internally by GSSAPI or underlying




 
RFC 1509            GSSAPI - Overview and C bindings      September 1993


   mechanism.  Thus the credential handle contains no security-relavent
   information, and requires no special protection by the application.
   Depending on the implementation, a given credential handle may refer
   to different credentials when presented to the GSSAPI by different
   callers.  Individual GSSAPI implementations should define both the
   scope of a credential handle and the scope of a credential itself
   (which must be at least as wide as that of a handle).  Possibilities
   for credential handle scope include the process that acquired the
   handle, the acquiring process and its children, or all processes
   sharing some local identification information (e.g., UID).  If no
   handles exist by which a given credential may be reached, the GSSAPI
   may delete the credential.

   Certain routines allow credential handle parameters to be omitted to
   indicate the use of a default credential.  The mechanism by which a
   default credential is established and its scope should be defined by
   the individual GSSAPI implementation.

2.1.7. Contexts

   The gss_ctx_id_t data type contains a caller-opaque atomic value that
   identifies one end of a GSSAPI security context.  It may be
   implemented as either an arithmetic or a pointer type. Depending on
   the implementation, a given gss_ctx_id_t value may refer to different
   GSSAPI security contexts when presented to the GSSAPI by different
   callers.  The security context holds state information about each end
   of a peer communication, including cryptographic state information.
   Individual GSSAPI implementations should define the scope of a
   context.  Since no way is provided by which a new gss_ctx_id_t value
   may be obtained for an existing context, the scope of a context
   should be the same as the scope of a gss_ctx_id_t.

2.1.8. Authentication tokens

   A token is a caller-opaque type that GSSAPI uses to maintain
   synchronization between the context data structures at each end of a
   GSSAPI security context.  The token is a cryptographically protected
   bit-string, generated by the underlying mechanism at one end of a
   GSSAPI 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 GSSAPI and the application using the gss_buffer_t conventions.

2.1.9. Status values

   One or more status codes are returned by each GSSAPI routine.  Two
   distinct sorts of status codes are returned.  These are termed GSS
   status codes and Mechanism status codes.




 
RFC 1509            GSSAPI - Overview and C bindings      September 1993


2.1.9.1. GSS status codes