Mercurial Mercurial > upstream > oracle > userland-gate / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
components/krb5/Solaris/man/gss_add_cred.3gss
changeset 5490 9bf0bc57423a
child 7820 a2b9a7de9e1a 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/krb5/Solaris/man/gss_add_cred.3gss	Wed Feb 24 10:43:57 2016 -0600
@@ -0,0 +1,307 @@
+'\" te
+.\" Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved.
+.TH gss_add_cred 3GSS "30 Jun 2005" "SunOS 5.12" "Generic Security Services API Library Functions"
+.SH NAME
+gss_add_cred \- add a credential-element to a credential
+.SH SYNOPSIS
+.LP
+.nf
+\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]
+#include <gssapi/gssapi.h>
+
+\fBOM_uint32\fR \fBgss_add_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
+     \fBconst gss_cred_id_t\fR \fIinput_cred_handle\fR,
+     \fBconst gss_name_t\fR \fIdesired_name\fR,
+     \fBconst gss_OID\fR \fIdesired_mech\fR,
+     \fBgss_cred_usage_t\fR \fIcred_usage\fR,
+     \fBOM_uint32\fR \fIinitiator_time_req\fR,
+     \fBOM_uint32\fR \fIacceptor_time_req\fR,
+     \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR,
+     \fBgss_OID_set *\fR\fIactual_mechs\fR,
+     \fBOM_uint32 *\fR\fIinitiator_time_rec\fR,
+     \fBOM_uint32 *\fR\fIacceptor_time_rec\fR);
+.fi
+
+.SH PARAMETERS
+.sp
+.LP
+The parameter descriptions for \fBgss_add_cred()\fR follow:
+.sp
+.ne 2
+.mk
+.na
+\fB\fIminor_status\fR\fR
+.ad
+.RS 22n
+.rt  
+Mechanism specific status code.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIinput_cred_handle\fR\fR
+.ad
+.RS 22n
+.rt  
+Credential to which the credential-element is added. If \fBGSS_C_NO_CREDENTIAL\fR is specified, the function composes the new credential based on default behavior. While the credential-handle is not modified by \fBgss_add_cred()\fR, the underlying credential is modified if \fIoutput_credential_handle\fR is \fBNULL\fR.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIdesired_name\fR\fR
+.ad
+.RS 22n
+.rt  
+Name of the principal for which a credential should be acquired.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIdesired_mech\fR\fR
+.ad
+.RS 22n
+.rt  
+Underlying security mechanism with which the credential can be used. GSS_C_NULL_OID can be used to obtain a default.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIcred_usage\fR\fR
+.ad
+.RS 22n
+.rt  
+Flag that indicates how a credential is used to initiate or accept security credentials. If the flag is \fBGSS_C_ACCEPT\fR, the credentials are used only to accept security credentials. If the flag is \fBGSS_C_INITIATE\fR, the credentials are used only to initiate security credentials. If the flag is GSS_C_BOTH, the credentials can be used to either initiate or accept security contexts.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIinitiator_time_req\fR\fR
+.ad
+.RS 22n
+.rt  
+Number of seconds that the credential may remain valid for initiating security contexts. This argument is ignored if the composed credentials are of the \fBGSS_C_ACCEPT\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the credentials have the maximum permitted initiator lifetime.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIacceptor_time_req\fR\fR
+.ad
+.RS 22n
+.rt  
+Number of seconds that the credential may remain valid for accepting security contexts. This argument is ignored if the composed credentials are of the \fBGSS_C_INITIATE\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the credentials have the maximum permitted initiator lifetime.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIoutput_cred_handle\fR\fR
+.ad
+.RS 22n
+.rt  
+Returned credential handle that contains the new credential-element and all the credential-elements from \fIinput_cred_handle\fR. If a valid pointer to a \fBgss_cred_id_t\fR is supplied for this parameter, \fBgss_add_cred()\fR creates a new credential handle that contains all credential-elements from \fIinput_cred_handle\fR and the newly acquired credential-element. If \fBNULL\fR is specified for this parameter, the newly acquired credential-element is added to the credential identified by \fIinput_cred_handle\fR.
+.sp
+The resources associated with any credential handle returned by means of this parameter must be released by the application after use by a call to \fBgss_release_cred\fR(3GSS).
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIactual_mechs\fR\fR
+.ad
+.RS 22n
+.rt  
+Complete set of mechanisms for which the new credential is valid. Storage for the returned \fBOID\fR-set must be freed by the application after use by a call to \fBgss_release_oid_set\fR(3GSS). Specify \fBNULL\fR if this parameter is not required.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIinitiator_time_rec\fR\fR
+.ad
+.RS 22n
+.rt  
+Actual number of seconds for which the returned credentials remain valid for initiating contexts using the specified mechanism. If a mechanism does not support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is returned. Specify \fBNULL\fR if this parameter is not required.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIacceptor_time_rec\fR\fR
+.ad
+.RS 22n
+.rt  
+Actual number of seconds for which the returned credentials remain valid for accepting security contexts using the specified mechanism. If a mechanism does not support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is returned. Specify \fBNULL\fR if this parameter is not required.
+.RE
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBgss_add_cred()\fR function adds a credential-element to a credential. The credential-element is identified by the name of the principal to which it refers. This function is not intended as a function to login to the network. A function for login to the network would involve creating new mechanism-specific authentication data, rather than acquiring a handle to existing data.
+.sp
+.LP
+If the value of \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is interpreted as a request to add a credential-element to invoke default behavior when passed to \fBgss_init_sec_context\fR(3GSS) if the value of \fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR. The call is also interpreted as a request to add a credential-element to the invoke default behavior when passed to \fBgss_accept_sec_context\fR(3GSS) if the value of \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR.
+.sp
+.LP
+The \fBgss_add_cred()\fR function is expected to be used primarily by context acceptors. The \fBGSS-API\fR provides mechanism-specific ways to obtain \fBGSS-API\fR initiator credentials through the system login process. Consequently, the \fBGSS-API\fR does not support acquiring \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred\fR(3GSS) for any name other than the following:
+.RS +4
+.TP
+.ie t \(bu
+.el o
+\fBGSS_C_NO_NAME\fR
+.RE
+.RS +4
+.TP
+.ie t \(bu
+.el o
+Name produced by \fBgss_inquire_cred\fR(3GSS) applied to a valid credential
+.RE
+.RS +4
+.TP
+.ie t \(bu
+.el o
+Name produced by \fBgss_inquire_context\fR(3GSS) applied to an active context
+.RE
+.sp
+.LP
+If credential acquisition is time consuming for a mechanism, the mechanism can choose to delay the actual acquisition until the credential is required by \fBgss_init_sec_context\fR(3GSS), for example, or by \fBgss_accept_sec_context\fR(3GSS). Such mechanism-specific implementation decisions are invisible to the calling application. A call to \fBgss_inquire_cred\fR(3GSS) immediately following the call \fBgss_add_cred()\fR returns valid credential data as well as incurring the overhead of deferred credential acquisition.
+.sp
+.LP
+The \fBgss_add_cred()\fR function can be used either to compose a new credential that contains all credential-elements of the original in addition to the newly-acquired credential-element. The function can also be used to add the new credential-element to an existing credential. If the value of the \fIoutput_cred_handle\fR parameter is \fBNULL\fR, the new credential-element is added to the credential identified by \fIinput_cred_handle\fR. If a valid pointer is specified for the \fIoutput_cred_handle\fR parameter, a new credential handle is created.
+.sp
+.LP
+If the value of \fIinput_cred_handle\fR is \fBGSS_C_NO_CREDENTIAL\fR, the \fBgss_add_cred()\fR function composes a credential and sets the \fIoutput_cred_handle\fR parameter based on the default behavior. The call has the same effect as a call first made by the application to \fBgss_acquire_cred\fR(3GSS) to specify the same usage and to pass \fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR parameter. Such an application call obtains an explicit credential handle that incorporates the default behaviors, then passes the credential handle to \fBgss_add_cred()\fR, and finally calls \fBgss_release_cred\fR(3GSS) on the first credential handle.
+.sp
+.LP
+If the value of the \fIinput_cred_handle\fR parameter is \fBGSS_C_NO_CREDENTIAL\fR, a non-\fBNULL\fR value must be supplied for the \fIoutput_cred_handle\fR parameter.
+.SH RETURN VALUES
+.sp
+.LP
+The \fBgss_add_cred()\fR function can return the following status codes:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_COMPLETE\fR\fR
+.ad
+.RS 29n
+.rt  
+Successful completion.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_BAD_MECH\fR\fR
+.ad
+.RS 29n
+.rt  
+An unavailable mechanism has been requested.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_BAD_NAMETYPE\fR\fR
+.ad
+.RS 29n
+.rt  
+The type contained within the \fIdesired_name\fR parameter is not supported.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_BAD_NAME\fR\fR
+.ad
+.RS 29n
+.rt  
+The value supplied for \fIdesired_name\fR parameter is ill formed.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR
+.ad
+.RS 29n
+.rt  
+The credential already contains an element for the requested mechanism that has overlapping usage and validity period.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
+.ad
+.RS 29n
+.rt  
+The credentials could not be added because they have expired.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_NO_CRED\fR\fR
+.ad
+.RS 29n
+.rt  
+No credentials were found for the specified name.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBGSS_S_FAILURE\fR\fR
+.ad
+.RS 29n
+.rt  
+The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined. The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.
+.RE
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+MT-LevelSafe
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBgss_accept_sec_context\fR(3GSS), \fBgss_acquire_cred\fR(3GSS), \fBgss_init_sec_context\fR(3GSS), \fBgss_inquire_context\fR(3GSS), \fBgss_inquire_cred\fR(3GSS), \fBgss_release_cred\fR(3GSS), \fBgss_release_oid_set\fR(3GSS), \fBlibgss\fR(3LIB), \fBattributes\fR(5)
+.sp
+.LP
+\fI\fR
upstream/oracle/userland-gate