NAME

gss_display_status — Provides an application with the textual representation of a GSSAPI status code that can be displayed to a user or used for logging

Synopsis

OM_uint32  gss_display_status(
OM_uint32 ∗minor_status,
int status_value,
int status_type,
gss_OID mech_type,
int ∗message_context,
gss_buffer_t status_string);

Parameters

Input

status_value
Specifies the status value to convert.

status_type
Specifies one of the following status types:

GSS_C_GSS_CODE
Major status; a GSS status code.

GSS_C_MECH_CODE
Minor status; either a DCE security status code or a Kerberos status code.

mech_typeSpecifies the security mechanism.  To use DCE security, specify either of the following:

   •GSSDCE_C_OID_DCE_KRBV5_DES

   •GSS_C_NULL_OID_SET

To use Kerberos Version 5, specify GSSDCE_C_OID_KRBV5_DES. 

Input/Output

message_context
Indicates whether the status code has multiple messages to read.

The first time an application calls the routine, you initialize the parameter to 0 (zero).  The routine returns the first message.  If there are more messages, the routine sets the parameter to a nonzero value.  The application calls the routine repeatedly to get the next message, until the message_context parameter is zero again. 

Output

status_string
Returns the status value as a text message.

minor_status
Returns a status code from the security mechanism.

Description

The gss_display_status() routine provides the context initiator with a textual representation of a Generic Security Service Application Programming Interface (GSSAPI) status code so that the application can display the message to a user or log the message.  Because some status values can indicate more than one error, the routine enables the calling application to process status codes with multiple messages. 

The message_context parameter indicates which error message the application should extract from the status_value parameter.  The first time an application calls the routine, it should initialize the message_context parameter to 0 (zero) and return the first message.  If there are additional messages to read, the gss_display_status() routine returns a nonzero value.  The application can call gss_display_status() repeatedly to generate a single text string for each call. 

Status Codes

The following describes a partial list of codes (messages) that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all messages.  The following status codes can be returned:

GSS_S_COMPLETE
The routine was completed successfully.

GSS_S_BAD_MECH
The translation requires a mechanism that is unsupported or unavailable.

GSS_S_BAD_STATUS
Either the status value was not recognized or the status type was something other than GSS_C_GSS_CODE or GSS_C_MECH_CODE. 

GSS_S_FAILURE
The routine failed.  Check the minor_status for details. 

Related Information

Functions: gss_accept_sec_context(3sec), gss_acquire_cred(3sec), gss_compare_name(3sec), gss_delete_sec_context(3sec), gss_display_status(3sec), gss_import_name(3sec), gss_inquire_cred(3sec), gssdce_extract_creds_from_sec_context(3sec), gssdce_login_context_to_cred(3sec).