Acquiring Credentials

Credentials are created by the underlying mechanisms rather than by the client application, server application, or GSS-API. A client program often has credentials that are obtained at login. A server always needs to acquire credentials explicitly.

Thegss-server programhas a function,server_acquire_creds(), to get the credentialsfor the service to be provided. Theserver_acquire_creds() functiontakes as input the name of the service and the security mechanism to be used.Theserver_acquire_creds() function then returns the credentialsfor the service. Theserver_acquire_creds() function usesthe GSS-API functiongss_acquire_cred() to get the credentialsfor the service that the server provides.

Beforeserver_acquire_creds() accessesgss_acquire_cred(),server_acquire_creds() must complete the followingtwo tasks:

1. Checking for a list of mechanisms and reducing the list toa single mechanism for the purpose of getting a credential.

   Ifa single credential can be shared by multiple mechanisms, thegss_acquire_cred() function returns credentials for all those mechanisms. Therefore,gss_acquire_cred() takes as input aset of mechanisms.(SeeWorking With Credentials in GSS-API.)In most cases, however, including this one, a single credential might notwork for multiple mechanisms. In thegss-server program,either a single mechanism is specified on the command line or else the defaultmechanism is used. Therefore, the first task is to make sure that the setof mechanisms that was passed togss_acquire_cred() containsa single mechanism, default or otherwise, as follows:

   if (mechOid != GSS_C_NULL_OID) {     desiredMechs = &mechOidSet;     mechOidSet.count = 1;     mechOidSet.elements = mechOid;} else     desiredMechs = GSS_C_NULL_OID_SET;

   GSS_C_NULL_OID_SET indicates that the defaultmechanism should be used.

2. Translating the service name into GSS-API format.

   Becausegss_acquire_cred() takes the servicename in the form of a gss_name_t structure, the nameof the service must be imported into that format. Thegss_import_name() functionperforms this translation. Because this function, like all GSS-API functions,requires arguments to be GSS-API types, the service name has to be copiedto a GSS-API buffer first, as follows:

        name_buf.value = service_name;     name_buf.length = strlen(name_buf.value) + 1;     maj_stat = gss_import_name(&min_stat, &name_buf,                (gss_OID) GSS_C_NT_HOSTBASED_SERVICE, &server_name);     if (maj_stat != GSS_S_COMPLETE) {          display_status("importing name", maj_stat, min_stat);          if (mechOid != GSS_C_NO_OID)                gss_release_oid(&min_stat, &mechOid);          return -1;     }

   Note again the use of the nonstandard functiongss_release_oid().

   The input is the service name as a string inname_buf.The output is the pointer to a gss_name_t structure,server_name. The third argument,GSS_C_NT_HOSTBASED_SERVICE, is the name type for the string inname_buf.In this case, the name type indicates that the string should be interpretedas a service of the formatservice@host.

After these tasks have been performed, the server program can callgss_acquire_cred():

maj_stat = gss_acquire_cred(&min_stat, server_name, 0,                                 desiredMechs, GSS_C_ACCEPT,                                 server_creds, NULL, NULL);

• min_stat is the error code returnedby the function.

• server_name is the name of theserver.

• 0 indicates that the program does not need to know the maximumlifetime of the credential.

• desiredMechs is the set of mechanismsfor which this credential applies.

• GSS_C_ACCEPT means that the credentialcan be used only to accept security contexts.

• server_creds is the credentialhandle to be returned by the function.

• NULL, NULL indicates that the program does not need to knoweither the specific mechanism being employed or the amount of time that thecredential will be valid.

The following source code illustrates theserver_acquire_creds() function.

/* * Function: server_acquire_creds * * Purpose: imports a service name and acquires credentials for it * * Arguments: * *      service_name    (r) the ASCII service name        mechType        (r) the mechanism type to use *      server_creds    (w) the GSS-API service credentials * * Returns: 0 on success, -1 on failure * * Effects: * * The service name is imported with gss_import_name, and service * credentials are acquired with gss_acquire_cred.  If either operation * fails, an error message is displayed and -1 is returned; otherwise, * 0 is returned. */int server_acquire_creds(service_name, mechOid, server_creds)     char *service_name;     gss_OID mechOid;     gss_cred_id_t *server_creds;{     gss_buffer_desc name_buf;     gss_name_t server_name;     OM_uint32 maj_stat, min_stat;     gss_OID_set_desc mechOidSet;     gss_OID_set desiredMechs = GSS_C_NULL_OID_SET;     if (mechOid != GSS_C_NULL_OID) {                desiredMechs = &mechOidSet;                mechOidSet.count = 1;                mechOidSet.elements = mechOid;     } else                desiredMechs = GSS_C_NULL_OID_SET;     name_buf.value = service_name;     name_buf.length = strlen(name_buf.value) + 1;     maj_stat = gss_import_name(&min_stat, &name_buf,                (gss_OID) GSS_C_NT_HOSTBASED_SERVICE, &server_name);     if (maj_stat != GSS_S_COMPLETE) {          display_status("importing name", maj_stat, min_stat);          if (mechOid != GSS_C_NO_OID)                gss_release_oid(&min_stat, &mechOid);          return -1;     }     maj_stat = gss_acquire_cred(&min_stat, server_name, 0,                                 desiredMechs, GSS_C_ACCEPT,                                 server_creds, NULL, NULL);     if (maj_stat != GSS_S_COMPLETE) {          display_status("acquiring credentials", maj_stat, min_stat);          return -1;     }     (void) gss_release_name(&min_stat, &server_name);     return 0;}