gssapi(5) gssapi(5)
NAME [Toc] [Back]
gssapi - Generic Security Service Application Programming Interface
DESCRIPTION [Toc] [Back]
This introduction includes general information about the Generic
Security Service Application Programming Interface (GSSAPI) defined in
"Internet 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 [Toc] [Back]
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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 [Toc] [Back]
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 [Toc] [Back]
This section provides an overview of the GSSAPI data types and their
definitions.
Integer Types The GSSAPI defines the following integer data
type:
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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 multiplebyte
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:
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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 [Toc] [Back]
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.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
Contexts [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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:
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
Name Field Meaning
Value
________________________________________________________
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.
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:
Name Field Meaning
Value
_________________________________________________________
GSS_S_CALL_INACCESSIBLE_READ 1 Could not read a
required input
parameter.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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 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
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 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() [Toc] [Back]
GSS_ROUTINE_ERROR() [Toc] [Back]
GSS_SUPPLEMENTARY_INFO() [Toc] [Back]
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.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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:
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
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
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
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
in the token.
Optional Parameters [Toc] [Back]
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
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 [Toc] [Back]
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).
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
gssapi(5) gssapi(5)
The manpages for DCE-GSSAPI are included with the DCE-CoreTools
product. To see those manpages add /opt/dce/share/man to MANPATH.
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003 [ Back ] |
