libgss(4)libgss(4)NAMElibgss - shared library for GSSAPI (Generic Security Service Applica‐
tion Programming Interface)
SYNOPSISDESCRIPTION
is a shared library which contains all the GSSAPIs as per the RFC 2743
and implemented as C-language interfaces as defined in the RFC 2744,
Generic Security Service API : C-bindings.
GSSAPI provides security services for applications independent of the
various underlying security mechanisms. The services include authenti‐
cation, integrity and/or confidentiality services. GSSAPI provides
secure communication between two peers with a data structure called a
security context. A GSSAPI caller is responsible for transfer of token
between peers. GSSAPI is independent of the underlying communication
protocols.
The application that establishes the secure connection is called the
context initiator or simply initiator. The application that accepts
the secure connection is the context acceptor or simply acceptor.
An application developer who uses GSSAPI C-binding interfaces can link
an application with The underlying security mechanism can be specified
at runtime in a configuration file called and the library will dynami‐
cally load the corresponding mechanism specific shared library (for
example, in the case of Kerberos), from the path specified in the con‐
figuration file.
The file has the following format:
first column contains the names of the backend security mechanism
which support GSSAPI.
second column contains the object identifier (OID).
third column contains the name of the shared library which imple‐
ments the backend security mechanism for GSSAPI. (The
backend library has to be placed in path for 32bit and
path for 64bit versions)
The default path of the mechanism file can be changed by environment
variable.
# Mechanism Name Object Identifier Shared Library
#
krb5_mech 1.2.840.113554.1.2.2 libgssapi_krb5.sl
Besides this configuration file, there are two other configuration
files and which can be used in association with
The file contains information about the GSSAPI-based quality of protec‐
tion (QOP) for each underlying security mechanisms. The file has the
following format:
first column specifies the string name of QOP.
second column contains its QOP value (32-bit integer).
third column contains names of the security mechanism.
# QOP string QOP Value Mechanism Name
#
GSS_KRB5_INTEG_C_QOP_DES_MD5 0 kerberos_v5
The is a configuration file that selects the underlying mechanism used
to store the table. The table is used to store the mapping between a
security principal and the UNIX uid. The supported backend mechanism is
only flat files. Therefore, the entry "files" must be specified in for
the successful operation of the library.
# gsscred configuration file
#
# Valid gsscred backend mechanisms are:
# files
#
files
Using the GSSAPI framework
Applications communicating using the GSSAPI framework go through the
following main stages:
1. The communicating applications acquire a set of credentials to
prove their identity to other applications. The applications'
credentials vouch for their global identities.
2. The applications establish a joint security context using their
credentials. This information is used to provide per message
security services like integrity and confidentiality.
Establishing the security context is done as follows. One
application (client) initiates the context setup. The other
application (server) accepts it after exchanging zero or more
number of tokens. The number of exchanges depends upon the
underlying security mechanism.
3. Per message services apply confidentiality and integrity. An
application transmitting a message that it wishes to protect
will call the GSSAPI routine (gss_get_mic or gss_wrap calls) to
apply protection. The transmitting application specifies the
appropriate security context and sends this to the receiving
application. The receiver will pass the data to the correspond‐
ing decoding routine (gss_verify_mic or gss_unwrap calls ) to
respectively remove the protection and validate the data.
4. At the completion of a communication session, the peer applica‐
tions call GSSAPI routines to delete the security context.
The names of the APIs implemented in the library and a very
brief description for each of them are given below. For details
about using these APIs, refer to the respective man pages.
Credential Manipulation APIs
Credentials are used to prove the identity of an application to another
application. GSSAPIs assume that credentials of the applications are
already in place. The following GSSAPIs are used to inquire and manipu‐
late them.
Allows an application to acquire a handle for a pre-existing credential
by name.
Informs GSSAPI that the specified credential is no longer required by
the process. When all the processes have released a credential, it
will be deleted.
Obtain information about a credential.
Obtain per mechanism information about a credential.
Construct credentials by adding incrementally.
Context Manipulation APIs
For the applications to establish a joint security context and use it
for security services the following GSSAPIs are required.
Initiate a security context with a peer application.
Accept a security context initiated by a peer application.
Discard a security context (release the memory of the context struc‐
ture).
Obtain information about a security context.
Process a token from a peer application.
Transfer a security context to another process.
Import a transferred context.
Determine for how long a context will remain valid.
Determine token size limit for on a context.
Per Message Operation APIs
To perform per message operations like data integrity and data privacy
services the following GSSAPIs could be used:
To calculate a cryptographic Message Integrity Code (MIC) for a mes‐
sage (Integrity Service).
To verify message integrity.
To encrypt a message for Confidentiality Service.
To decrypt a message for Confidentiality Service.
Name Manipulation APIs
Names identify principals. Names are represented in printable form (for
presentation to an application) or in internal for (canonical form)
that is used by the API and is opaque to applications. The following
are the APIs that are used manipulate the names:
Convert a contiguous string name to a internal form.
Convert a internal form name to a text.
Compare two internal form names.
Discard an internal form name.
List the name types supported by a specific mechanism.
List mechanisms that support the specified name type.
Convert an internal name to a mechanism specific Mechanism Name (MN).
Convert an MN to flat name representation suitable for bitwise compari‐
son.
Create a copy of an internal name.
Miscellaneous Operation APIs
Besides the above mentioned category of APIs, there are APIs which are
used for miscellaneous operations like creating and deleting list of
mechanism OIDs, display the GSSAPI error status codes in text format,
releasing the memory for the buffer etc. as given below: as
Add object identifier to a set of OIDs.
Release the memory of a set of OID's.
Create an OID set with no OID's.
Determine whether an OID is a member of a set.
Release the memory of a buffer.
Release the memory of an OID structure.
Release the memory of a nametype.
Convert GSSAPI status code to text.
Determine available underlying security mechanisms.
AUTHOR
was developed by Sun Microsystems, Inc.
SEE ALSOgssapi(5).
The manpages for DCE-GSSAPI are included with the DCE-CoreTools prod‐
uct. To see those manpages add to
libgss(4)
