gssapi(5)

General Information

The Generic Security Service Application Programming Interface (GSSAPI) provides security services to applications using peer-to-peer communications. Using GSSAPI routines, applications can perform the following operations:

GSSAPI supports a secure connection between two communicating applications. The application that establishes the secure connection is called the context initiator. The application that accepts the secure connection is the context acceptor

There are four stages involved in using the GSSAPI:

The applications use credentials to establish their global identity. The global identity can be, but is not necessarily, related to the local user name under which the application is running. Credentials can contain either of the following:

The security context is a pair of GSSAPI data structures that contain information that is shared between the communicating applications. The information describes the state of each application. This security context is required for per-message security services.

To establish a security context, the context initiator calls the gss_init_sec_context() routine to get a token. The token is cryptographically protected, opaque data. The context initiator transfers the token to the context acceptor, which in turn passes the token to the gss_accept_sec_context() routine to decode and extract the shared information.

As part of establishing the security context, the context initiator is authenticated to the context acceptor. The context initiator can require the context acceptor to authenticate itself in return.

The context initiator can delegate rights to allow the context acceptor to act as its agent. Delegation means the context initiator gives the context acceptor the ability to initiate additional security contexts as an agent of the context initiator. To delegate, the context initiator sets a flag on the gss_init_sec_context() routine indicating that it wants to delegate and sends the returned token in the normal way to the context acceptor. The acceptor passes this token to the gss_accept_sec_context() routine, which generates a delegated credential. The context acceptor can use the credential to initiate additional security contexts. The applications can exchange protected messages and data using this context.

The applications can call GSSAPI routines to protect data exchanged in messages. The application sends a protected message by calling the appropriate GSSAPI routine to do the following:

The application can then send the resulting information to the peer application.

The application that receives the message passes the received data to a GSSAPI routine, which removes the protection and validates the data.

GSSAPI treats application data as arbitrary octet strings. The GSSAPI per-message security services can provide either of the following:

When the applications have finished communicating, either one may instruct GSSAPI to delete the security context.

The Standard GSSAPI routines are defined in the "Internet RFC 2743, Generic Security Service Application Programming Interface," and "RFC 2744, Generic Security Service API : C-bindings." These routines have the prefix gss_.

The following sections provide an overview of the GSSAPI error handling and data types.

Error Handling

Each GSSAPI routine returns two status values, major and minor:

If a routine has output parameters that contain pointers for storage allocated by the routine, the output parameters will always contain a valid pointer even if the routine returns an error. If no storage was allocated, the routine sets the pointer to NULL and sets any length fields associated with the pointers (such as in the gss_buffer_desc structure) to 0 (zero).

Minor status values usually contain more detailed information about the error. They are not, however, portable between GSSAPI implementations. When designing portable applications, use major status values for handling errors. Use minor status values to debug applications and to display error and error-recovery information to users.

GSSAPI Data Types

This section provides an overview of the GSSAPI data types and their definitions.

Credentials

Credentials establish, or prove, the identity of an application or other principal.

The gss_cred_id_t data type is an atomic data type that identifies a GSSAPI credential data structure.

Contexts

The security context is a pair of GSSAPI data structures that contain information shared between the communicating applications. The information describes the cryptographic state of each application. This security context is required for per-message security services and is created by a successful authentication exchange.

The gss_ctx_id_t data type contains an atomic value that identifies one end of a GSSAPI security context. The data type is opaque to the caller.

Authentication Tokens

GSSAPI uses tokens to maintain the synchronization between the applications sharing a security context. The token is a cryptographically protected bit string generated by the security mechanism at one end of the GSSAPI security context for use by the peer application at the other end of the security context. The data type is opaque to the caller.

The applications use the gss_buffer_t data type as tokens to GSSAPI routines.

Major Status Values

GSSAPI routines return GSS status codes as their OM_uint32 function value. These codes indicate either generic API routine errors or calling errors.

