lib/libgssapi/gss_add_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 .\" The following commands are required for all man pages.
  28 .Dd January 26, 2010
  29 .Dt GSS_ADD_CRED 3 PRM
  30 .Os
  31 .Sh NAME
  32 .Nm gss_add_cred
  33 .Nd Construct credentials incrementally
  34 .\" This next command is for sections 2 and 3 only.
  35 .\" .Sh LIBRARY
  36 .Sh SYNOPSIS
  37 .In "gssapi/gssapi.h"
  38 .Ft OM_uint32
  39 .Fo gss_add_cred
  40 .Fa "OM_uint32 *minor_status"
  41 .Fa "const gss_cred_id_t input_cred_handle"
  42 .Fa "const gss_name_t desired_name"
  43 .Fa "const gss_OID desired_mech"
  44 .Fa "gss_cred_usage_t cred_usage"
  45 .Fa "OM_uint32 initiator_time_req"
  46 .Fa "OM_uint32 acceptor_time_req"
  47 .Fa "gss_cred_id_t *output_cred_handle"
  48 .Fa "gss_OID_set *actual_mechs"
  49 .Fa "OM_uint32 *initiator_time_rec"
  50 .Fa "OM_uint32 *acceptor_time_rec"
  51 .Fc
  52 .Sh DESCRIPTION
  53 Adds a credential-element to a credential.
  54 The credential-element is identified by the name of the principal to
  55 which it refers.
  56 GSS-API implementations must impose a local access-control policy on
  57 callers of this routine to prevent unauthorized callers from acquiring
  58 credential-elements to which they are not entitled.
  59 This routine is not intended to provide a "login to the network"
  60 function,
  61 as such a function would involve the creation of new
  62 mechanism-specific authentication data,
  63 rather than merely acquiring a GSS-API handle to existing data.
  64 Such functions,
  65 if required,
  66 should be defined in implementation-specific extensions to the API.
  67 .Pp
  68 If
  69 .Fa desired_name
  70 is
  71 .Dv GSS_C_NO_NAME ,
  72 the call is interpreted as a request to add a credential element that
  73 will invoke default behavior when passed to
  74 .Fn gss_init_sec_context
  75 (if cred_usage is
  76 .Dv GSS_C_INITIATE
  77 or
  78 .Dv GSS_C_BOTH )
  79 or
  80 .Fn gss_accept_sec_context
  81 (if
  82 .Fa cred_usage
  83 is
  84 .Dv GSS_C_ACCEPT
  85 or
  86 .Dv GSS_C_BOTH ).
  87 .Pp
  88 This routine is expected to be used primarily by context acceptors,
  89 since implementations are likely to provide mechanism-specific ways of
  90 obtaining GSS-API initiator credentials from the system login process.
  91 Some implementations may therefore not support the acquisition of
  92 .Dv GSS_C_INITIATE
  93 or
  94 .Dv GSS_C_BOTH
  95 credentials via
  96 .Fn gss_acquire_cred
  97 for any name other than
  98 .Dv GSS_C_NO_NAME ,
  99 or a name produced by applying either
 100 .Fn gss_inquire_cred
 101 to a valid credential,
 102 or
 103 .Fn gss_inquire_context
 104 to an active context.
 105 .Pp
 106 If credential acquisition is time-consuming for a mechanism,
 107 the mechanism may choose to delay the actual acquisition until the
 108 credential is required (e.g. by
 109 .Fn gss_init_sec_context
 110 or
 111 .Fn gss_accept_sec_context ).
 112 Such mechanism-specific implementation decisions should be invisible
 113 to the calling application;
 114 thus a call of
 115 .Fn gss_inquire_cred
 116 immediately following the call of
 117 .Fn gss_add_cred
 118 must return valid credential data,
 119 and may therefore incur the overhead of a deferred credential acquisition.
 120 .Pp
 121 This routine can be used to either compose a new credential containing
 122 all credential-elements of the original in addition to the
 123 newly-acquire credential-element,
 124 or to add the new credential-element to an existing credential.
 125 If
 126 .Dv NULL
 127 is specified for the
 128 .Fa output_cred_handle
 129 parameter argument,
 130 the new credential-element will be added to the credential identified
 131 by
 132 .Fa input_cred_handle ;
 133 if a valid pointer is specified for the
 134 .Fa output_cred_handle
 135 parameter,
 136 a new credential handle will be created.
 137 .Pp
 138 If
 139 .Dv GSS_C_NO_CREDENTIAL
 140 is specified as the
 141 .Fa input_cred_handle ,
 142 .Fn gss_add_cred
 143 will compose a credential (and set the
 144 .Fa output_cred_handle
 145 parameter accordingly) based on default behavior.
 146 That is, the call will have the same effect as if the application had
 147 first made a call to
 148 .Fn gss_acquire_cred ,
 149 specifying the same usage and passing
 150 .Dv GSS_C_NO_NAME
 151 as the
 152 .Fa desired_name
 153 parameter to obtain an explicit credential handle embodying default
 154 behavior,
 155 passed this credential handle to
 156 .Fn gss_add_cred ,
 157 and finally called
 158 .Fn gss_release_cred
 159 on the first credential handle.
 160 .Pp
 161 If
 162 .Dv GSS_C_NO_CREDENTIAL
 163 is specified as the
 164 .Fa input_cred_handle
 165 parameter,
 166 a non-
 167 .Dv NULL
 168 .Fa output_cred_handle
 169 must be supplied.
 170 .Sh PARAMETERS
 171 .Bl -tag -width ".It output_cred_handle"
 172 .It minor_status
 173 Mechanism specific status code.
 174 .It input_cred_handle
 175 The credential to which a credential-element will be added.
 176 If
 177 .Dv GSS_C_NO_CREDENTIAL
 178 is specified, the routine will compose the new credential based on
 179 default behavior (see description above).
 180 Note that, while the credential-handle is not modified by
 181 .Fn gss_add_cred ,
 182 the underlying credential will be modified if
 183 .Fa output_credential_handle
 184 is
 185 .Dv NULL .
 186 .It desired_name
 187 Name of principal whose credential should be acquired.
 188 .It desired_mech
 189 Underlying security mechanism with which the credential may be used.
 190 .It cred_usage
 191 .Bl -tag -width "GSS_C_INITIATE"
 192 .It GSS_C_BOTH
 193 Credential may be used either to initiate or accept security
 194 contexts.
 195 .It GSS_C_INITIATE
 196 Credential will only be used to initiate security contexts.
 197 .It GSS_C_ACCEPT
 198 Credential will only be used to accept security contexts.
 199 .El
 200 .It initiator_time_req
 201 Number of seconds that the credential should remain valid for
 202 initiating security contexts.
 203 This argument is ignored if the composed credentials are of type
 204 .Dv GSS_C_ACCEPT .
 205 Specify
 206 .Dv GSS_C_INDEFINITE
 207 to request that the credentials have the maximum permitted initiator lifetime.
 208 .It acceptor_time_req
 209 Number of seconds that the credential should remain valid for
 210 accepting security contexts.
 211 This argument is ignored if the composed credentials are of type
 212 .Dv GSS_C_INITIATE .
 213 Specify
 214 .Dv GSS_C_INDEFINITE
 215 to request that the credentials have the maximum permitted initiator lifetime.
 216 .It output_cred_handle
 217 The returned credential handle,
 218 containing
 219 the new credential-element and all the credential-elements from
 220 .Fa input_cred_handle .
 221 If a valid pointer to a
 222 .Fa gss_cred_id_t
 223 is supplied for this parameter,
 224 .Fn gss_add_cred
 225 creates a new credential handle containing all credential-elements
 226 from the
 227 .Fa input_cred_handle
 228 and the newly acquired credential-element;
 229 if
 230 .Dv NULL
 231 is specified for this parameter,
 232 the newly acquired credential-element will be added to the credential
 233 identified by
 234 .Fa input_cred_handle .
 235 .Pp
 236 The resources associated with any credential handle returned via this
 237 parameter must be released by the application after use with a call to
 238 .Fn gss_release_cred .
 239 .It actual_mechs
 240 The complete set of mechanisms for which the new credential is valid.
 241 Storage for the returned OID-set must be freed by the application
 242 after use with a call to
 243 .Fn gss_release_oid_set .
 244 Specify
 245 .Dv NULL if not required.
 246 .It initiator_time_rec
 247 Actual number of seconds for which the returned credentials will
 248 remain valid for initiating contexts using the specified mechanism.
 249 If the implementation or mechanism does not support expiration of
 250 credentials,
 251 the value
 252 .Dv GSS_C_INDEFINITE
 253 will be returned.
 254 Specify
 255 .Dv NULL
 256 if not required.
 257 .It acceptor_time_rec
 258 Actual number of seconds for which the returned credentials will
 259 remain valid for accepting security contexts using the specified
 260 mechanism.
 261 If the implementation or mechanism does not support expiration of
 262 credentials,
 263 the value
 264 .Dv GSS_C_INDEFINITE
 265 will be returned.
 266 Specify
 267 .Dv NULL
 268 if not required.
 269 .El
 270 .Sh RETURN VALUES
 271 .Bl -tag -width ".It GSS_S_CREDENTIALS_EXPIRED"
 272 .It GSS_S_COMPLETE
 273 Successful completion.
 274 .It GSS_S_BAD_MECH
 275 Unavailable mechanism requested.
 276 .It GSS_S_BAD_NAMETYPE
 277 Type contained within desired_name parameter is not supported
 278 .It GSS_S_BAD_NAME
 279 Value supplied for desired_name parameter is ill-formed.
 280 .It GSS_S_DUPLICATE_ELEMENT
 281 The credential already contains an element for the requested mechanism
 282 with overlapping usage and validity period.
 283 .It GSS_S_CREDENTIALS_EXPIRED
 284 The required credentials could not be added because they have expired.
 285 .It GSS_S_NO_CRED
 286 No credentials were found for the specified name.
 287 .El
 288 .Sh SEE ALSO
 289 .Xr gss_accept_sec_context 3 ,
 290 .Xr gss_acquire_cred 3 ,
 291 .Xr gss_init_sec_context 3 ,
 292 .Xr gss_inquire_context 3 ,
 293 .Xr gss_inquire_cred 3 ,
 294 .Xr gss_release_cred 3 ,
 295 .Xr gss_release_oid_set 3
 296 .Sh STANDARDS
 297 .Bl -tag -width ".It RFC 2743"
 298 .It RFC 2743
 299 Generic Security Service Application Program Interface Version 2, Update 1
 300 .It RFC 2744
 301 Generic Security Service API Version 2 : C-bindings
 302 .El
 303 .Sh HISTORY
 304 The
 305 .Nm
 306 function first appeared in
 307 .Fx 7.0 .
 308 .Sh AUTHORS
 309 John Wray, Iris Associates
 310 .Sh COPYRIGHT
 311 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 312 .Pp
 313 This document and translations of it may be copied and furnished to
 314 others, and derivative works that comment on or otherwise explain it
 315 or assist in its implementation may be prepared, copied, published
 316 and distributed, in whole or in part, without restriction of any
 317 kind, provided that the above copyright notice and this paragraph are
 318 included on all such copies and derivative works.  However, this
 319 document itself may not be modified in any way, such as by removing
 320 the copyright notice or references to the Internet Society or other
 321 Internet organizations, except as needed for the purpose of
 322 developing Internet standards in which case the procedures for
 323 copyrights defined in the Internet Standards process must be
 324 followed, or as required to translate it into languages other than
 325 English.
 326 .Pp
 327 The limited permissions granted above are perpetual and will not be
 328 revoked by the Internet Society or its successors or assigns.
 329 .Pp
 330 This document and the information contained herein is provided on an
 331 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 332 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 333 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 334 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 335 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.