HP Open Source Security for OpenVMS Volume 3: Kerberos > Chapter 5 GSSAPI (Generic Security Services Application Programming Interface)

gss_display_status — Convert GSSAPI status code to text for user display

  Table of Contents

  Glossary

  Index

C Prototype

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

Arguments

minor_status (output) 

An implementation-specific status code.

status_value (input) 

The status value to be converted.

status_type (input) 

One of the following values:

GSS_C_GSS_CODE — The status_value is a GSS status code.

GSS_C_MECH_CODE — The status_value is a mechanism status code.

mech_type (input) 

The underlying mechanism (used to interpret a minor_status value). Supply GSS_C_NO_OID to obtain the system default.

message_context (input/output)
  

This argument should be initialized to zero by the caller on the first call. If further messages are contained in the status_value argument, message_context will be nonzero on return, and this value should be passed back to subsequent calls, along with the same status_value, status_type, and mech_type arguments.

status_string (output) 

The textual interpretation of the status_value. Storage associated with this argument must be freed by the application after use with a call to gss_release_buffer.

Description

This routine allows an application to obtain a textual representation of a GSSAPI status code, for display to the user or for logging purposes. Since some status values may indicate multiple conditions, applications may need to call gss_display_status multiple times, each call generating a single text string. The message_context argument is used to store state information about which error messages have already been extracted from a given status_value; message_context must be initialized to zero by the application prior to the first call, and gss_display_status will return a nonzero value in this argument if there are further messages to extract.

The message_context argument contains all state information required by gss_display_status in order to extract further messages from the status_value; even when a nonzero value is returned in this argument, the application is not required to call gss_display_status again unless subsequent messages are desired. The following code extracts all messages from a given status code and prints them to SYS$ERROR.

OM_uint32 message_context;
OM_uint32 status_code;
OM_uint32 maj_status;
OM_uint32 min_status;
gss_buffer_desc status_string;
.
.
.
message_context = 0;

do {
maj_status = gss_display_status(&min_status
status_code,
GSS_C_GSS_CODE,
GSS_C_NO_OID,
&message_context,
&status_string);
fprintf(stderr,
“%.*s\n”,
(int)status_string.length,
(char *)status_string.value);
gss_release_buffer(&min_status, &status_string);
} while (message_context != 0);

Return Values

This routine returns one of the following GSS status codes:

GSS_S_COMPLETE

Successful completion.
GSS_S_BAD_MECHIndicates that translation in accordance with an unsupported mechanism type was requested.
GSS_S_BAD_STATUSThe status_value was not recognized, or the status_type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.