1gss_acquire_cred(G3eGnSeSr)ic Security Services API Library Fungcstsi_oancsquire_cred(3GSS)
2
6 gss_acquire_cred - acquire a handle for a pre-existing credential by
7 name
8
10 cc [ flag... ] file... -lgss [ library... ]
11 #include <gssapi/gssapi.h>
12 OM_uint32 gss_acquire_cred(OM_uint32 *minor_status,
14 const gss_name_t *desired_name, OM_uint32 time_req,
15 const gss_OID_set desired_mech, gss_cred_usage_t cred_usage,
16 gss_cred_id_t * output_cred_handle, gss_OID_set *actual_mechs,
17 OM_uint32 *time_rec);
18
21 The gss_acquire_cred() function allows an application to acquire a han‐
22 dle for a pre-existing credential by name. This routine is not intended
23 as a function to login to the network; a function for login to the net‐
24 work would involve creating new credentials rather than merely acquir‐
25 ing a handle to existing credentials.
26 If desired_name is GSS_C_NO_NAME, the call is interpreted as a request
29 for a credential handle that will invoke default behavior when passed
30 to gss_init_sec_context(3GSS) (if cred_usage is GSS_C_INITIATE or
31 GSS_C_BOTH) or gss_accept_sec_context(3GSS) (if cred_usage is
32 GSS_C_ACCEPT or GSS_C_BOTH).
33 Normally gss_acquire_cred() returns a credential that is valid only for
36 the mechanisms requested by the desired_mechs argument. However, if
37 multiple mechanisms can share a single credential element, the function
38 returns all the mechanisms for which the credential is valid in the
39 actual_mechs argument.
40 gss_acquire_cred() is intended to be used primarily by context accep‐
43 tors, since the GSS-API routines obtain initiator credentials through
44 the system login process. Accordingly, you may not acquire GSS_C_INITI‐
45 ATE or GSS_C_BOTH credentials by means of gss_acquire_cred() for any
46 name other than GSS_C_NO_NAME. Alternatively, you may acquire
47 GSS_C_INITIATE or GSS_C_BOTH credentials for a name produced when
48 gss_inquire_cred(3GSS) is applied to a valid credential, or when
49 gss_inquire_context(3GSS) is applied to an active context.
50 If credential acquisition is time-consuming for a mechanism, the mecha‐
53 nism may choose to delay the actual acquisition until the credential is
54 required, for example, by gss_init_sec_context(3GSS) or by
55 gss_accept_sec_context(3GSS). Such mechanism-specific implementations
56 are, however, invisible to the calling application; thus a call of
57 gss_inquire_cred(3GSS) immediately following the call of
58 gss_acquire_cred() will return valid credential data and incur the
59 overhead of a deferred credential acquisition.
60
62 The parameter descriptions for gss_acquire_cred() follow:
63 desired_name The name of the principal for which a credential
65 should be acquired.
66 time_req The number of seconds that credentials remain
69 valid. Specify GSS_C_INDEFINITE to request that
70 the credentials have the maximum permitted life‐
71 time
72 desired_mechs The set of underlying security mechanisms that
75 may be used. GSS_C_NO_OID_SET may be used to
76 obtain a default.
77 cred_usage A flag that indicates how this credential should
80 be used. If the flag is GSS_C_ACCEPT, then cre‐
81 dentials will be used only to accept security
82 credentials. GSS_C_INITIATE indicates that cre‐
83 dentials will be used only to initiate security
84 credentials. If the flag is GSS_C_BOTH, then cre‐
85 dentials may be used either to initiate or accept
86 security contexts.
87 output_cred_handle The returned credential handle. Resources asso‐
90 ciated with this credential handle must be
91 released by the application after use with a call
92 to gss_release_cred(3GSS)
93 actual_mechs The set of mechanisms for which the credential is
96 valid. Storage associated with the returned OID-
97 set must be released by the application after use
98 with a call to gss_release_oid_set(3GSS). Spec‐
99 ify NULL if not required.
100 time_rec Actual number of seconds for which the returned
103 credentials will remain valid. Specify NULL if
104 not required.
105 minor_status Mechanism specific status code.
108
111 gss_acquire_cred() may return the following status code:
112 GSS_S_COMPLETE Successful completion.
114 GSS_S_BAD_MECH An unavailable mechanism has been
117 requested.
118 GSS_S_BAD_NAMETYPE The type contained within the desired_name
121 parameter is not supported.
122 GSS_S_BAD_NAME The value supplied for desired_name param‐
125 eter is ill formed.
126 GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired
129 because they have expired.
130 GSS_S_NO_CRED No credentials were found for the speci‐
133 fied name.
134 GSS_S_FAILURE The underlying mechanism detected an error
137 for which no specific GSS status code is
138 defined. The mechanism-specific status
139 code reported by means of the minor_status
140 parameter details the error condition.
141
144 See attributes(5) for descriptions of the following attributes:
145 ┌─────────────────────────────┬─────────────────────────────┐
150 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
151 ├─────────────────────────────┼─────────────────────────────┤
152 │Availability │SUNWgss (32-bit) │
153 ├─────────────────────────────┼─────────────────────────────┤
154 │ │SUNWgssx (64-bit) │
155 ├─────────────────────────────┼─────────────────────────────┤
156 │MT-Level │Safe │
157 └─────────────────────────────┴─────────────────────────────┘
158
160 gss_accept_sec_context(3GSS), gss_init_sec_context(3GSS),
161 gss_inquire_context(3GSS), gss_inquire_cred(3GSS),
162 gss_release_cred(3GSS), gss_release_oid_set(3GSS), attributes(5)
163 Solaris Security for Developers Guide
166SunOS 5.11 14 Jan 2003 gss_acquire_cred(3GSS)