--- name: "gss_add_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_add_cred" --- # gss\_add\_cred(3) API function ## NAME gss\_add\_cred - API function ## SYNOPSIS **#include \** **OM\_uint32 gss\_add\_cred(OM\_uint32 \*** *minor\_status***, const gss\_cred\_id\_t** *input\_cred\_handle***, const gss\_name\_t** *desired\_name***, const gss\_OID** *desired\_mech***, gss\_cred\_usage\_t** *cred\_usage***, OM\_uint32** *initiator\_time\_req***, OM\_uint32** *acceptor\_time\_req***, gss\_cred\_id\_t \*** *output\_cred\_handle***, gss\_OID\_set \*** *actual\_mechs***, OM\_uint32 \*** *initiator\_time\_rec***, OM\_uint32 \*** *acceptor\_time\_rec***);** ## ARGUMENTS - OM\_uint32 \* minor\_status (integer, modify) Mechanism specific status code. - const gss\_cred\_id\_t input\_cred\_handle (gss\_cred\_id\_t, read, optional) The credential\ to which a credential-element will be added. If\ GSS\_C\_NO\_CREDENTIAL is specified, the routine will compose the\ new credential based on default behavior (see text).\ Note that, while the credential-handle is not modified by\ **gss\_add\_cred()**, the underlying credential will be modified if\ output\_credential\_handle is NULL. - const gss\_name\_t desired\_name (gss\_name\_t, read.) Name of principal whose\ credential should be acquired. - const gss\_OID desired\_mech (Object ID, read) Underlying security mechanism with\ which the credential may be used. - gss\_cred\_usage\_t cred\_usage (gss\_cred\_usage\_t, read) GSS\_C\_BOTH - Credential may\ be used either to initiate or accept security contexts.\ GSS\_C\_INITIATE - Credential will only be used to initiate\ security contexts. GSS\_C\_ACCEPT - Credential will only be used\ to accept security contexts. - OM\_uint32 initiator\_time\_req (Integer, read, optional) number of seconds\ that the credential should remain valid for initiating security\ contexts. This argument is ignored if the composed credentials\ are of type GSS\_C\_ACCEPT. Specify GSS\_C\_INDEFINITE to request\ that the credentials have the maximum permitted initiator\ lifetime. - OM\_uint32 acceptor\_time\_req (Integer, read, optional) number of seconds\ that the credential should remain valid for accepting security\ contexts. This argument is ignored if the composed credentials\ are of type GSS\_C\_INITIATE. Specify GSS\_C\_INDEFINITE to request\ that the credentials have the maximum permitted initiator\ lifetime. - gss\_cred\_id\_t \* output\_cred\_handle (gss\_cred\_id\_t, modify, optional) The returned\ credential handle, containing the new credential-element and all\ the credential-elements from input\_cred\_handle. If a valid\ pointer to a gss\_cred\_id\_t is supplied for this parameter,\ gss\_add\_cred creates a new credential handle containing all\ credential-elements from the input\_cred\_handle and the newly\ acquired credential-element; if NULL is specified for this\ parameter, the newly acquired credential-element will be added to\ the credential identified by input\_cred\_handle. The resources\ associated with any credential handle returned via this parameter\ 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 complete\ set of mechanisms for which the new credential is valid. Storage\ for the returned OID-set must be freed by the application after\ use with a call to **gss\_release\_oid\_set()**. Specify NULL if not\ required. - OM\_uint32 \* initiator\_time\_rec (Integer, modify, optional) Actual number of\ seconds for which the returned credentials will remain valid for\ initiating contexts using the specified mechanism. If the\ implementation or mechanism does not support expiration of\ credentials, the value GSS\_C\_INDEFINITE will be returned. Specify\ NULL if not required - OM\_uint32 \* acceptor\_time\_rec (Integer, modify, optional) Actual number of\ seconds for which the returned credentials will remain valid for\ accepting security contexts using the specified mechanism. If\ the implementation or mechanism does not support expiration of\ credentials, the value GSS\_C\_INDEFINITE will be returned. Specify\ NULL if not required ## DESCRIPTION Adds a credential-element to a credential. The credential-element is identified by the name of the principal to which it refers. GSS-API implementations must impose a local access-control policy on callers of this routine to prevent unauthorized callers from acquiring credential-elements 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 mechanism-specific authentication data, rather than merely acquiring a GSS-API handle to existing data. 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 to add a credential element 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). 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\_add\_cred must return valid credential data, and may therefore incur the overhead of a deferred credential acquisition. This routine can be used to either compose a new credential containing all credential-elements of the original in addition to the newly-acquire credential-element, or to add the new credential- element to an existing credential. If NULL is specified for the output\_cred\_handle parameter argument, the new credential-element will be added to the credential identified by input\_cred\_handle; if a valid pointer is specified for the output\_cred\_handle parameter, a new credential handle will be created. If GSS\_C\_NO\_CREDENTIAL is specified as the input\_cred\_handle, gss\_add\_cred will compose a credential (and set the output\_cred\_handle parameter accordingly) based on default behavior. That is, the call will have the same effect as if the application had first made a call to **gss\_acquire\_cred()**, specifying the same usage and passing GSS\_C\_NO\_NAME as the desired\_name parameter to obtain an explicit credential handle embodying default behavior, passed this credential handle to **gss\_add\_cred()**, and finally called **gss\_release\_cred()** on the first credential handle. If GSS\_C\_NO\_CREDENTIAL is specified as the input\_cred\_handle parameter, a non-NULL output\_cred\_handle must be supplied. ## 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\_DUPLICATE\_ELEMENT\`: The credential already contains an element for the requested mechanism with overlapping usage and validity period. \`GSS\_S\_CREDENTIALS\_EXPIRED\`: The required credentials could not be added 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.