Working With Credentials in GSS-API

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 that application's global identity. Additionally, a credential may be used to confirm an entity's privileges.

GSS-API does not provide credentials. Credentials are created by the security mechanisms that underly GSS-API, before GSS-API functions are called. In many cases, a user receives credentials at login.

A given GSS-API credential is valid for a single principal. A single credential can contain multiple elements for that principal, each created by a different mechanism. A credential that is acquired on a machine with multiple security mechanisms is valid if that credential is transferred to a machine with a subset of those mechanisms. GSS-API accesses credentials through the gss_cred_id_t structure. This structure is called a credential handle. Credentials are opaque to applications. Thus, the application does not need to know the specifics of a given credential.

Credentials come in three forms:

• GSS_C_INITIATE – Identifies applications that only initiate security contexts

• GSS_C_ACCEPT – Identifies applications that only accept security contexts

• GSS_C_BOTH – Identifies applications that can initiate or accept security contexts

Acquiring Credentials in GSS-API

Before a security context can be established, both the server and the client must acquire their respective credentials. A credential can be reused until that credential expires, after which the application must reacquire the credential. Credentials that are used by the client and credentials that are used by the server can have different lifetimes.

GSS-API-based applications can acquire credentials in two ways:

• By using the gss_acquire_cred() or gss_add_cred() function

• By specifying the value GSS_C_NO_CREDENTIAL, which indicates a default credential, when the context is established

In most cases, gss_acquire_cred() is called only by a context acceptor, that is, a server. A context initiator, that is, a client, typically receives credentials at login. A client, therefore, can usually specify the default credential. The server can also bypass gss_acquire_cred() and use that server's default credential instead.

A client's credential proves that client's identity to other processes. A server acquires a credential to enable that server to accept a security context. So when a client makes an ftp request to a server, that client might already have a credential from login. GSS-API automatically retrieves the credential when the client attempts to initiate a context. The server program, however, explicitly acquires credentials for the requested service (ftp).

If gss_acquire_cred() completes successfully, then GSS_S_COMPLETE is returned. If a valid credential cannot be returned, then GSS_S_NO_CRED is returned. See the gss_acquire_cred(3GSS) man page for other error codes. For an example, see “Acquiring Credentials” in Chapter 8.

gss_add_cred() is similar to gss_acquire_cred(). However, gss_add_cred() enables an application to use an existing credential to create a new handle or to add a new credential element. If GSS_C_NO_CREDENTIAL is specified as the existing credential, then gss_add_cred() creates a new credential according to the default behavior. See the gss_add_cred(3GSS) man page for more information.