A GSS status code can indicate a single, fatal generic API error from the routine and a single calling error. Additional status information can also be contained in the GSS status code. The errors are encoded into a 32-bit GSS status code, as follows:

If a GSSAPI routine returns a GSS status code whose upper 16 bits contain a nonzero value,means the call has failed. If the calling error field is nonzero, the context initiator's use of the routine was in error. In addition, the routine can indicate additional information by setting bits in the supplementary information field of the status code. The tables that follow describe the routine errors, calling errors, and supplementary information status bits and their meanings.

The following table lists the GSSAPI routine errors and their meanings:

The following table lists the calling error values and their meanings:

The following table lists the supplementary bits and their meanings.

All GSS_S_ symbols equate to complete OM_uint32 status codes, rather than to bitfield values. For example, the actual value of GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16.

The major status code GSS_S_FAILURE indicates that the underlying security mechanism has detected an error for which no major status code is available. Check the minor status code for details about the error. See the section on minor status values for more information.

The GSSAPI provides three macros:

Each macro takes a GSS status code and masks all but the relevant field. For example, when you use the GSS_ROUTINE_ERROR() macro on a status code, it returns a value. The value of the macro is arrived at by using only the routine errors field and zeroing the values of the calling error and the supplementary information fields.

An additional macro, GSS_ERROR(), lets you determine whether the status code indicated a calling or routine error. If the status code indicated a calling or routine error, the macro returns a nonzero value. If no calling or routine error is indicated, the macro returns a 0 (zero).

NOTE: At times, a GSSAPI routine that is unable to access data can generate a platform-specific signal, instead of returning a GSS_S_CALL_INACCESSIBLE_READ or GSS_S_CALL_INACCESSIBLE_WRITE status value.

Minor Status Values

The GSSAPI routines return a minor_status parameter to indicate errors from the underlying security mechanism. The parameter can contain a single error, indicated by an OM_uint32 datatype value.

Names

Names identify principals. The GSSAPI authenticates the relationship between a name and the principal claiming the name.

Names are represented in two forms:

The gss_import_name() and gss_display_name() routines convert names between their printable form and their gss_name_tdata type.

The gss_compare_name() routine compares internal form names.

Channel Bindings

You can define and use channel bindings to associate the security context with the communications channel that carries the context. Channel bindings are communicated to the GSSAPI by using the following structure:

Use the initiator_addrtype and acceptor_addrtype fields to initiate the type of addresses contained in the initiator_address and acceptor_address buffers. The following table lists the address types and their addrtype values:

The tags specify address families rather than addressing formats. For address families that contain several alternative address forms, the initiator_address and the acceptor_address fields should contain sufficient information to determine which address form is used. Format the bytes that contain the addresses in the order in which the bytes are transmitted across the network.

The GSSAPI creates an octet string by concatenating all the fields (initiator_addrtype, initiator_address, acceptor_addrtype, acceptor_address, and application_data). The security mechanism signs the octet string and binds the signature to the token generated by the gss_init_sec_context() routine. The context acceptor presents the same bindings to the gss_accept_sec_context() routine, which evaluates the signature and compares it to the signature in the token. If the signatures differ, the gss_accept_sec_context() routine returns a GSS_S_BAD_BINDINGS error, and the context is not established.

Some security mechanisms check that the initiator_address field of the channel bindings presented to the gss_init_sec_context() routine contains the correct network address of the host system. Therefore portable applications should use either the correct address type and value or the GSS_C_AF_NULLADDR for the initiator_addrtype address field. Some security mechanisms include the channel binding data in the token instead of a signature, so portable applications should not use confidential data as channel-binding components. The GSSAPI does not verify the address or include the plain text bindings information in the token.

Optional Parameters

In routine descriptions, optional parameters allow the application to request default behaviors by passing a default value for the parameter. The following conventions are used for optional parameters: