NAME

gssapi_intro — Generic security service application programming interface

Description

This introduction includes general information about the generic security service application programming interface (GSSAPI) defined in Internet RFC 1508, Generic Security Service Application Programming Interface, and RFC 1509, Generic Security Service API : C-bindings.  It also includes an overview of error handling, data types, and calling conventions, including the following:

   •Integer types

   •String and similar data

   •Object identifiers (OIDs)

   •Object identifier sets (OID sets)

   •Credentials

   •Contexts

   •Authentication tokens

   •Major status values

   •Minor status values

   •Names

   •Channel bindings

   •Optional parameters

General Information

The GSSAPI provides security services to applications using peer-to-peer communications (instead of DCE-secure RPC).  Using DCE GSSAPI routines, applications can perform the following operations:

   •Enabling an application to determine another application’s user

   •Enabling an application to delegate access rights to another application

   •Applying security services, such as confidentiality and integrity, on a per-message basis

GSSAPI represents a secure connection between two communicating applications with a data structure called a security context.  The application that establishes the secure connection is called the context indicator or simply indicator.  The context initiator is like a DCE RPC client.  The application that accepts the secure connection is the context acceptor or simply acceptor.  The context acceptor is like a DCE RPC server. 

There are four stages involved in using the GSSAPI, as follows:

   1.The context initiator acquires a credential with which it can prove its identity to other processes.  Similarly, the context acceptor cquires a credential to enable it to accept a security context.  Either application may omit this credential acquistion and use their default credentials in subsequent stages.  See the section on credentials for more information. 

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:

   •Login context

The login context includes a principal’s network credentials, as well as other account information. 

   •Principal name and a key

The key corresponding to the principal name must be registered with the DCE security registration in a key table.  A set of GSSAPI routines enables applications to register and use principal names. 

   2.The communicating applications establish a joint security context by exchanging authentication tokens. 

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 the establishing the 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. 

   3.The applications exchange protected messages and data. 

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:

   •Apply protection

   •Bind the message to the appropriate security context

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:

   •Integrity and authentication of data origin

   •Confidentiality, integrity, and authentication of data origin

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

There are two sets of GSSAPI routines, as follows:

   •Standard GSSAPI routines, which are defined in the Internet RFC 1508, Generic Security Service Application Programming Interface, and RFC 1509, Generic Security Service API : C-bindings.  These routines have the prefix gss_. 

   •OSF DCE extensions to the GSSAPI routines.  These are additional routines that enable an application to use DCE security services.  These routines have the prefix gssdce_. 

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

Error Handling

Each GSSAPI routine returns two types of status values:

   •Major status values, which are generic API routine errors or calling errors defined in RFC 1509. 

   •Minor status values, which indicate DCE-specific errors. 

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. 

Integer Types

The GSSAPI defines the following integer data type:

OM_uint32Z-bit unsigned integer

This integer data type is a portable data type that the GSSAPI routine definitions use for guaranteed minimum bit-counts. 

String and Similar Data

Many of the GSSAPI routines take arguments and return values that describe contiguous multiple-byte data, such as opaque data and character strings.  Use the gss_buffer_t data type, which is a pointer to the buffer descriptor gss_buffer_desc, to pass the data between the GSSAPI routines and applications. 

The  gss_buffer_t data type has the following structure:

typedef struct gss_buffer_desc_struct {
size_t  length;
void    ∗value;
} gss_buffer_desc, ∗gss_buffer_t;

The length field contains the total number of bytes in the data and the value field contains a pointer to the actual data. 

When using the gss_buffer_t data type, the GSSAPI routine allocates storage for any data it passes to the application.  The calling application must allocate the gss_buffer_desc object.  It can initialize unused gss_buffer_desc objects with the value GSS_C_EMPTY_BUFFER.  To free the storage, the application calls the gss_release_buffer() routine. 

Object Identifier

Applications use the gss_OID data type to choose a security mechanism, either DCE security or Kerberos, and to specify name types.  Select a security mechanism by using the following two OIDs:

   •To use DCE security, specify either GSSDCE_C_OID_DCE_KRBV5_DES or GSS_C_NULL_OID. 

   •To use Kerberos Version 5, specify GSSDCE_C_OID_KRBV5_DES. 

Use of the default security mechanisms, specified by the constant GSS_C_NULL_OID, helps to ensure the portability of the application. 

The  gss_OID data type contains tree-structured values defined by ISO and has the following structure:

typedef struct gss_OID_desc_struct {
OM_uint32 length;
void      ∗elements;
}  gss_OID_desc, ∗gss_OID;

The elements field of the structure points to the first byte of an octet string containing the ASN.1 BER encoding of the value of the gss_OID data type.  The length field contains the number of bytes in the value. 

The gss_OID_desc values returned from the GSSAPI are read-only values.  The application should not try to deallocate them. 

Object Identifier Sets

The gss_OID_set data type represents one or more object identifiers.  The values of the gss_OID_set data type are used to do the following:

   •Report the available mechanisms supported by GSSAPI

   •Request specific mechanisms

   •Indicate which mechanisms a credential supports

The gss_OID_set data type has the following structure:

typedef struct gss_OID_set_desc_struct {
int     count;
gss_OIDelements;
} gss_OID_set_desc, ∗gss_OID_set;

The count field contains the number of OIDs in the set.  The elements field is a pointer to an array of gss_oid_desc objects, each describing a single OID.  The application calls the gss_release_oid_set() routine to deallocate storage associated with the gss_OID_set values that the GSSAPI routines return to the application. 

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 DCE security 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:

MSB   LSB
+---------------------------------------------------+
| Calling Error | Routine Error | Supplementary Info|
+---------------------------------------------------+
Bit 31      24 23           16 15                 0

If a GSSAPI routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call 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:

Name	Field Value	Meaning
_	_	_
GSS_S_BAD_MECH	1	The required mechanism is unsupported.
_	_	_
GSS_S_NAME	2	The name passed is invalid.
_	_	_
GSS_S_NAMETYPE	3	The name passed is unsupported.
_	_	_
GSS_S_BAD_BINDINGS	4	The channel bindings are incorrect.
_	_	_
GSS_S_BAD_STATUS	5	A status value was invalid.
_	_	_
GSS_S_BAD_SIG	6	A token had an invalid signature.
_	_	_
GSS_S_NO_CRED	7	No credentials were 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 expired.
_	_	_
GSS_S_CONTEXT_EXPIRED	12	The context expired.
_	_	_
GSS_S_FAILURE	13	The routine failed.  Check minor status codes.
_	_	_

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

Name	Field Value	Meaning
_	_	_
Name	Value	Meaning
_	_	_
GSS_S_CALL_INACCESSIBLE _READ	1	Could not read a required input parameter.
_	_	_
GSS_S_CALL_INACCESSIBLE _WRITE	2	Could not write a required output parameter.
_	_	_
GSS_S_BAD_STRUCTURE	3	A parameter was incorrectly structured.
_	_	_

The following table lists the supplementary bits and their meanings. 

Name	Bit Number	Meaning
_	_	_
GSS_S_CONTINUE_NEEDED	0 (LSB)	Call the routine 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 expired; the routine cannot verify that the token is not a duplicate of an earlier token.
_	_	_
GSS_S_UNSEQ_TOKEN	3	A later token has been processed.
_	_	_

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 DCE security 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 the following three macros:

   •GSS_CALLING_ERROR()

   •GSS_ROUTINE_ERROR()

   •GSS_SUPPLEMENTARY_INFO()

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 routine 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 either DCE security or Kerberos.  The parameter can contain a single error, indicated by an OM_uint32 value.  The OM_uint32 data type is equivalent to the DCE data type error_status_t and can contain any DCE-defined error. 

Names

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

Names are represented in the following two forms:

   •A printable form, for presentation to an application

   •An internal, canonical form that is used by the API and is opaque to applications

The gss_import_name() and gss_display_name() routines convert names between their printable form and their gss_name_t data type.  GSSAPI supports only DCE principal names, which are identified by the constant OID, GSSCDE_C_OID_DCENAME. 

The gss_compare_names() 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:

typedef struct gss_channel_binding_struct {
OM_uint32       initiator_addrtype;
gss_buffer_desc initiator_address;
OM_uint32       acceptor_addrtype;
gss_buffer_desc aceptor_address;
gss_buffer_desc application_data;
} ∗gss_channel_bindings_t;

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

Unspecified
GSS_C_AF_UNSPEC

Host-localGSS_C_AF_LOCAL

DARPA Internet
GSS_C_AF_INET

ARPAnet IMP
GSS_C_AF_IMPLINK

pup protocols (for example, BSP)
GSS_C_AF_PUP

MIT CHAOS protocol
GSS_C_AF_CHAOS

XEROX NS
GSS_C_AF_NS

nbsGSS_C_AF_NBS

ECMAGSS_C_AF_ECMA

datakit protocols
GSS_C_AF_DATAKIT

CCITT protocols (for example, X.25)
GSS_C_AF_CCITT

IBM SNAGSS_C_AF_SNA

Digital DECnet
GSS_C_AF_DECnet

Direct data link interface
GSS_C_AF_DLI

LATGSS_C_AF_LAT

NSC Hyperchannel
GSS_C_AF_HYLINK

AppleTalkGSS_C_AF_APPLETALK

BISYNC 2780/3780
GSS_C_AF_BSC

Distributed system services
GSS_C_AF_DSS

OSI TP4GSS_C_AF_OSI

X25GSS_C_AF_X25

No address specified
GSS_C_AF_NULLADDR

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:

Convention	Value Default	Explanation
_	_	_
gss_buffer_t types	GSS_C_NO_BUFFER	For an input parameter, indicates no data is supplied.  For an output parameter, indicates that the information returned is not required by the application.
_	_	_
Integer types (input)		Refer to the reference pages for default values.
_	_	_
Integer types (output)	NULL	Indicates that the application does not require the information.
_	_	_
Pointer types (output)	NULL	Indicates that the application does not require the information.
_	_	_
OIDs	GSS_C_NULL_OID	Indicates the default choice for name type or security mechanism.
_	_	_
OID sets	GSS_C_NULL_OID_SET	Indicates the default set of security mechanisms, DCE security and Kerberos.
_	_	_
Credentials	GSS_C_NO_CREDENTIAL	Indicates that the application should use the default credential handle.
_	_	_
Channel bindings	GSS_C_NO_CHANNEL _BINDINGS	Indicates that no channel bindings are used.
_	_	_

Related Information

Books: OSF DCE Application Development Guide—Core Components.