GSS-API Programming Guide

Introduction to the GSS-API

As its name implies, the GSS-API enables programmers to write applications that are generic with respect to security; that is, they do not have to tailor their security implementations to any particular platform, security mechanism, type of protection, or transport protocol. Although the GSS-API enables applications control over security aspects, a programmer using GSS-API can write a program that is ignorant of the details of protecting network data. Therefore, a program that takes advantage of GSS-API is more portable as regards network security. More than anything else, this portability is the hallmark of the Generic Security Standard API.

The GSS-API does not actually provide security services itself. Rather, it is a framework that provides security services to callers in a generic fashion, supportable with a range of underlying mechanisms and technologies such as Kerberos v5 or public key technologies, as shown in Figure 1–1:

Figure 1–1 The GSS-API Layer

Diagram shows the GSS-API and protocol layers between the application and the security mechanisms.

Broadly speaking, the GSS-API does two main things:

It creates a security context in which data can be passed between applications. A context can be thought of as a sort of “state of trust” between two applications. Applications that share a context know who each other are and thus can permit data transfers between them as long as the context lasts.
It applies one or more types of protection, known as security services, to the data to be transmitted. Security services are explained in Security Services.

Of course, the GSS-API is more complex than that. Some of the other things that the GSS-API does include: data conversion; error checking; delegation of user privileges; information display; and identity comparison. The GSS-API includes numerous support or convenience functions.

Application Portability

As mentioned above, the GSS-API provides several types of portability for applications:

Mechanism independence. GSS-API provides a generic interface to the mechanisms for which it has been implemented. By specifying a default security mechanism, an application does not need to know which mechanism it is using (for example, Kerberos v5), or even what type of mechanism it uses. As an example, when an application forwards a user's credential to a server, it does not need to know if that credential has a Kerberos format or the format used by some other mechanism, nor how the credentials are stored by the mechanism and accessed by the application. (If necessary, an application can specify a particular mechanism to use.)
Protocol independence. The GSS–API is independent of any communications protocol or protocol suite. It can be used with applications that use, for example, sockets, RCP, or TCP/IP.

RPCSEC_GSS is an additional layer that smoothly integrates GSS-API with RPC. For more information, see RPCSEC_GSS Layer.
Platform independence. The GSS-API is completely oblivious to the type of operating system on which an application is running.
Quality of Protection independence. Quality of Protection (QOP) is the name given to the type of algorithm used in encrypting data or generating cryptographic tags; the GSS-API allows a programmer to ignore QOP, using a default provided by the GSS-API. (On the other hand, an application can specify the QOP if necessary.)

Security Services

The basic security offered by the GSS-API is authentication. Authentication is the verification of an identity: if you are authenticated, it means that you are recognized to be who you say you are.

The GSS-API provides for two additional security services, if supported by the underlying mechanisms:

Integrity. It's not always sufficient to know that an application sending you data is who it claims to be. The data itself could have become corrupted or compromised. The GSS-API provides for data to be accompanied by a cryptographic tag, known as an Message Integrity Code (MIC), to prove that the data that arrives at your doorstep is the same as the data that the sender transmitted. This verification of the data's validity is known as integrity.
Confidentiality. Both authentication and integrity, however, leave the data itself alone, so if it's somehow intercepted, others can read it. The GSS-API therefore allows data to be encrypted, if underlying mechanisms support it. This encryption of data is known as confidentiality.

Mechanisms Available With GSS-API

The current implementation of the GSS-API works only with the Kerberos v5 security mechanism. (This includes its Sun variant, the Solaris Enterprise Authentication Mechanism, or SEAM. See “Introduction to SEAM” in System Administration Guide: Security Services for more information.) Kerberos v5 or SEAM must, therefore, be installed and running on any system on which GSS-API-aware programs are running.

RPCSEC_GSS Layer

Programmers who employ the RPC (Remote Procedure Call) protocol for their networking applications can use RPCSEC_GSS to provide security. RPCSEC_GSS is a separate layer that sits on top of GSS-API; it provides all the functionality of GSS-API in a way that is tailored to RPC. In fact, it serves to hide many aspects of GSS-API from the programmer, making RPC security especially accessible and portable. For more information on RPCSEC_GSS, see the ONC+ Developer's Guide.

Figure 1–2 RPCSEC_GSS and GSS-API

Diagram shows that the RPCSEC_GSS layer lies between the application and the GSS-API layer.

What the GSS-API Does Not Do For You

Although the GSS-API makes protecting data simple, it does not do certain things, in order to maximize its generic nature. These include:

Provide security credentials for a user or application. These must be provided by the underlying security mechanism(s). The GSS-API does allow applications to acquire credentials, either automatically or explicitly.
Transfer data between applications. It is the application's responsibility to handle the transfer of all data between peers, whether it is security-related or “plain” data.
Distinguish between different types of transmitted data (for example, to know or determine that a data packet is plain data and not GSS–API related).
Indicate status due to remote (asynchronous) errors.
Automatically protect information sent between processes of a multiprocess program.
Allocate string buffers to be passed to GSS-API functions. See Strings and Similar Data.
Deallocate GSS-API data spaces. These must be explicitly deallocated with functions such as gss_release_buffer() and gss_delete_name().

Language Bindings

This document currently covers only the C language bindings (functions and data types) for the GSS-API. At some point a Java-bindings version of the GSS-API might become available.

Where to Get More Information

Two documents provide descriptions of the GSS-API (and are somewhat more oriented toward the GSS-API implementor than to the application developer). The Generic Security Service Application Program Interface document (ftp://ftp.isi.edu/in-notes/rfc2743.txt) provides a conceptual overview of the GSS-API, while the Generic Security Service API Version 2: C-Bindings document (ftp://ftp.isi.edu/in-notes/rfc2744.txt) discusses the specifics of the C-language-based GSS-API.