lib/libgssapi/gss_acquire_cred.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2005 Doug Rabson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\"     $FreeBSD$
  28 .\"
  29 .\" The following commands are required for all man pages.
  30 .Dd January 26, 2010
  31 .Dt GSS_ACQUIRE_CRED 3 PRM
  32 .Os
  33 .Sh NAME
  34 .Nm gss_acquire_cred
  35 .Nd Obtain a GSS-API credential handle for pre-existing credentials
  36 .\" This next command is for sections 2 and 3 only.
  37 .\" .Sh LIBRARY
  38 .Sh SYNOPSIS
  39 .In "gssapi/gssapi.h"
  40 .Ft OM_uint32
  41 .Fo gss_acquire_cred
  42 .Fa "OM_uint32 *minor_status"
  43 .Fa "const gss_name_t desired_name"
  44 .Fa "OM_uint32 time_req"
  45 .Fa "const gss_OID_set desired_mechs"
  46 .Fa "gss_cred_usage_t cred_usage"
  47 .Fa "gss_cred_id_t *output_cred_handle"
  48 .Fa "gss_OID_set *actual_mechs"
  49 .Fa "OM_uint32 *time_rec"
  50 .Fc
  51 .Sh DESCRIPTION
  52 Allows an application to acquire a handle for a pre-existing
  53 credential by name.
  54 GSS-API implementations must impose a local
  55 access-control policy on callers of this routine to prevent
  56 unauthorized callers from acquiring credentials to which they are not
  57 entitled.
  58 This routine is not intended to provide a "login to the
  59 network" function, as such a function would involve the creation of
  60 new credentials rather than merely acquiring a handle to existing
  61 credentials.
  62 Such functions, if required, should be defined in
  63 implementation-specific extensions to the API.
  64 .Pp
  65 If desired_name is
  66 .Dv GSS_C_NO_NAME ,
  67 the call is interpreted as a
  68 request for a credential handle that will invoke default behavior
  69 when passed to
  70 .Fn gss_init_sec_context
  71 (if cred_usage is
  72 .Dv GSS_C_INITIATE
  73 or
  74 .Dv GSS_C_BOTH )
  75 or
  76 .Fn gss_accept_sec_context
  77 (if cred_usage is
  78 .Dv GSS_C_ACCEPT
  79 or
  80 .Dv GSS_C_BOTH ).
  81 .Pp
  82 Mechanisms should honor the
  83 .Fa desired_mechs
  84 parameter,
  85 and return a credential that is suitable to use only with the
  86 requested mechanisms.
  87 An exception to this is the case where one underlying credential
  88 element can be shared by multiple mechanisms;
  89 in this case it is permissible for an implementation to indicate all
  90 mechanisms with which the credential element may be used.
  91 If
  92 .Fa desired_mechs
  93 is an empty set, behavior is undefined.
  94 .Pp
  95 This routine is expected to be used primarily by context acceptors,
  96 since implementations are likely to provide mechanism-specific ways
  97 of obtaining GSS-API initiator credentials from the system login
  98 process.
  99 Some implementations may therefore not support the acquisition of
 100 .Dv GSS_C_INITIATE
 101 or
 102 .Dv GSS_C_BOTH
 103 credentials via
 104 .Fn gss_acquire_cred
 105 for any name other than
 106 .Dv GSS_C_NO_NAME ,
 107 or a name produced by applying either
 108 .Fn gss_inquire_cred
 109 to a valid credential, or
 110 .Fn gss_inquire_context
 111 to an active context.
 112 .Pp
 113 If credential acquisition is time-consuming for a mechanism,
 114 the mechanism may choose to delay the actual acquisition until the
 115 credential is required
 116 (e.g. by
 117 .Fn gss_init_sec_context
 118 or
 119 .Fn gss_accept_sec_context ).
 120 Such mechanism-specific implementation
 121 decisions should be invisible to the calling application;
 122 thus a call of
 123 .Fn gss_inquire_cred
 124 immediately following the call of
 125 .Fn gss_acquire_cred
 126 must return valid credential data,
 127 and may therefore incur the overhead of a deferred credential acquisition.
 128 .Sh PARAMETERS
 129 .Bl -tag -width ".It output_cred_handle"
 130 .It desired_name
 131 Name of principal whose credential should be acquired.
 132 .It time_req
 133 Number of seconds that credentials should remain valid.
 134 Specify
 135 .Dv GSS_C_INDEFINITE
 136 to request that the credentials have the maximum
 137 permitted lifetime.
 138 .It desired_mechs
 139 Set of underlying security mechanisms that may be used.
 140 .Dv GSS_C_NO_OID_SET
 141 may be used to obtain an implementation-specific default.
 142 .It cred_usage
 143 .Bl -tag -width "GSS_C_INITIATE"
 144 .It GSS_C_BOTH
 145 Credentials may be used either to initiate or accept security
 146 contexts.
 147 .It GSS_C_INITIATE
 148 Credentials will only be used to initiate security contexts.
 149 .It GSS_C_ACCEPT
 150 Credentials will only be used to accept security contexts.
 151 .El
 152 .It output_cred_handle
 153 The returned credential handle.
 154 Resources
 155 associated with this credential handle must be released by
 156 the application after use with a call to
 157 .Fn gss_release_cred .
 158 .It actual_mechs
 159 The set of mechanisms for which the credential is valid.
 160 Storage associated with the returned OID-set must be released by the
 161 application after use with a call to
 162 .Fn gss_release_oid_set .
 163 Specify
 164 .Dv NULL if not required.
 165 .It time_rec
 166 Actual number of seconds for which the returned credentials will
 167 remain valid.
 168 If the implementation does not support expiration of credentials,
 169 the value
 170 .Dv GSS_C_INDEFINITE
 171 will be returned.
 172 Specify NULL if not required.
 173 .It minor_status
 174 Mechanism specific status code.
 175 .El
 176 .Sh RETURN VALUES
 177 .Bl -tag -width ".It GSS_S_CREDENTIALS_EXPIRED"
 178 .It GSS_S_COMPLETE
 179 Successful completion.
 180 .It GSS_S_BAD_MECH
 181 Unavailable mechanism requested.
 182 .It GSS_S_BAD_NAMETYPE
 183 Type contained within desired_name parameter is not supported.
 184 .It GSS_S_BAD_NAME
 185 Value supplied for desired_name parameter is ill formed.
 186 .It GSS_S_CREDENTIALS_EXPIRED
 187 The credentials could not be acquired because they have expired.
 188 .It GSS_S_NO_CRED
 189 No credentials were found for the specified name.
 190 .El
 191 .Sh SEE ALSO
 192 .Xr gss_init_sec_context 3 ,
 193 .Xr gss_accept_sec_context 3 ,
 194 .Xr gss_inquire_cred 3 ,
 195 .Xr gss_inquire_context 3 ,
 196 .Xr gss_release_cred 3 ,
 197 .Xr gss_release_oid_set 3
 198 .Sh STANDARDS
 199 .Bl -tag -width ".It RFC 2743"
 200 .It RFC 2743
 201 Generic Security Service Application Program Interface Version 2, Update 1
 202 .It RFC 2744
 203 Generic Security Service API Version 2 : C-bindings
 204 .El
 205 .Sh HISTORY
 206 The
 207 .Nm
 208 function first appeared in
 209 .Fx 7.0 .
 210 .Sh AUTHORS
 211 John Wray, Iris Associates
 212 .Sh COPYRIGHT
 213 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 214 .Pp
 215 This document and translations of it may be copied and furnished to
 216 others, and derivative works that comment on or otherwise explain it
 217 or assist in its implementation may be prepared, copied, published
 218 and distributed, in whole or in part, without restriction of any
 219 kind, provided that the above copyright notice and this paragraph are
 220 included on all such copies and derivative works.  However, this
 221 document itself may not be modified in any way, such as by removing
 222 the copyright notice or references to the Internet Society or other
 223 Internet organizations, except as needed for the purpose of
 224 developing Internet standards in which case the procedures for
 225 copyrights defined in the Internet Standards process must be
 226 followed, or as required to translate it into languages other than
 227 English.
 228 .Pp
 229 The limited permissions granted above are perpetual and will not be
 230 revoked by the Internet Society or its successors or assigns.
 231 .Pp
 232 This document and the information contained herein is provided on an
 233 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 234 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 235 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 236 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 237 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.