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:

• By using the gss_acquire_cred() function (in some cases this will be the gss_add_cred() function), or

• By specifying a default credential, represented by the value GSS_C_NO_CREDENTIAL, when establishing a context.

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)

minor_status

The status code given by the underlying mechanism upon return.

desired_name

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.

time_req

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

desired_mechs

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.

cred_usage

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).

output_cred_handle

The credential handle returned by this function.

actual_mechs

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.

time_rec

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.