--- name: "gss_acquire_cred" section: "3" platform: "linux" package: "gss-man" version: "1.0.4-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gss_acquire_cred" --- # gss\_acquire\_cred(3) API function ## NAME gss\_acquire\_cred - API function ## SYNOPSIS **#include \** **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***);** ## ARGUMENTS - OM\_uint32 \* minor\_status (integer, modify) Mechanism specific status code. - const gss\_name\_t desired\_name (gss\_name\_t, read) Name of principal whose\ credential should be acquired. - OM\_uint32 time\_req (Integer, read, optional) Number of seconds that\ credentials should remain valid. Specify GSS\_C\_INDEFINITE to\ request that the credentials have the maximum permitted lifetime. - const gss\_OID\_set desired\_mechs (Set of Object IDs, read, optional) Set of\ underlying security mechanisms that may be used.\ GSS\_C\_NO\_OID\_SET may be used to obtain an implementation-specific\ default. - gss\_cred\_usage\_t cred\_usage (gss\_cred\_usage\_t, read) GSS\_C\_BOTH - Credentials may\ be used either to initiate or accept security contexts.\ GSS\_C\_INITIATE - Credentials will only be used to initiate\ security contexts. GSS\_C\_ACCEPT - Credentials will only be used\ to accept security contexts. - gss\_cred\_id\_t \* output\_cred\_handle (gss\_cred\_id\_t, modify) The returned\ credential handle. Resources associated with this credential\ handle must be released by the application after use with a call\ to **gss\_release\_cred()**. - gss\_OID\_set \* actual\_mechs (Set of Object IDs, modify, optional) The set of\ mechanisms for which the credential is valid. Storage associated\ with the returned OID-set must be released by the application\ after use with a call to **gss\_release\_oid\_set()**. Specify NULL if\ not required. - OM\_uint32 \* time\_rec (Integer, modify, optional) Actual number of seconds for\ which the returned credentials will remain valid. If the\ implementation does not support expiration of credentials, the\ value GSS\_C\_INDEFINITE will be returned. Specify NULL if not\ required. ## DESCRIPTION Allows an application to acquire a handle for a pre-existing credential by name. GSS-API implementations must impose a local access-control policy on callers of this routine to prevent unauthorized callers from acquiring credentials to which they are not entitled. This routine is not intended to provide a "login to the network" function, as such a function would involve the creation of new credentials rather than merely acquiring a handle to existing credentials. Such functions, if required, should be defined in implementation-specific extensions to the API. If desired\_name is GSS\_C\_NO\_NAME, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to **gss\_init\_sec\_context()** (if cred\_usage is GSS\_C\_INITIATE or GSS\_C\_BOTH) or **gss\_accept\_sec\_context()** (if cred\_usage is GSS\_C\_ACCEPT or GSS\_C\_BOTH). Mechanisms should honor the desired\_mechs parameter, and return a credential that is suitable to use only with the requested mechanisms. An exception to this is the case where one underlying credential element can be shared by multiple mechanisms; in this case it is permissible for an implementation to indicate all mechanisms with which the credential element may be used. If desired\_mechs is an empty set, behavior is undefined. This routine is expected to be used primarily by context acceptors, since implementations are likely to provide mechanism-specific ways of obtaining GSS-API initiator credentials from the system login process. Some implementations may therefore not support the acquisition of GSS\_C\_INITIATE or GSS\_C\_BOTH credentials via gss\_acquire\_cred for any name other than GSS\_C\_NO\_NAME, or a name produced by applying either gss\_inquire\_cred to a valid credential, or gss\_inquire\_context to an active context. If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required (e.g. by gss\_init\_sec\_context or gss\_accept\_sec\_context). Such mechanism-specific implementation decisions should be invisible to the calling application; thus a call of gss\_inquire\_cred immediately following the call of gss\_acquire\_cred must return valid credential data, and may therefore incur the overhead of a deferred credential acquisition. ## RETURN VALUE \`GSS\_S\_COMPLETE\`: Successful completion. \`GSS\_S\_BAD\_MECH\`: Unavailable mechanism requested. \`GSS\_S\_BAD\_NAMETYPE\`: Type contained within desired\_name parameter is not supported. \`GSS\_S\_BAD\_NAME\`: Value supplied for desired\_name parameter is ill formed. \`GSS\_S\_CREDENTIALS\_EXPIRED\`: The credentials could not be acquired Because they have expired. \`GSS\_S\_NO\_CRED\`: No credentials were found for the specified name. ## REPORTING BUGS Report bugs to \. GNU Generic Security Service home page: http://www.gnu.org/software/gss/ General help using GNU software: http://www.gnu.org/gethelp/ ## COPYRIGHT Copyright © 2003-2022 Simon Josefsson.\ Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. ## SEE ALSO The full documentation for **gss** is maintained as a Texinfo manual. If the **info** and **gss** programs are properly installed at your site, the command - **info gss** should give you access to the complete manual.