This routine adds a credential-element to a credential. The
credential-element is identified by the name of the principal to
which it refers. 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 GSSAPI handle to existing data.
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 GSSAPI 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.
This routine can be used to either compose a new credential
containing all credential-elements of the original in addition to
the newly acquired credential element, or to add the new credential-element
to an existing credential. If NULL is specified for the output_cred_handle 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 argument,
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 argument
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 argument
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 argument,
a nonNULL output_cred_handle must be supplied.