GSS-API Programming Guide


A credential is a data structure that provides proof of an application's claim to a principal name. An application uses a credential to establish its global identity. You can think of a credential as a principal's “identity badge,” a set of information that proves that a person, machine, or program is who it claims to be and, often, what privileges it has.

The GSS-API does not provide credentials. Credentials are created by the security mechanisms that underly the GSS-API, before GSS-API functions are called. In many cases, for example, users receive credentials when they log in to a system.

A given GSS-API credential is valid for a single principal. A single credential can contain several elements for that principal, each created by a different mechanism, as shown in Figure 1–7. This means that a credential acquired on a machine with several security mechanisms will be valid if transferred to a machine that has only a subset of those mechanisms. The GSS-API accesses credentials through the gss_cred_id_t structure; this structure is called a credential handle. Credentials are opaque to applications; you don't need to know the specifics of a given credential.

Figure 1–7 Generalized GSS-API Credential


Credentials come in three forms:

Acquiring Credentials

Before a security context can be established, both the server and the client must acquire their respective credentials. Once acquired, credentials can be re-used until they expire, at which time they must be re-acquired. Credentials used by the client and those used by the server might have different lifetimes.

GSS-API-based applications acquire credentials in one of two ways:

In most cases, gss_acquire_cred() is called only by a context acceptor (server), because the context initiator (client) is likely to have received its credentials at login. The initiator, therefore, can usually specify only the default credential. The context acceptor can also bypass using gss_acquire_cred() and use its default credential instead.

The initiator's credential proves its identity to other processes, while the acceptor acquires a credential to enable it to accept a security context. Consider the case of a client making an ftp request to a server. The client already has a credential, from login, and the GSS-API is automatically retrieves that credential when the client attempts to initiate a context. The server program, however, is explicitly acquires credentials for the requested service (ftp).

gss_acquire_cred() takes the syntax shown below:

Example 1–5

OM_uint32 gss_acquire_cred (
OM_uint32         *minor_status,
const gss_name_t  desired_name,
OM_uint32         time_req,
const gss_OID_set desired_mechs,
gss_cred_usage_t  cred_usage,
gss_cred_id_t     *output_cred_handle,
gss_OID_set       *actual_mechs,
OM_uint32         *time_rec)


The status code given by the underlying mechanism upon return.


The name of the principal whose credential should be acquired. In our example above, it would be “ftp.” This argument would be created with gss_import_name() (see Names).

Note that if desired_name is set to GSS_C_NO_NAME, then the credential returned is a generic one that causes the GSS-API context-initiation and context-acceptance routines to use their default behavior with regard to credentials. In other words, passing GSS_C_NO_NAME to gss_acquire_cred() returns a credential that, when passed to gss_init_sec_context() or gss_accept_sec_context(), is equivalent to passing them the default credential request (GSS_C_NO_CREDENTIAL). See Context Initiation (Client) and Context Acceptance (Server) for more information.


The length of time (in seconds) for which the credential should remain valid. Specify GSS_C_INDEFINITE to request the maximum permitted lifetime.


The set of underlying mechanisms that the application wants to use with this credential. This is a gss_OID_set data structure containing one or more gss_OID structures, each representing an appropriate mechanism. If possible, specify GSS_C_NO_OID_SET to get a default set from the GSS-API.


A flag that indicates how this credential should be used: for context initiation (GSS_C_INITIATE), acceptance (GSS_C_ACCEPT), or both (GSS_C_BOTH).


The credential handle returned by this function.


A set of mechanisms that can be used with this credential. If you don't need to know what the mechanisms are, set this to NULL.


The actual number of seconds for which the credential is valid. Set to NULL if this value doesn't interest you.

gss_acquire_cred() returns GSS_S_COMPLETE if it completes successfully. If it cannot return a valid credential, it returns GSS_S_NO_CRED; see the gss_acquire_cred(3GSS) man page for other error codes. An example of acquiring a credential can be found in Acquiring Credentials (program listing in server_acquire_creds()).

gss_add_cred() is similar to gss_acquire_cred(), but allows an application to either create a new credential handle based on an existing credential or to add a new credential element to the existing one. If GSS_C_NO_CREDENTIAL is specified as the existing credential, then gss_add_cred() will create a new credential based on default behavior. See the gss_add_cred(3GSS) man page for more information.