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_acquire_cred.3gss
changeset 5490 9bf0bc57423a
child 7820 a2b9a7de9e1a 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/krb5/Solaris/man/gss_acquire_cred.3gss	Wed Feb 24 10:43:57 2016 -0600
@@ -0,0 +1,231 @@
+'\" te
+.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
+.TH gss_acquire_cred 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions"
+.SH NAME
+gss_acquire_cred \- acquire a handle for a pre-existing credential by name
+.SH SYNOPSIS
+.LP
+.nf
+\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 
+#include <gssapi/gssapi.h>
+
+\fBOM_uint32\fR \fBgss_acquire_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
+     \fBconst gss_name_t\fR \fIdesired_name\fR, \fBOM_uint32\fR \fItime_req\fR,
+     \fBconst gss_OID_set\fR \fIdesired_mech\fR, \fBgss_cred_usage_t\fR \fIcred_usage\fR,
+     \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR, \fBgss_OID_set *\fR\fIactual_mechs\fR,
+     \fBOM_uint32 *\fR\fItime_rec\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBgss_acquire_cred()\fR function allows an application to acquire a handle for a pre-existing credential by name. This routine is not intended as a function to login to the network; a function for login to the network would involve creating new credentials rather than merely acquiring a handle to existing credentials.
+.sp
+.LP
+If \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to \fBgss_init_sec_context\fR(3GSS) (if \fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR) or \fBgss_accept_sec_context\fR(3GSS) (if \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR). 
+.sp
+.LP
+Normally \fBgss_acquire_cred()\fR returns a credential that is valid only for the mechanisms requested by the \fIdesired_mechs\fR argument. However, if multiple mechanisms can share a single credential element, the function returns all the mechanisms for which the credential is valid in the \fIactual_mechs\fR argument.
+.sp
+.LP
+\fBgss_acquire_cred()\fR is intended to be used primarily by context  acceptors, since the \fBGSS-API\fR routines obtain initiator credentials through the system login process. Accordingly, you may not acquire \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred()\fR for any name other than \fBGSS_C_NO_NAME\fR. Alternatively, you may acquire \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials for a name produced when \fBgss_inquire_cred\fR(3GSS) is applied to a valid credential, or when \fBgss_inquire_context\fR(3GSS) is applied to an active context. 
+.sp
+.LP
+If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required, for example, by \fBgss_init_sec_context\fR(3GSS) or by \fBgss_accept_sec_context\fR(3GSS).  Such mechanism-specific implementations are, however, invisible to the calling application; thus a call of \fBgss_inquire_cred\fR(3GSS) immediately following the call of \fBgss_acquire_cred()\fR will return valid credential data and incur the overhead of a deferred credential acquisition.  
+.SH PARAMETERS
+.sp
+.LP
+The parameter descriptions for \fBgss_acquire_cred()\fR follow:
+.sp
+.ne 2
+.mk
+.na
+\fB\fIdesired_name\fR\fR
+.ad
+.RS 22n
+.rt  
+The name of the principal for which a credential should be acquired.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fItime_req\fR\fR
+.ad
+.RS 22n
+.rt  
+The number of seconds that credentials remain valid. Specify \fBGSS_C_INDEFINITE\fR  to request that the credentials have the maximum permitted lifetime
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIdesired_mechs\fR\fR
+.ad
+.RS 22n
+.rt  
+The set of underlying security mechanisms that may be used.  \fBGSS_C_NO_OID_SET\fR may be used to obtain a default.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIcred_usage\fR\fR
+.ad
+.RS 22n
+.rt  
+A flag that indicates how this credential should be used. If the flag is \fBGSS_C_ACCEPT\fR, then credentials will be used only to accept security credentials. \fBGSS_C_INITIATE\fR indicates that credentials will be used only to initiate security credentials. If the flag is \fBGSS_C_BOTH\fR, then credentials may be used either to initiate or accept security contexts. 
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIoutput_cred_handle\fR\fR
+.ad
+.RS 22n
+.rt  
+The returned credential handle.  Resources associated with this credential handle must be released by the application after use with a call to \fBgss_release_cred\fR(3GSS)
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIactual_mechs\fR\fR
+.ad
+.RS 22n
+.rt  
+The set of mechanisms for which the credential is valid.  Storage associated with the returned \fBOID\fR-set must be released by the application after use with a call to  \fBgss_release_oid_set\fR(3GSS).  Specify \fBNULL\fR if not required.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fItime_rec\fR\fR
+.ad
+.RS 22n
+.rt  
+Actual number of seconds for which the returned credentials will remain valid. Specify \fBNULL\fR if not required.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIminor_status\fR\fR
+.ad
+.RS 22n
+.rt  
+Mechanism specific status code.
+.RE
+
+.SH ERRORS
+.sp
+.LP
+\fBgss_acquire_cred()\fR may return the following status code:
+.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_CREDENTIALS_EXPIRED\fR\fR
+.ad
+.RS 29n
+.rt  
+The credentials could not be acquired 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_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), \fBattributes\fR(5)
+.sp
+.LP
+
upstream/oracle/userland-gate