JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Developer's Guide to Oracle Solaris 11 Security     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

1.  Oracle Solaris Security for Developers (Overview)

2.  Developing Privileged Applications

3.  Writing PAM Applications and Services

4.  Writing Applications That Use GSS-API

5.  GSS-API Client Example

6.  GSS-API Server Example

7.  Writing Applications That Use SASL

8.  Introduction to the Oracle Solaris Cryptographic Framework

9.  Writing User-Level Cryptographic Applications

10.  Introduction to the Oracle Solaris Key Management Framework

A.  Secure Coding Guidelines for Developers

B.  Sample C-Based GSS-API Programs

C.  GSS-API Reference

GSS-API Functions

Functions From Previous Versions of GSS-API

Functions for Manipulating OIDs

Renamed Functions

GSS-API Status Codes

GSS-API Major Status Code Values

Displaying Status Codes

Status Code Macros

GSS-API Data Types and Values

Basic GSS-API Data Types

OM_uint32

gss_buffer_desc

gss_OID_desc

gss_OID_set_desc

gss_channel_bindings_struct

Name Types

Address Types for Channel Bindings

Implementation-Specific Features in GSS-API

Oracle Solaris-Specific Functions

Human-Readable Name Syntax

Format of Anonymous Names

Implementations of Selected Data Types

Deletion of Contexts and Stored Data

Protection of Channel-Binding Information

Context Exportation and Interprocess Tokens

Types of Credentials Supported

Credential Expiration

Context Expiration

Wrap Size Limits and QOP Values

Use of minor_status Parameter

Kerberos v5 Status Codes

Messages Returned in Kerberos v5 for Status Code 1

Messages Returned in Kerberos v5 for Status Code 2

Messages Returned in Kerberos v5 for Status Code 3

Messages Returned in Kerberos v5 for Status Code 4

Messages Returned in Kerberos v5 for Status Code 5

Messages Returned in Kerberos v5 for Status Code 6

Messages Returned in Kerberos v5 for Status Code 7

D.  Specifying an OID

E.  Source Code for SASL Example

F.  SASL Reference Tables

Glossary

Index

GSS-API Status Codes

Major status codes are encoded in the OM_uint32 as shown in the following figure.

Figure C-1 Major-Status Encoding

image:Diagram shows how major status codes are encoded in OM_uint32.

If a GSS-API routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call has failed. If the calling error field is nonzero, the application's call of the routine was erroneous. The calling errors are listed in Table C-1. If the routine error field is nonzero, the routine failed because of a routine-specific error, as listed in Table C-2. The bits in the supplementary information field of the status code can be set whether the upper 16 bits indicate a failure or a success. The meaning of individual bits is listed in Table C-3.

GSS-API Major Status Code Values

The following tables list the calling errors that are returned by GSS-API. These errors are specific to a particular language-binding, which is C in this case.

Table C-1 GSS-API Calling Errors

Error
Value in Field
Meaning
GSS_S_CALL_INACCESSIBLE_READ
1
An input parameter that is required could not be read
GSS_S_CALL_INACCESSIBLE_WRITE
2
A required output parameter could not be written
GSS_S_CALL_BAD_STRUCTURE
3
A parameter was malformed

The following table lists the GSS-API routine errors, generic errors that are returned by GSS-API functions.

Table C-2 GSS-API Routine Errors

Error
Value in Field
Meaning
GSS_S_BAD_MECH
1
An unsupported mechanism was requested.
GSS_S_BAD_NAME
2
An invalid name was supplied.
GSS_S_BAD_NAMETYPE
3
A supplied name was of an unsupported type.
GSS_S_BAD_BINDINGS
4
Incorrect channel bindings were supplied.
GSS_S_BAD_STATUS
5
An invalid status code was supplied.
GSS_S_BAD_MIC, GSS_S_BAD_SIG
6
A token had an invalid MIC.
GSS_S_NO_CRED
7
The credentials were unavailable, inaccessible, or not supplied.
GSS_S_NO_CONTEXT
8
No context has been established.
GSS_S_DEFECTIVE_TOKEN
9
A token was invalid.
GSS_S_DEFECTIVE_CREDENTIAL
10
A credential was invalid.
GSS_S_CREDENTIALS_EXPIRED
11
The referenced credentials have expired.
GSS_S_CONTEXT_EXPIRED
12
The context has expired.
GSS_S_FAILURE
13
Miscellaneous failure. The underlying mechanism detected an error for which no specific GSS–API status code is defined. The mechanism-specific status code, that is, the minor-status code, provides more details about the error.
GSS_S_BAD_QOP
14
The quality-of-protection that was requested could not be provided.
GSS_S_UNAUTHORIZED
15
The operation is forbidden by local security policy.
GSS_S_UNAVAILABLE
16
The operation or option is unavailable.
GSS_S_DUPLICATE_ELEMENT
17
The requested credential element already exists.
GSS_S_NAME_NOT_MN
18
The provided name was not a mechanism name (MN).

The name GSS_S_COMPLETE, which is a zero value, indicates an absence of any API errors or supplementary information bits.

The following table lists the supplementary information values returned by GSS-API functions.

Table C-3 GSS-API Supplementary Information Codes

Code
Bit Number
Meaning
GSS_S_CONTINUE_NEEDED
0 (LSB)
Returned only by gss_init_sec_context() or gss_accept_sec_context(). The routine must be called again to complete its function.
GSS_S_DUPLICATE_TOKEN
1
The token was a duplicate of an earlier token.
GSS_S_OLD_TOKEN
2
The token's validity period has expired.
GSS_S_UNSEQ_TOKEN
3
A later token has already been processed.
GSS_S_GAP_TOKEN
4
An expected per-message token was not received.

For more on status codes, see GSS-API Status Codes.

Displaying Status Codes

The function gss_display_status() translates GSS-API status codes into text format. This format allows the codes to be displayed to a user or put in a text log. gss_display_status() only displays one status code at a time, and some functions can return multiple status conditions. Accordingly, gss_display_status() should be called as part of a loop. When gss_display_status() indicates a non-zero status code, another status code is available for the function to fetch.

Example C-1 Displaying Status Codes with gss_display_status()

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);

Status Code Macros

The macros, GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and GSS_SUPPLEMENTARY_INFO(), take a GSS status code. These macros remove all information except for the relevant field. For example, the GSS_ROUTINE_ERROR() can be applied to a status code to remove the calling errors and supplementary information fields. This operation leaves the routine errors field only. The values delivered by these macros can be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() returns a non-zero value if a status code indicates a calling or routine error, and a zero value otherwise. All macros that are defined by GSS-API evaluate the arguments exactly once.