usr/src/man/man3gss/gss_acquire_cred.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GSS_ACQUIRE_CRED 3GSS "Jan 14, 2003"
   7 .SH NAME
   8 gss_acquire_cred \- acquire a handle for a pre-existing credential by name
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_acquire_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_name_t *\fR\fIdesired_name\fR, \fBOM_uint32\fR \fItime_req\fR,
  17      \fBconst gss_OID_set\fR \fIdesired_mech\fR, \fBgss_cred_usage_t\fR \fIcred_usage\fR,
  18      \fBgss_cred_id_t *\fR \fIoutput_cred_handle\fR, \fBgss_OID_set *\fR\fIactual_mechs\fR,
  19      \fBOM_uint32 *\fR\fItime_rec\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBgss_acquire_cred()\fR function allows an application to acquire a handle
  26 for a pre-existing credential by name. This routine is not intended as a
  27 function to login to the network; a function for login to the network would
  28 involve creating new credentials rather than merely acquiring a handle to
  29 existing credentials.
  30 .sp
  31 .LP
  32 If \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is interpreted as a
  33 request for a credential handle that will invoke default behavior when passed
  34 to \fBgss_init_sec_context\fR(3GSS) (if \fIcred_usage\fR is
  35 \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR) or \fBgss_accept_sec_context\fR(3GSS)
  36 (if \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR).
  37 .sp
  38 .LP
  39 Normally \fBgss_acquire_cred()\fR returns a credential that is valid only for
  40 the mechanisms requested by the \fIdesired_mechs\fR argument. However, if
  41 multiple mechanisms can share a single credential element, the function returns
  42 all the mechanisms for which the credential is valid in the \fIactual_mechs\fR
  43 argument.
  44 .sp
  45 .LP
  46 \fBgss_acquire_cred()\fR is intended to be used primarily by context
  47 acceptors, since the \fBGSS-API\fR routines obtain initiator credentials
  48 through the system login process. Accordingly, you may not acquire
  49 \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials by means of
  50 \fBgss_acquire_cred()\fR for any name other than \fBGSS_C_NO_NAME\fR.
  51 Alternatively, you may acquire \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR
  52 credentials for a name produced when \fBgss_inquire_cred\fR(3GSS) is applied to
  53 a valid credential, or when \fBgss_inquire_context\fR(3GSS) is applied to an
  54 active context.
  55 .sp
  56 .LP
  57 If credential acquisition is time-consuming for a mechanism, the mechanism may
  58 choose to delay the actual acquisition until the credential is required, for
  59 example, by \fBgss_init_sec_context\fR(3GSS) or by
  60 \fBgss_accept_sec_context\fR(3GSS).  Such mechanism-specific implementations
  61 are, however, invisible to the calling application; thus a call of
  62 \fBgss_inquire_cred\fR(3GSS) immediately following the call of
  63 \fBgss_acquire_cred()\fR will return valid credential data and incur the
  64 overhead of a deferred credential acquisition.
  65 .SH PARAMETERS
  66 .sp
  67 .LP
  68 The parameter descriptions for \fBgss_acquire_cred()\fR follow:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIdesired_name\fR\fR
  73 .ad
  74 .RS 22n
  75 The name of the principal for which a credential should be acquired.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fItime_req\fR\fR
  82 .ad
  83 .RS 22n
  84 The number of seconds that credentials remain valid. Specify
  85 \fBGSS_C_INDEFINITE\fR  to request that the credentials have the maximum
  86 permitted lifetime
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fIdesired_mechs\fR\fR
  93 .ad
  94 .RS 22n
  95 The set of underlying security mechanisms that may be used.
  96 \fBGSS_C_NO_OID_SET\fR may be used to obtain a default.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fIcred_usage\fR\fR
 103 .ad
 104 .RS 22n
 105 A flag that indicates how this credential should be used. If the flag is
 106 \fBGSS_C_ACCEPT\fR, then credentials will be used only to accept security
 107 credentials. \fBGSS_C_INITIATE\fR indicates that credentials will be used only
 108 to initiate security credentials. If the flag is \fBGSS_C_BOTH\fR, then
 109 credentials may be used either to initiate or accept security contexts.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIoutput_cred_handle\fR\fR
 116 .ad
 117 .RS 22n
 118 The returned credential handle.  Resources associated with this credential
 119 handle must be released by the application after use with a call to
 120 \fBgss_release_cred\fR(3GSS)
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fIactual_mechs\fR\fR
 127 .ad
 128 .RS 22n
 129 The set of mechanisms for which the credential is valid.  Storage associated
 130 with the returned \fBOID\fR-set must be released by the application after use
 131 with a call to  \fBgss_release_oid_set\fR(3GSS).  Specify \fBNULL\fR if not
 132 required.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fItime_rec\fR\fR
 139 .ad
 140 .RS 22n
 141 Actual number of seconds for which the returned credentials will remain valid.
 142 Specify \fBNULL\fR if not required.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fIminor_status\fR\fR
 149 .ad
 150 .RS 22n
 151 Mechanism specific status code.
 152 .RE
 153
 154 .SH ERRORS
 155 .sp
 156 .LP
 157 \fBgss_acquire_cred()\fR may return the following status code:
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBGSS_S_COMPLETE\fR\fR
 162 .ad
 163 .RS 29n
 164  Successful completion.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBGSS_S_BAD_MECH\fR\fR
 171 .ad
 172 .RS 29n
 173 An unavailable mechanism has been requested.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBGSS_S_BAD_NAMETYPE\fR\fR
 180 .ad
 181 .RS 29n
 182 The type contained within the \fIdesired_name\fR parameter is not supported.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBGSS_S_BAD_NAME\fR\fR
 189 .ad
 190 .RS 29n
 191 The value supplied for \fIdesired_name\fR parameter is ill formed.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
 198 .ad
 199 .RS 29n
 200 The credentials could not be acquired because they have expired.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBGSS_S_NO_CRED\fR\fR
 207 .ad
 208 .RS 29n
 209 No credentials were found for the specified name.
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBGSS_S_FAILURE\fR\fR
 216 .ad
 217 .RS 29n
 218 The underlying mechanism detected an error for which no specific \fBGSS\fR
 219 status code is defined.  The mechanism-specific status code reported by means
 220 of the \fIminor_status\fR parameter details the error condition.
 221 .RE
 222
 223 .SH ATTRIBUTES
 224 .sp
 225 .LP
 226 See \fBattributes\fR(5)  for descriptions of the following attributes:
 227 .sp
 228
 229 .sp
 230 .TS
 231 box;
 232 c | c
 233 l | l .
 234 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 235 _
 236 MT-Level        Safe
 237 .TE
 238
 239 .SH SEE ALSO
 240 .sp
 241 .LP
 242 \fBgss_accept_sec_context\fR(3GSS), \fBgss_init_sec_context\fR(3GSS),
 243 \fBgss_inquire_context\fR(3GSS), \fBgss_inquire_cred\fR(3GSS),
 244 \fBgss_release_cred\fR(3GSS), \fBgss_release_oid_set\fR(3GSS),
 245 \fBattributes\fR(5)
 246 .sp
 247 .LP
 248 \fISolaris Security for Developers Guide\fR