hpux gssapi man page on unix.com

gssapi(5) File Formats Manual gssapi(5)

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 com-
munications. 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 accep-
tor 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:

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

The 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 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 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 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 routine, which generates a delegated credential. The context acceptor can use the creden-
tial 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

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 structure) to 0 (zero).

Minor status values usually contain more detailed information about the error. They are not, however, portable between GSSAPI implementa-
tions. 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:

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 data type, which is a pointer to the buffer descriptor to pass the data
between the GSSAPI routines and applications.

The data type has the following structure:

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 data type, the GSSAPI routine allocates storage for any data it passes to the application. The calling
application must allocate the object. It can initialize unused objects with the value To free the storage, the appli-
cation calls the routine.

Object Identifier Applications use the 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

helps to ensure the portability of the application.

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

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 data type. The length field contains the number of bytes in the value.

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

Object Identifier Sets
The data type represents one or more object identifiers. The values of the data type are used to:

Report the available mechanisms supported by GSSAPI.

Request specific mechanisms.

Indicate which mechanisms a credential supports.

The data type has the following structure:

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

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

The 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 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 data type as tokens to GSSAPI routines.

Major Status Values
GSSAPI routines return GSS status codes as their 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 informa-
tion 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:

GSSAPI Routine Errors

Name Field Meaning
Value
--------------------------------------------------------------------------
GSS_S_BAD_MECH 1 The required mechanism is unsup-
ported.

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.
GSS_S_BAD_QOP 14 The quality of protection requested
could not be provided.
GSS_S_UNAUTHORIZED 15 The operation is forbidded by local
security policy.

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

Calling Errors

Name Field Meaning
Value
-----------------------------------------------------------------------------
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 struc-
tured.

The following table lists the supplementary bits and their meanings.

Supplementary Information Status Bits

Name Bit Meaning
Number
-----------------------------------------------------------------------
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 ear-
lier 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 ear-
lier token.
GSS_S_UNSEQ_TOKEN 3 A later token has been processed.

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

The major status code 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 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, lets you determine whether the status code indicated a calling or routine error. If the status code indicated a call-
ing 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 or 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 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 and routines convert names between their printable form and their type.

The 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. Chan-
nel bindings are communicated to the GSSAPI by using the following structure:

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

Address Type addrtype Value
---------------------------------------------------------
Unspecified GSS_C_AF_UNSPEC
Host-local GSS_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
nbs GSS_C_AF_NBS
ECMA GSS_C_AF_ECMA
datakit protocols GSS_C_AF_DATAKIT
CCITT protocols (for example, X.25) GSS_C_AF_CCITT
IBM SNA GSS_C_AF_SNA
Digital DECnet GSS_C_AF_DECnet
Direct data link interface GSS_C_AF_DLI
LAT GSS_C_AF_LAT
NSC Hyperchannel GSS_C_AF_HYLINK
AppleTalk GSS_C_AF_APPLETALK
BISYNC 2780/3780 GSS_C_AF_BSC
Distributed system services GSS_C_AF_DSS
OSI TP4 GSS_C_AF_OSI
X25 GSS_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
and the 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 and The security mechanism signs the octet string and binds the signa-
ture to the token generated by the routine. The context acceptor presents the same bindings to the routine, which evaluates the signature
and compares it to the signature in the token. If the signatures differ, the routine returns a error, and the context is not established.

Some security mechanisms check that the field of the channel bindings presented to the routine contains the correct network address of the
host system. Therefore portable applications should use either the correct address type and value or the for the address field. Some
security mechanisms include the channel binding data in the token instead of a signature, so portable applications should not use confiden-
tial 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 parame-
ter. 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 infor-
mation 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 secu-
rity mechanisms
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.

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 to

gssapi(5)

hpux man page for gssapi