Copyright © 2003 Simon Josefsson.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License."(a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."
GSS is an implementation of the Generic Security Service Application Program Interface (GSS-API). GSS-API is used by network servers (e.g., IMAP, SMTP) to provide security security services, e.g., authenticate clients against servers. GSS consists of a library and a manual.
GSS is developed for the GNU/Linux system, but runs on over 20 platforms including most major Unix platforms and Windows, and many kind of devices including iPAQ handhelds and S/390 mainframes.
GSS is licensed under the GNU Public License.
This manual documents the GSS programming interface. All functions and data types provided by the library are explained.
The reader is assumed to possess basic familiarity with GSS-API and network programming in C or C++.
This manual can be used in several ways. If read from the beginning to the end, it gives a good introduction into the library and how it can be used in an application. Forward references are included where necessary. Later on, the manual can be used as a reference manual to get just the information needed about any particular interface of the library. Experienced programmers might want to start looking at the examples at the end of the manual, and then only read up those parts of the interface which are unclear.
GSS might have a couple of advantages over other libraries doing a similar job.
GSS has at some point in time been tested on the following platforms.
GCC 2.95.4 and GNU Make. This is the main development platform.
alphaev67-unknown-linux-gnu, alphaev6-unknown-linux-gnu,
arm-unknown-linux-gnu, hppa-unknown-linux-gnu,
hppa64-unknown-linux-gnu, i686-pc-linux-gnu,
ia64-unknown-linux-gnu, m68k-unknown-linux-gnu,
mips-unknown-linux-gnu, mipsel-unknown-linux-gnu,
powerpc-unknown-linux-gnu, s390-ibm-linux-gnu,
sparc-unknown-linux-gnu.
GCC 2.95.1 and GNU Make. armv4l-unknown-linux-gnu.
Tru64 UNIX C compiler and Tru64 Make. alphaev67-dec-osf5.1,
alphaev68-dec-osf5.1.
GCC 2.96 and GNU Make. alphaev6-unknown-linux-gnu,
alphaev67-unknown-linux-gnu.
GCC 3.0 and GNU Make. ia64-unknown-linux-gnu.
GCC 2.96 and GNU Make. alphaev6-unknown-linux-gnu,
alphaev67-unknown-linux-gnu, ia64-unknown-linux-gnu.
GCC 3.2 and GNU Make. i686-pc-linux-gnu.
GCC 2.96 and GNU Make. i686-pc-linux-gnu.
GCC 2.95.3 and GNU Make. i686-pc-linux-gnu.
GCC 3.2 and GNU Make. i686-pc-linux-gnu.
MIPS C compiler, IRIX Make. mips-sgi-irix6.5.
IBM C for AIX compiler, AIX Make. rs6000-ibm-aix4.3.2.0.
GCC 3.2, GNU make. i686-pc-cygwin.
HP-UX C compiler and HP Make. ia64-hp-hpux11.22,
hppa2.0w-hp-hpux11.11.
Sun WorkShop Compiler C 6.0 and SUN Make. sparc-sun-solaris2.8.
GCC 2.95.3 and GNU Make. alpha-unknown-netbsd1.6,
i386-unknown-netbsdelf1.6.
GCC 2.95.3 and GNU Make. alpha-unknown-openbsd3.1,
i386-unknown-openbsd3.1.
GCC 2.95.4 and GNU Make. alpha-unknown-freebsd4.7,
i386-unknown-freebsd4.7.
If you use GSS on, or port GSS to, a new platform please report it to the author.
If you think you have found a bug in GSS, please investigate it and report it.
Please make an effort to produce a self-contained report, with something definite that can be tested or debugged. Vague queries or piecemeal messages are difficult to act on and don't help the development effort.
If your bug report is good, we will do our best to help you to get a corrected version of the software; if the bug report is poor, we won't do anything about it (apart from asking you to send better bug reports).
If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please also send a note.
Send your bug report to:
bug-gss@josefsson.orgTo use GSS, you have to perform some changes to your sources and the build system. The necessary changes are small and explained in the following sections. At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.
A faster way to find out how to adapt your application for use with GSS may be to look at the examples at the end of this manual.
All standard interfaces (data types and functions) of the official GSS API are defined in the header file `gss/api.h'. The file is taken verbatim from the RFC (after correcting a few typos) where it is known as gssapi.h. However, to be able to co-exist gracefully with other GSS-API implementation, the name gssapi.h was changed.
The header file `gss.h' contains a few non-standard extensions, C++ namespace fixes, and takes care of including header files related to all supported mechanisms (e.g., gss/krb5.h). Therefore, including `gss.h' in your project is recommended over `gss/api.h'. If using `gss.h' instead of `gss/api.h' causes problems, it should be regarded a bug.
You must include either file in all programs using the library, either directly or through some other header file, like this:
#include <gss.h>
The name space of GSS is gss_* for function names, gss_*
for data types and GSS_* for other symbols. In addition the
same name prefixes with one prepended underscore are reserved for
internal use and should never be used by an application.
Each supported GSS mechanism may want to expose mechanism specific functionality, and can do so through one or more header files under the `gss/' directory. The Kerberos 5 mechanism uses the file `gss/krb5.h', but again, it is included (with C++ namespace fixes) from `gss.h'.
GSS does not need to be initialized before it can be used.
It is often desirable to check that the version of GSS used is indeed
one which fits all requirements. Even with binary compatibility new
features may have been introduced but due to problem with the dynamic
linker an old version is actually used. So you may want to check that
the version is okay right after program startup. The function is
called gss_check_version() and is described in See Extended GSS API.
The normal way to use the function is to put something similar to the
following early in your main():
#include <gss.h>
...
if (!gss_check_version (GSS_VERSION))
{
printf ("gss_check_version() failed:\n"
"Header file incompatible with shared library.\n");
exit(1);
}
If you want to compile a source file that includes the `gss.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy. This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the -I option).
However, the path to the include file is determined at the time the
source is configured. To solve this problem, GSS uses the external
package pkg-config that knows the path to the include file
and other configuration options. The options that need to be added to
the compiler invocation at compile time are output by the
--cflags option to pkg-config gss. The following
example shows how it can be used at the command line:
gcc -c foo.c `pkg-config gss --cflags`
Adding the output of pkg-config gss --cflags to the compilers
command line will ensure that the compiler can find the `gss.h' header
file.
A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files. For this to work,
the path to the library files has to be added to the library search
path (via the -L option). For this, the option
--libs to pkg-config gss can be used. For
convenience, this option also outputs all other options that are
required to link the program with the GSS libarary (for instance, the
-lshishi option). The example shows how to link foo.o
with GSS into a program foo.
gcc -o foo foo.o `pkg-config gss --libs`
Of course you can also combine both examples to a single command by
specifying both options to pkg-config:
gcc -o foo foo.c `pkg-config gss --cflags --libs`
As an alternative to the native Shishi programming API, it is possible to program Shishi through the Generic Security Services (GSS) API. The advantage of using GSS-API in your security application, instead of the native Shishi API, is that it will be easier to port your application between different Kerberos 5 implementations, and even beyond Kerberos 5 to different security systems, that support GSS-API.
In the free software world, however, the only widely used security system that supports GSS-API is Kerberos 5, so this advantage is somewhat academic. But if you are porting applications using GSS-API for other Kerberos 5 implementations, or want a more mature and stable API than the native Shishi API, you may find using Shishi's GSS-API interface compelling. Note that GSS-API only offer basic services, for more advanced uses you must use the native API.
The remaining part of this section assume you are familiar with
GSS-API in general, and only describe how to hook up your application
written using GSS-API with Shishi. For general GSS-API information,
and some programming examples, a good guide is available online at
<http://docs.sun.com/db/doc/816-1331>.
Shishi exposes the GSS-API through the standard `gssapi.h' header file and the library `libshishi-gss'. To avoid conflicting with other GSS-API implementations on your system, the header file is installed in a sub-directory `shishi/' under the header file location specified when building Shishi. You must include this in all programs using the library, either directly or through some other header file, like this:
#include <gss.h>
The library `libshishi-gss' is installed in the normal object code library location.
To facilitate finding the proper parameters for your compiler, the
pkg-config tool can be used. Compile your application
foo.c with the Shishi GSS interface like this:
gcc -o foo foo.c `pkg-config shishi-gss --cflags --libs`
Of course you do not need to use both --cflags and
--libs at the same time, see the full discussion elsewhere in
this manual (see Building the source), but note that you must use
`shishi-gss' instead of `shishi' as the library parameter to
pkg-config.
Table 2-1 GSS-API Credential-management Routines
Routine Section Function
------- ------- --------
gss_acquire_cred 5.2 Assume a global identity; Obtain
a GSS-API credential handle for
pre-existing credentials.
gss_add_cred 5.3 Construct credentials
incrementally
gss_inquire_cred 5.21 Obtain information about a
credential
gss_inquire_cred_by_mech 5.22 Obtain per-mechanism information
about a credential.
gss_release_cred 5.27 Discard a credential handle.
| OM_uint32 gss_release_cred (OM_uint32 * minor_status, gss_cred_id_t * cred_handle) | Function |
|
minor_status: Mechanism specific status code. cred_handle: Optional opaque handle identifying credential to be released. If GSS_C_NO_CREDENTIAL is supplied, the routine will complete successfully, but will do nothing. Informs GSS-API that the specified credential handle is no longer required by the application, and frees associated resources. Implementations are encouraged to set the cred_handle to GSS_C_NO_CREDENTIAL on successful completion of this call. Returns GSS_S_COMPLETE for successful completion, and GSS_S_NO_CRED for credentials could not be accessed. |
Table 2-2 GSS-API Context-Level Routines
Routine Section Function
------- ------- --------
gss_init_sec_context 5.19 Initiate a security context with
a peer application
gss_accept_sec_context 5.1 Accept a security context
initiated by a
peer application
gss_delete_sec_context 5.9 Discard a security context
gss_process_context_token 5.25 Process a token on a security
context from a peer application
gss_context_time 5.7 Determine for how long a context
will remain valid
gss_inquire_context 5.20 Obtain information about a
security context
gss_wrap_size_limit 5.34 Determine token-size limit for
gss_wrap on a context
gss_export_sec_context 5.14 Transfer a security context to
another process
gss_import_sec_context 5.17 Import a transferred context
| OM_uint32 gss_init_sec_context (OM_uint32 * minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t * context_handle, const gss_name_t target_name, const gss_OID mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID * actual_mech_type, gss_buffer_t output_token, OM_uint32 * ret_flags, OM_uint32 * time_rec) | Function |
|
minor_status: Mechanism specific status code. initiator_cred_handle: Optional handle for credentials claimed. Supply GSS_C_NO_CREDENTIAL to act as a default initiator principal. If no default initiator is defined, the function will return GSS_S_NO_CRED. context_handle: Context handle for new context. Supply
GSS_C_NO_CONTEXT for first call; use value returned by first call
in continuation calls. Resources associated with this
context-handle must be released by the application after use with a
call to target_name: Name of target. mech_type: Optional object ID of desired mechanism. Supply GSS_C_NO_OID to obtain an implementation specific default req_flags: Contains various independent flags, each of which requests that the context support a specific service option. Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically-ORed together to form the bit-mask value. See below for details. time_req: Optional Desired number of seconds for which context should remain valid. Supply 0 to request a default validity period. input_chan_bindings: Optional Application-specified bindings. Allows application to securely bind channel identification information to the security context. Specify GSS_C_NO_CHANNEL_BINDINGS if channel bindings are not used. input_token: Optional (see text) Token received from peer application. Supply GSS_C_NO_BUFFER, or a pointer to a buffer containing the value GSS_C_EMPTY_BUFFER on initial call. actual_mech_type: Optional actual mechanism used. The OID returned via this parameter will be a pointer to static storage that should be treated as read-only; In particular the application should not attempt to free it. Specify NULL if not required. output_token: Token to be sent to peer application. If the length
field of the returned buffer is zero, no token need be sent to the
peer application. Storage associated with this buffer must be
freed by the application after use with a call to
ret_flags: Optional various independent flags, each of which indicates that the context supports a specific service option. Specify NULL if not required. Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically-ANDed with the ret_flags value to test whether a given option is supported by the context. See below for details. time_rec: Optional number of seconds for which the context will remain valid. If the implementation does not support context expiration, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required. Initiates the establishment of a security context between the application and a remote peer. Initially, the input_token parameter should be specified either as GSS_C_NO_BUFFER, or as a pointer to a gss_buffer_desc object whose length field contains the value zero. The routine may return a output_token which should be transferred to the peer application, where the peer application will present it to gss_accept_sec_context. If no token need be sent, gss_init_sec_context will indicate this by setting the length field of the output_token argument to zero. To complete the context establishment, one or more reply tokens may be required from the peer application; if so, gss_init_sec_context will return a status containing the supplementary information bit GSS_S_CONTINUE_NEEDED. In this case, gss_init_sec_context should be called again when the reply token is received from the peer application, passing the reply token to gss_init_sec_context via the input_token parameters. Portable applications should be constructed to use the token length and return status to determine whether a token needs to be sent or waited for. Thus a typical portable caller should always invoke int context_established = 0; gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; ... input_token->length = 0; while (!context_established) {
maj_stat = gss_init_sec_context( if (output_token->length != 0) {
send_token_to_peer(output_token);
gss_release_buffer( if (context_hdl != GSS_C_NO_CONTEXT)
gss_delete_sec_context( if (maj_stat & GSS_S_CONTINUE_NEEDED) { receive_token_from_peer(input_token); } else { context_established = 1; }; }; Whenever the routine returns a major status that includes the value GSS_S_CONTINUE_NEEDED, the context is not fully established and the The value returned via the time_rec parameter is undefined Unless the accompanying ret_flags parameter contains the bit GSS_C_PROT_READY_FLAG, indicating that per-message services may be applied in advance of a successful completion status, the value returned via the actual_mech_type parameter is undefined until the routine returns a major status value of GSS_S_COMPLETE. The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the ret_flags parameter should contain the values that the implementation expects would be valid if context establishment were to succeed. In particular, if the application has requested a service such as delegation or anonymous authentication via the req_flags argument, and such a service is unavailable from the underlying mechanism, gss_init_sec_context should generate a token that will not provide the service, and indicate via the ret_flags argument that the service will not be supported. The application may choose to abort the context establishment by calling gss_delete_sec_context (if it cannot continue in the absence of the service), or it may choose to transmit the token and continue context establishment (if the service was merely desired but not mandatory). The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits within ret_flags should indicate the actual state at the time gss_init_sec_context returns, whether or not the context is fully established. GSS-API implementations that support per-message protection are encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE status code). However, applications should not rely on this behavior as the flag was not defined in Version 1 of the GSS-API. Instead, applications should determine what per-message services are available after a successful context establishment according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. All other bits within the ret_flags argument should be set to zero. If the initial call of During context establishment, the informational status bits GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and GSS-API mechanisms should always return them in association with a routine error of GSS_S_FAILURE. This requirement for pairing did not exist in version 1 of the GSS-API specification, so applications that wish to run over version 1 implementations must special-case these codes. GSS_C_DELEG_FLAG True - Delegate credentials to remote peer False - Don't delegate GSS_C_MUTUAL_FLAG True - Request that remote peer authenticate itself False - Authenticate self to remote peer only GSS_C_REPLAY_FLAG True - Enable replay detection for messages protected with gss_wrap or gss_get_mic False - Don't attempt to detect replayed messages GSS_C_SEQUENCE_FLAG True - Enable detection of out-of-sequence protected messages False - Don't attempt to detect out-of-sequence messages GSS_C_CONF_FLAG True - Request that confidentiality service be made available (via gss_wrap) False - No per-message confidentiality service is required. GSS_C_INTEG_FLAG True - Request that integrity service be made available (via gss_wrap or gss_get_mic) False - No per-message integrity service is required. GSS_C_ANON_FLAG True - Do not reveal the initiator's identity to the acceptor. False - Authenticate normally. GSS_C_DELEG_FLAG True - Credentials were delegated to the remote peer False - No credentials were delegated GSS_C_MUTUAL_FLAG True - The remote peer has authenticated itself. False - Remote peer has not authenticated itself. GSS_C_REPLAY_FLAG True - replay of protected messages will be detected False - replayed messages will not be detected GSS_C_SEQUENCE_FLAG True - out-of-sequence protected messages will be detected False - out-of-sequence messages will not be detected GSS_C_CONF_FLAG True - Confidentiality service may be invoked by calling gss_wrap routine False - No confidentiality service (via gss_wrap) available. gss_wrap will provide message encapsulation, data-origin authentication and integrity services only. GSS_C_INTEG_FLAG True - Integrity service may be invoked by calling either gss_get_mic or gss_wrap routines. False - Per-message integrity service unavailable. GSS_C_ANON_FLAG True - The initiator's identity has not been revealed, and will not be revealed if any emitted token is passed to the acceptor. False - The initiator's identity has been or will be authenticated normally. GSS_C_PROT_READY_FLAG True - Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use if the accompanying major status return value is either GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED. False - Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the accompanying major status return value is GSS_S_COMPLETE. GSS_C_TRANS_FLAG
True - The resultant security context may be transferred to other
processes via a call to All other bits should be set to zero. Returns: GSS_S_COMPLETE Successful completion GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application is required to complete the context, and that gss_init_sec_context must be called again with that token. GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the input_token failed GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed on the credential failed. GSS_S_NO_CRED The supplied credentials were not valid for context initiation, or the credential handle did not reference any credentials. GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired GSS_S_BAD_BINDINGS The input_token contains different channel bindings to those specified via the input_chan_bindings parameter GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that could not be verified GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error during context establishment GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a token already processed. This is a fatal error during context establishment. GSS_S_NO_CONTEXT Indicates that the supplied context handle did not refer to a valid context GSS_S_BAD_NAMETYPE The provided target_name parameter contained an invalid or unsupported type of name GSS_S_BAD_NAME The provided target_name parameter was ill-formed. GSS_S_BAD_MECH The specified mechanism is not supported by the provided credential, or is unrecognized by the implementation. |
| OM_uint32 gss_delete_sec_context (OM_uint32 * minor_status, gss_ctx_id_t * context_handle, gss_buffer_t output_token) | Function |
|
minor_status: Mechanism specific status code. context_handle: Context handle identifying context to delete. After deleting the context, the GSS-API will set this context handle to GSS_C_NO_CONTEXT. output_token: Optional token to be sent to remote application to instruct it to also delete the context. It is recommended that applications specify GSS_C_NO_BUFFER for this parameter, requesting local deletion only. If a buffer parameter is provided by the application, the mechanism may return a token in it; mechanisms that implement only local deletion should set the length field of this token to zero to indicate to the application that no token is to be sent to the peer. Delete a security context. In addition to deleting established security contexts,
The output_token parameter is retained for compatibility with
version 1 of the GSS-API. It is recommended that both peer
applications invoke Returns GSS_S_COMPLETE for successful completion, and GSS_S_NO_CONTEXT if no valid context was supplied. |
Table 2-3 GSS-API Per-message Routines
Routine Section Function
------- ------- --------
gss_get_mic 5.15 Calculate a cryptographic message
integrity code (MIC) for a
message; integrity service
gss_verify_mic 5.32 Check a MIC against a message;
verify integrity of a received
message
gss_wrap 5.33 Attach a MIC to a message, and
optionally encrypt the message
content;
confidentiality service
gss_unwrap 5.31 Verify a message with attached
MIC, and decrypt message content
if necessary.
| OM_uint32 gss_wrap (OM_uint32 * minor_status, const gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int * conf_state, gss_buffer_t output_message_buffer) | Function |
|
minor_status: Mechanism specific status code. context_handle: Identifies the context on which the message will be sent conf_req_flag: Whether confidentiality is requested. qop_req: Specifies required quality of protection. A mechanism-specific default may be requested by setting qop_req to GSS_C_QOP_DEFAULT. If an unsupported protection strength is requested, gss_wrap will return a major_status of GSS_S_BAD_QOP. input_message_buffer: Message to be protected. conf_state: Optional output variable indicating if confidentiality services have been applied. output_message_buffer: Buffer to receive protected message.
Storage associated with this message must be freed by the
application after use with a call to Attaches a cryptographic MIC and optionally encrypts the specified input_message. The output_message contains both the MIC and the message. The qop_req parameter allows a choice between several cryptographic algorithms, if supported by the chosen mechanism. Since some application-level protocols may wish to use tokens
emitted by Returns GSS_S_COMPLETE Successful completion GSS_S_CONTEXT_EXPIRED The context has already expired GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid context GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. |
| OM_uint32 gss_unwrap (OM_uint32 * minor_status, const gss_ctx_id_t context_handle, const gss_buffer_t input_message_buffer, gss_buffer_t output_message_buffer, int * conf_state, gss_qop_t * qop_state) | Function |
|
minor_status: Mechanism specific status code. context_handle: Identifies the context on which the message arrived input_message_buffer: input protected message output_message_buffer: Buffer to receive unwrapped message.
Storage associated with this buffer must be freed by the
application after use use with a call to conf_state: optional output variable indicating if confidentiality protection was used. qop_state: optional output variable indicating quality of protection. Converts a message previously protected by gss_wrap back to a usable form, verifying the embedded MIC. The conf_state parameter indicates whether the message was encrypted; the qop_state parameter indicates the strength of protection that was used to provide the confidentiality and integrity services. Since some application-level protocols may wish to use tokens
emitted by Returns: GSS_S_COMPLETE Successful completion GSS_S_DEFECTIVE_TOKEN The token failed consistency checks GSS_S_BAD_SIG The MIC was incorrect GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC for the message, but it had already been processed GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for the message, but it is too old to check for duplication. GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for the message, but has been verified out of sequence; a later token has already been received. GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for the message, but has been verified out of sequence; an earlier expected token has not yet been received. GSS_S_CONTEXT_EXPIRED The context has already expired GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid context |
Table 2-4 GSS-API Name manipulation Routines
Routine Section Function
------- ------- --------
gss_import_name 5.16 Convert a contiguous string name
to internal-form
gss_display_name 5.10 Convert internal-form name to
text
gss_compare_name 5.6 Compare two internal-form names
gss_release_name 5.28 Discard an internal-form name
gss_inquire_names_for_mech 5.24 List the name-types supported by
the specified mechanism
gss_inquire_mechs_for_name 5.23 List mechanisms that support the
specified name-type
gss_canonicalize_name 5.5 Convert an internal name to an MN
gss_export_name 5.13 Convert an MN to export form
gss_duplicate_name 5.12 Create a copy of an internal name
| OM_uint32 gss_import_name (OM_uint32 * minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t * output_name) | Function |
|
minor_status: Mechanism specific status code input_name_buffer: buffer containing contiguous string name to convert input_name_type: Optional Object ID specifying type of printable name. Applications may specify either GSS_C_NO_OID to use a mechanism-specific default printable syntax, or an OID recognized by the GSS-API implementation to name a specific namespace. output_name: returned name in internal form. Storage associated
with this name must be freed by the application after use with a call
to Convert a contiguous string name to internal form. In general, the internal name returned (via the <output_name> parameter) will not be an MN; the exception to this is if the <input_name_type> indicates that the contiguous string provided via the <input_name_buffer> parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will be an MN for the mechanism that exported the name. Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_NAMETYPE when the input_name_type was unrecognized, GSS_S_BAD_NAME when the input_name parameter could not be interpreted as a name of the specified type, and GSS_S_BAD_MECH when the input name-type was GSS_C_NT_EXPORT_NAME, but the mechanism contained within the input-name is not supported. |
| OM_uint32 gss_display_name (OM_uint32 * minor_status, const gss_name_t input_name, gss_buffer_t output_name_buffer, gss_OID * output_name_type) | Function |
|
minor_status: Mechanism specific status code. input_name: Name to be displayed output_name_buffer: Buffer to receive textual name string. The
application must free storage associated with this name after use
with a call to output_name_type: Optional type of the returned name. The returned gss_OID will be a pointer into static storage, and should be treated as read-only by the caller (in particular, the application should not attempt to free it). Specify NULL if not required. Allows an application to obtain a textual representation of an opaque internal-form name for display purposes. The syntax of a printable name is defined by the GSS-API implementation. If input_name denotes an anonymous principal, the implementation should return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and a textual name that is syntactically distinct from all valid supported printable names in output_name_buffer. If input_name was created by a call to gss_import_name, specifying GSS_C_NO_OID as the name-type, implementations that employ lazy conversion between name types may return GSS_C_NO_OID via the output_name_type parameter. Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_NAME when input_name was ill-formed. |
| OM_uint32 gss_compare_name (OM_uint32 * minor_status, const gss_name_t name1, const gss_name_t name2, int * name_equal) | Function |
|
minor_status: Mechanism specific status code. name1: Internal-form name. name2: Internal-form name. name_equal: non-zero if names refer to same entity. Allows an application to compare two internal-form names to determine whether they refer to the same entity. If either name presented to gss_compare_name denotes an anonymous principal, the routines should indicate that the two names do not refer to the same identity. Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_NAMETYPE when the two names were of incomparable types, and GSS_S_BAD_NAME if one or both of name1 or name2 was ill-formed. |
| OM_uint32 gss_release_name (OM_uint32 * minor_status, gss_name_t * name) | Function |
|
minor_status: Mechanism specific status code. name: The name to be deleted. Free GSSAPI-allocated storage associated with an internal-form name. Implementations are encouraged to set the name to GSS_C_NO_NAME on successful completion of this call. Returns GSS_S_COMPLETE for successful completion, and GSS_S_BAD_NAME when the name parameter did not contain a valid name. |
| OM_uint32 gss_canonicalize_name (OM_uint32 * minor_status, const gss_name_t input_name, const gss_OID mech_type, gss_name_t * output_name) | Function |
|
minor_status: Mechanism specific status code. input_name: The name for which a canonical form is desired. mech_type: The authentication mechanism for which the canonical form of the name is desired. The desired mechanism must be specified explicitly; no default is provided. output_name: The resultant canonical name. Storage associated
with this name must be freed by the application after use with a
call to Generate a canonical mechanism name (MN) from an arbitrary internal name. The mechanism name is the name that would be returned to a context acceptor on successful authentication of a context where the initiator used the input_name in a successful call to gss_acquire_cred, specifying an OID set containing <mech_type> as its only member, followed by a call to gss_init_sec_context, specifying <mech_type> as the authentication mechanism. Returns GSS_S_COMPLETE Successful completion. GSS_S_BAD_MECH The identified mechanism is not supported. GSS_S_BAD_NAMETYPE The provided internal name contains no elements that could be processed by the specified mechanism. GSS_S_BAD_NAME The provided internal name was ill-formed. |
| OM_uint32 gss_inquire_names_for_mech (OM_uint32 *minor_status, const gss_OID mechanism, gss_OID_set *name_types) | Function |
|
minor_status: Implementation specific status code. mechanism: The mechanism to be interrogated. name_types: Output set of name-types supported by the specified mechanism. The returned OID set must be freed by the application after use with a call to gss_release_oid_set(). Outputs the set of nametypes supported by the specified mechanism. Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_inquire_mechs_for_name (OM_uint32 *minor_status, const gss_name_t input_name, gss_OID_set *mech_types) | Function |
|
minor_status: Implementation specific status code. input_name: The name to which the inquiry relates. mech_types: Output set of mechanisms that may support the specified name. The returned OID set must be freed by the caller after use with a call to gss_release_oid_set(). Outputs the set of mechanisms supported by the GSS-API implementation that may be able to process the specified name. Each mechanism returned will recognize at least one element within the name. It is permissible for this routine to be implemented within a mechanism-independent GSS-API layer, using the type information contained within the presented name, and based on registration information provided by individual mechanism implementations. This means that the returned mech_types set may indicate that a particular mechanism will understand the name when in fact it would refuse to accept the name as input to gss_canonicalize_name(), gss_init_sec_context(), gss_acquire_cred() or gss_add_cred() (due to some property of the specific name, as opposed to the name type). Thus this routine should be used only as a pre-filter for a call to a subsequent mechanism-specific routine. Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_NAME to indicate that the input_name parameter was ill-formed, and GSS_S_BAD_NAMETYPE to indicate that the input_name parameter contained an invalid or unsupported type of name. |
| OM_uint32 gss_canonicalize_name (OM_uint32 *minor_status, const gss_name_t input_name, const gss_OID mech_type, gss_name_t *output_name) | Function |
|
minor_status: Mechanism specific status code. input_name: The name for which a canonical form is desired. mech_type: The authentication mechanism for which the canonical form of the name is desired. The desired mechanism must be specified explicitly; no default is provided. output_name: The resultant canonical name. Storage associated with this name must be freed by the application after use with a call to gss_release_name(). Generate a canonical mechanism name (MN) from an arbitrary internal name. The mechanism name is the name that would be returned to a context acceptor on successful authentication of a context where the initiator used the input_name in a successful call to gss_acquire_cred, specifying an OID set containing <mech_type> as its only member, followed by a call to gss_init_sec_context, specifying <mech_type> as the authentication mechanism. Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_MECH to indicate that the identified mechanism is not supported, GSS_S_BAD_NAMETYPE to indicate that the provided internal name contains no elements that could be processed by the specified mechanism, and GSS_S_BAD_NAME to indicate that the provided internal name was ill-formed. |
| OM_uint32 gss_export_name (OM_uint32 *minor_status, const gss_name_t input_name, gss_buffer_t exported_name) | Function |
|
minor_status: Mechanism specific status code. input_name: The mechanism name to be exported. exported_name: Output variable with canonical contiguous string form of input_name. Storage associated with this string must freed by the application after use with gss_release_buffer(). To produce a canonical contiguous string representation of a mechanism name (MN), suitable for direct comparison (e.g. with memcmp) for use in authorization functions (e.g. matching entries in an access-control list). The input_name parameter must specify a valid MN (i.e. an internal name generated by gss_accept_sec_context or by gss_canonicalize_name). Returns GSS_S_COMPLETE for successful completion, GSS_S_NAME_NOT_MN to indicate that the provided internal name was not a mechanism name, GSS_S_BAD_NAME to indicate that the provided internal name was ill-formed, and GSS_S_BAD_NAMETYPE to indicate that the internal name was of a type not supported by the GSS-API implementation. |
| OM_uint32 gss_duplicate_name (OM_uint32 * minor_status, const gss_name_t src_name, gss_name_t * dest_name) | Function |
|
minor_status: Mechanism specific status code. src_name: Internal name to be duplicated. dest_name: The resultant copy of <src_name>. Storage associated
with this name must be freed by the application after use with a
call to Create an exact duplicate of the existing internal name src_name. The new dest_name will be independent of src_name (i.e. src_name and dest_name must both be released, and the release of one shall not affect the validity of the other). Returns GSS_S_COMPLETE for successful completion, and GSS_S_BAD_NAME when the src_name parameter was ill-formed. |
Table 2-5 GSS-API Miscellaneous Routines
Routine Section Function
------- ------- --------
gss_add_oid_set_member 5.4 Add an object identifier to
a set
gss_display_status 5.11 Convert a GSS-API status code
to text
gss_indicate_mechs 5.18 Determine available underlying
authentication mechanisms
gss_release_buffer 5.26 Discard a buffer
gss_release_oid_set 5.29 Discard a set of object
identifiers
gss_create_empty_oid_set 5.8 Create a set containing no
object identifiers
gss_test_oid_set_member 5.30 Determines whether an object
identifier is a member of a set.
| OM_uint32 gss_release_buffer (OM_uint32 * minor_status, gss_buffer_t buffer) | Function |
|
minor_status: Mechanism specific status code. buffer: The storage associated with the buffer will be deleted. The gss_buffer_desc object will not be freed, but its length field will be zeroed. Free storage associated with a buffer. The storage must have been allocated by a GSS-API routine. In addition to freeing the associated storage, the routine will zero the length field in the descriptor to which the buffer parameter refers, and implementations are encouraged to additionally set the pointer field in the descriptor to NULL. Any buffer object returned by a GSS-API routine may be passed to gss_release_buffer (even if there is no storage associated with the buffer). Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_create_empty_oid_set (OM_uint32 * minor_status, gss_OID_set * oid_set) | Function |
|
minor_status: Mechanism specific status code oid_set: The empty object identifier set. The routine will
allocate the gss_OID_set_desc object, which the application must free
after use with a call to Create an object-identifier set containing no object identifiers, to
which members may be subsequently added using the
Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_add_oid_set_member (OM_uint32 * minor_status, const gss_OID member_oid, gss_OID_set * oid_set) | Function |
|
minor_status: Mechanism specific status code member_oid: The object identifier to copied into the set. oid_set: The set in which the object identifier should be inserted. Add an Object Identifier to an Object Identifier set. This routine
is intended for use in conjunction with gss_create_empty_oid_set
when constructing a set of mechanism OIDs for input to
gss_acquire_cred. The oid_set parameter must refer to an OID-set
that was created by GSS-API (e.g. a set returned by
Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_test_oid_set_member (OM_uint32 * minor_status, const gss_OID member, const gss_OID_set set, int * present) | Function |
|
minor_status: Mechanism specific status code member: The object identifier whose presence is to be tested. set: The Object Identifier set. present: output indicating if the specified OID is a member of the set, zero if not. Interrogate an Object Identifier set to determine whether a specified
Object Identifier is a member. This routine is intended to be used
with OID sets returned by Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_release_oid_set (OM_uint32 * minor_status, gss_OID_set * set) | Function |
|
minor_status: Mechanism specific status code set: The storage associated with the gss_OID_set will be deleted. Free storage associated with a GSSAPI-generated gss_OID_set object.
The set parameter must refer to an OID-set that was returned from a
GSS-API routine. Implementations are encouraged to set the gss_OID_set parameter to GSS_C_NO_OID_SET on successful completion of this routine. Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_indicate_mechs (OM_uint32 *minor_status, gss_OID_set *mech_set) | Function |
|
minor_status: Mechanism specific status code. mech_set: Output OID set with implementation-supported mechanisms. Allows an application to determine which underlying security mechanisms are available. The returned gss_OID_set value will be a dynamically-allocated OID set, that should be released by the caller after use with a call to gss_release_oid_set(). Returns GSS_S_COMPLETE for successful completion. |
| OM_uint32 gss_display_status (OM_uint32 *minor_status, OM_uint32 status_value, int status_type, const gss_OID mech_type, OM_uint32 *message_context, gss_buffer_t status_string) | Function |
|
minor_status: Mechanism specific status code. status_value Status value to be converted status_type: Type of status code. Valid values include GSS_C_GSS_CODE to indicate that status_value is a GSS status code, and GSS_C_MECH_CODE to indicate that status_value is a mechanism status code. mech_type: Optional OID of underlying mechanism (used to interpret a minor status value) Supply GSS_C_NO_OID to obtain the system default. message_context: Input/output variable that should be initialized to zero by the application prior to the first call. On return from gss_display_status(), a non-zero status_value parameter indicates that additional messages may be extracted from the status code via subsequent calls to gss_display_status(), passing the same status_value, status_type, mech_type, and message_context parameters. status_string: Output textual interpretation of the status_value. Storage associated with this parameter must be freed by the application after use with a call to gss_release_buffer(). Allows an application to obtain a textual representation of a GSS-API status code, for display to the user or for logging purposes. Since some status values may indicate multiple conditions, applications may need to call gss_display_status multiple times, each call generating a single text string. The message_context parameter is used by gss_display_status to store state information about which error messages have already been extracted from a given status_value; message_context must be initialized to 0 by the application prior to the first call, and gss_display_status will return a non-zero value in this parameter if there are further messages to extract. The message_context parameter contains all state information required by gss_display_status in order to extract further messages from the status_value; even when a non-zero value is returned in this parameter, the application is not required to call gss_display_status again unless subsequent messages are desired. The following code extracts all messages from a given status code and prints them to stderr: OM_uint32 message_context;
OM_uint32 status_code;
OM_uint32 maj_status;
OM_uint32 min_status;
gss_buffer_desc status_string;
...
message_context = 0;
do {
maj_status = gss_display_status (
&min_status,
status_code,
GSS_C_GSS_CODE,
GSS_C_NO_OID,
&message_context,
&status_string)
fprintf(stderr,
"%.*s\n",
(int)status_string.length,
(char *)status_string.value);
gss_release_buffer(&min_status, &status_string);
} while (message_context != 0);
Returns GSS_S_COMPLETE for successful completion, GSS_S_BAD_MECH to indicate that translation in accordance with an unsupported mechanism type was requested, and GSS_S_BAD_STATUS to indicate that the status value was not recognized, or the status type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE. |
None of the following functions are standard GSS API functions. As such, they are not declared in `gss/api.h', but rather in `gss.h'.
| const char * gss_check_version (const char * req_version) | Function |
|
req_version: version string to compare with, or NULL Check that the the version of the library is at minimum the one given
as a string in |
| int gss_oid_equal (gss_OID first_oid, gss_OID second_oid) | Function |
|
Compare to OIDs for equality. Compares actual content, not just pointer equality. Returns a boolean true iff the OIDs are equal. |
| OM_uint32 gss_copy_oid (OM_uint32 * minor_status, const gss_OID src_oid, gss_OID dest_oid); | Function |
|
Make an exact copy of the given OID, that shares no memory areas with the original. The contents of the copied OID must be deallocated by the caller. Returns GSS_S_COMPLETE on success. |
| OM_uint32 gss_duplicate_oid (OM_uint32 * minor_status, const gss_OID src_oid, gss_OID * dest_oid) | Function |
|
Allocate an exact copy of the given OID, that shares no memory areas with the original. The newly created OID, and its contents, must be deallocated by the caller. Returns GSS_S_COMPLETE on success. |
| int gss_encapsulate_token (gss_buffer_t input_message, gss_OID token_oid, gss_buffer_t output_message) | Function |
|
input_message: Message to be encapsulated. token_oid: OID of mechanism. input_message: Output buffer with encapsulated message. Wrap a buffer in the mechanism-independent token format. This is used for the initial token of a GSS-API context establishment sequence. It incorporates an identifier of the mechanism type to be used on that context, and enables tokens to be interpreted unambiguously at GSS-API peers. See further section 3.1 of RFC 2743. |
| int gss_decapsulate_token (gss_buffer_t input_message, gss_OID token_oid, gss_buffer_t output_message) | Function |
|
input_message: Message to decapsulated. token_oid: Output buffer with mechanism OID used in message. input_message: Output buffer with encapsulated message. Unwrap a buffer in the mechanism-independent token format. This is
the reverse of |
TBA
The author has doubts whether GSS is a good solution for new projects looking for a implementation agnostic security framework. We express these doubts in this section. GSS can be criticized on several levels. We start with the actual implementation.
GSS do not appear to be designed by experienced C programmers. While generally this may be a good thing (C is not the best language), but since they defined the API in C, it is unfortunate. The primary evidence of this is the major_status and minor_status error code solution. It is a complicated way to describe error conditions, but what makes matters worse, the error condition is separated; half of the error condition is in the function return value and the other half is in the first argument to the function, which is always a pointer to an integer. (The pointer is not even allowed to be NULL, if the application doesn't care about the minor error code.) This makes the API unreadable, and difficult to use. A better solutions would be to return a struct containing the entire error condition, which can be accessed using macros, although we acknowledge that the C language used at the time may not have allowed this (this may in fact be the reason the awkward solution was chosen). Instead, the return value could have been passed back to callers using a pointer to a struct, accessible using various macros, and the function could have a void prototype. The fact that minor_status is placed first in the parameter list increases the pain it is to use the API. Important parameters should be placed first. A better place for minor_status would have been last in the prototypes.
Another evidence of the C inexperience are the memory management issues; GSS provides functions to deallocate data stored within, e.g., gss_buffer_t but the caller is responsible of deallocating the gss_buffer_t struct itself. Memory management issues are error prone, and this division easily leads to memory leaks (or worse). Instead, the API should be the sole owner of all gss_ctx_id_t, gss_cred_id_t, and gss_buffer_t structures: they should be allocated by the library, and deallocated (using the utility functions defined for this purpose) by the library.
TBA: thread issues
TBA: multiple mechanisms in a GSS library
TBA: high-level criticism.
TBA: no credential forwarding.
TBA: krb5: no way to access authorization-data
TBA: krb5: firewall/pre-IP: iakerb status?
TBA: krb5: single-DES only
We also note that very few free security systems uses GSS, perhaps the only exception to this are Kerberos 5 implementations. This suggest that the GSS may not have been so "generic" as it was thought to be.
Our conclusion is that any new project that is looking for a security framework, that is independent of any particular implementation, should look elsewhere. In particular SASL is recommended. The most compelling argument is that SASL is, as its acronym suggest, Simple, whereas GSS is not, in any regard.
gss_add_oid_set_member: Miscellaneous Routines
gss_canonicalize_name: Name Manipulation
gss_check_version: Extended GSS API
gss_compare_name: Name Manipulation
gss_copy_oid: Extended GSS API
gss_create_empty_oid_set: Miscellaneous Routines
gss_decapsulate_token: Extended GSS API
gss_delete_sec_context: Context-Level Routines
gss_display_name: Name Manipulation
gss_display_status: Miscellaneous Routines
gss_duplicate_name: Name Manipulation
gss_duplicate_oid: Extended GSS API
gss_encapsulate_token: Extended GSS API
gss_export_name: Name Manipulation
gss_import_name: Name Manipulation
gss_indicate_mechs: Miscellaneous Routines
gss_init_sec_context: Context-Level Routines
gss_inquire_mechs_for_name: Name Manipulation
gss_inquire_names_for_mech: Name Manipulation
gss_oid_equal: Extended GSS API
gss_release_buffer: Miscellaneous Routines
gss_release_cred: Credential Management
gss_release_name: Name Manipulation
gss_release_oid_set: Miscellaneous Routines
gss_test_oid_set_member: Miscellaneous Routines
gss_unwrap: Per-Message Routines
gss_wrap: Per-Message Routines