gssapi(5)gssapi(5)NAMEgssapi - Generic Security Service Application Programming Interface
DESCRIPTION
This introduction includes general information about the Generic Secu‐
rity 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 communi‐
cations. 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 applica‐
tions. 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 acquisi‐
tion 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 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 rou‐
tine to get a token. The token is cryptographically protected, opaque
data. The context initiator transfers the token to the context accep‐
tor, 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 initia‐
tor 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 dele‐
gated credential. The context acceptor can use the credential to ini‐
tiate additional security contexts. The applications can exchange pro‐
tected 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 implementations.
When designing portable applications, use major status values for han‐
dling 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 allo‐
cates storage for any data it passes to the appli‐
cation. The calling application must allocate the
object. It can initialize unused objects with the
value To free the storage, the application 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 deallo‐
cate them.
Object Identifier Sets
The data type represents one or more object identi‐
fiers. The values of the data type are used to:
Report the available mechanisms supported by GSS‐
API.
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 creden‐
tial data structure.
Contexts
The security context is a pair of GSSAPI data structures that contain
information shared between the communicating applications. The infor‐
mation 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 applica‐
tions 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 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 con‐
tain 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 mecha‐
nism 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 bind‐
ings 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 cre‐
dentials 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 pro‐
tection requested
could not be pro‐
vided.
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
earlier token.
GSS_S_OLD_TOKEN 2 The token's valid‐
ity 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 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 sec‐
tion 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 indi‐
cated 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 gen‐
erate 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 con‐
text with the communications channel that carries the context. Channel
bindings are communicated to the GSSAPI by using the following struc‐
ture:
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 signature
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 confi‐
dential 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 param‐
eter, indicates no
data is supplied.
For an output
parameter, indi‐
cates that the
information
returned is not
required by the
application.
Integer types (input) Refer to the refer‐
ence 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 secu‐
rity 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 ALSOgss_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 prod‐
uct. To see those manpages add to
gssapi(5)