GSS_CALLING_ERROR()

#define             GSS_CALLING_ERROR(x)

GSS_ROUTINE_ERROR()

#define             GSS_ROUTINE_ERROR(x)

GSS_SUPPLEMENTARY_INFO()

#define             GSS_SUPPLEMENTARY_INFO(x)

GSS_ERROR()

#define             GSS_ERROR(x)

gss_acquire_cred ()

OM_uint32
gss_acquire_cred (OM_uint32 *minor_status,
                  const gss_name_t desired_name,
                  OM_uint32 time_req,
                  const gss_OID_set desired_mechs,
                  gss_cred_usage_t cred_usage,
                  gss_cred_id_t *output_cred_handle,
                  gss_OID_set *actual_mechs,
                  OM_uint32 *time_rec);

Allows an application to acquire a handle for a pre-existing credential by name. GSS-API implementations must impose a local access-control policy on callers of this routine to prevent unauthorized callers from acquiring credentials to which they are not entitled. This routine is not intended to provide a "login to the network" function, as such a function would involve the creation of new credentials rather than merely acquiring a handle to existing credentials. Such functions, if required, should be defined in implementation-specific extensions to the API.

If desired_name is GSS_C_NO_NAME, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).

Mechanisms should honor the desired_mechs parameter, and return a credential that is suitable to use only with the requested mechanisms. An exception to this is the case where one underlying credential element can be shared by multiple mechanisms; in this case it is permissible for an implementation to indicate all mechanisms with which the credential element may be used. If desired_mechs is an empty set, behavior is undefined.

This routine is expected to be used primarily by context acceptors, since implementations are likely to provide mechanism-specific ways of obtaining GSS-API initiator credentials from the system login process. Some implementations may therefore not support the acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name produced by applying either gss_inquire_cred to a valid credential, or gss_inquire_context to an active context.

If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required (e.g. by gss_init_sec_context or gss_accept_sec_context). Such mechanism-specific implementation decisions should be invisible to the calling application; thus a call of gss_inquire_cred immediately following the call of gss_acquire_cred must return valid credential data, and may therefore incur the overhead of a deferred credential acquisition.

gss_release_cred ()

OM_uint32
gss_release_cred (OM_uint32 *minor_status,
                  gss_cred_id_t *cred_handle);

Informs GSS-API that the specified credential handle is no longer required by the application, and frees associated resources. The cred_handle is set to GSS_C_NO_CREDENTIAL on successful completion of this call.

gss_init_sec_context ()

OM_uint32
gss_init_sec_context (OM_uint32 *minor_status,
                      const gss_cred_id_t initiator_cred_handle,
                      gss_ctx_id_t *context_handle,
                      const gss_name_t target_name,
                      const gss_OID mech_type,
                      OM_uint32 req_flags,
                      OM_uint32 time_req,
                      const gss_channel_bindings_t input_chan_bindings,
                      const gss_buffer_t input_token,
                      gss_OID *actual_mech_type,
                      gss_buffer_t output_token,
                      OM_uint32 *ret_flags,
                      OM_uint32 *time_rec);

Initiates the establishment of a security context between the application and a remote peer. Initially, the input_token parameter should be specified either as GSS_C_NO_BUFFER, or as a pointer to a gss_buffer_desc object whose length field contains the value zero. The routine may return a output_token which should be transferred to the peer application, where the peer application will present it to gss_accept_sec_context. If no token need be sent, gss_init_sec_context will indicate this by setting the length field of the output_token argument to zero. To complete the context establishment, one or more reply tokens may be required from the peer application; if so, gss_init_sec_context will return a status containing the supplementary information bit GSS_S_CONTINUE_NEEDED. In this case, gss_init_sec_context should be called again when the reply token is received from the peer application, passing the reply token to gss_init_sec_context via the input_token parameters.

Portable applications should be constructed to use the token length and return status to determine whether a token needs to be sent or waited for. Thus a typical portable caller should always invoke gss_init_sec_context within a loop: