Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > G

gssapi(5)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

gssapi — Generic Security Service Application Programming Interface

DESCRIPTION

This introduction includes general information about the Generic Security Service Application Programming Interface (GSSAPI) defined in RFC 2743, "Generic Security Service Application Programming Interface," and RFC 2744, "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 other similar data types 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 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:

  • Enable an application to authenticate another application's user.

  • Enable an application to delegate access rights to another application.

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

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 context initiator acquires a credential with which it can prove its identity to other processes. Similarly, the context acceptor acquires a credential to enable it to accept a security context. Either application may omit this credential acquisition and use their default credentials in subsequent stages. See the "Credentials" section in this manual page 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.

Security Context

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

  • 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.

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:

major status values

Major status values are generic API routine errors or calling errors defined in RFC 2744.

minor status values

Minor status values indicate mechanism-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_uint32 32-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 types

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 (for example Kerberos), and to specify name types. Select a security mechanism by using the corresponding OIDs:

For Kerberos Version 5, specify GSS_C_OID_KRBV5_DES.

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:

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_OID elements } 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 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:

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,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:

GSSAPI Routine Errors
 Field 
NameValueMeaning
GSS_S_BAD_MECH1The required mechanism is unsupported.
GSS_S_NAME2The name passed is invalid.
GSS_S_NAMETYPE3The name passed is unsupported.
GSS_S_BAD_BINDINGS4The channel bindings are incorrect.
GSS_S_BAD_STATUS5A status value was invalid.
GSS_S_BAD_SIG6A token had an invalid signature.
GSS_S_NO_CRED7No credentials were supplied.
GSS_S_NO_CONTEXT8No context has been established.
GSS_S_DEFECTIVE_TOKEN9A token was invalid.
GSS_S_DEFECTIVE_CREDENTIAL10A credential was invalid.
GSS_S_CREDENTIALS_EXPIRED11The referenced credentials expired.
GSS_S_CONTEXT_EXPIRED12The context expired.
GSS_S_FAILURE13The routine failed. Check minor status codes.
GSS_S_BAD_QOP14The quality of protection requested could not be provided.
GSS_S_UNAUTHORIZED15The operation is forbidded by local security policy.

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

Calling Errors
 Field 
NameValueMeaning
GSS_S_CALL_INACCESSIBLE_READ1Could not read a required input parameter.
GSS_S_CALL_INACCESSIBLE_WRITE2Could not write a required output parameter.
GSS_S_BAD_STRUCTURE3A parameter was incorrectly structured.

The following table lists the supplementary bits and their meanings.

Supplementary Information Status Bits
 Bit 
NameNumberMeaning
GSS_S_CONTINUE_NEEDED0 (LSB)Call the routine again to complete its function.
GSS_S_DUPLICATE_TOKEN1The token was a duplicate of an earlier token.
GSS_S_OLD_TOKEN2The token's validity period expired; the routine cannot verify that the token is not a duplicate of an earlier token.
GSS_S_UNSEQ_TOKEN3A 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 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:

  • 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 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:

  • A printable form, for presentation to an application.

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

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:

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 following table lists the address types and their addrtype values:

Address Typeaddrtype Value
UnspecifiedGSS_C_AF_UNSPEC
Host-localGSS_C_AF_LOCAL
DARPA InternetGSS_C_AF_INET
ARPAnet IMPGSS_C_AF_IMPLINK
pup protocols (for example, BSP)GSS_C_AF_PUP
MIT CHAOS protocolGSS_C_AF_CHAOS
XEROX NSGSS_C_AF_NS
nbsGSS_C_AF_NBS
ECMAGSS_C_AF_ECMA
datakit protocolsGSS_C_AF_DATAKIT
CCITT protocols (for example, X.25)GSS_C_AF_CCITT
IBM SNAGSS_C_AF_SNA
Digital DECnetGSS_C_AF_DECnet
Direct data link interfaceGSS_C_AF_DLI
LATGSS_C_AF_LAT
NSC HyperchannelGSS_C_AF_HYLINK
AppleTalkGSS_C_AF_APPLETALK
BISYNC 2780/3780GSS_C_AF_BSC
Distributed system servicesGSS_C_AF_DSS
OSI TP4GSS_C_AF_OSI
X25GSS_C_AF_X25
No address specifiedGSS_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:

ConventionValue DefaultExplanation
gss_buffer_t typesGSS_C_NO_BUFFERFor 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)NULLIndicates that the application does not require the information.
Pointer types (output)NULLIndicates that the application does not require the information.
OIDsGSS_C_NULL_OIDIndicates the default choice for name type or security mechanism.
OID setsGSS_C_NULL_OID_SETIndicates the default set of security mechanisms
CredentialsGSS_C_NO_CREDENTIALIndicates that the application should use the default credential handle.
Channel bindingsGSS_C_NO_CHANNEL_BINDINGSIndicates that no channel bindings are used.

SEE ALSO

gss_accept_sec_context(3), gss_compare_name(3), gss_display_name(3), gss_import_name(3), gss_init_sec_context(3), gss_release_buffer(3), gss_release_oid_set(3), libgss(4).

RFC 2743, RFC 2744.

The manpages for DCE-GSSAPI are included with the DCE-CoreTools product. To see those manpages add /opt/dce/share/man to MANPATH.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.